Switching the stream from parallel() to sequential() worked in the initial Stream API design, but caused many problems and finally the implementation was changed, so it just turns the parallel flag on and off for the whole pipeline. The current documentation is indeed vague, but it was improved in Java-9:
The stream pipeline is executed sequentially or in parallel depending on the mode of the stream on which the terminal operation is invoked. The sequential or parallel mode of a stream can be determined with the BaseStream.isParallel() method, and the stream's mode can be modified with the BaseStream.sequential() and BaseStream.parallel() operations. The most recent sequential or parallel mode setting applies to the execution of the entire stream pipeline.
Overview Threads and locks are a software-defined formalization of the hardware underneath, and as such comprise the simplest possible concurrency model. It forms the basis of other concurrency abstractions built on top of it, so it’s important to understand in this regards. However, it’s difficult or impossible to build reliable, scalable systems directly on these primitives. While most every language has support for threads and locks, CPython remains special in its use of a global interpreter lock that prevents threads from concurrently accessing shared memory, because CPython’s memory management is not thread-safe.
R. Okuta, Y. Unno, D. Nishino, S. Hido, and C. Loomis. Proceedings of Workshop on Machine Learning Systems (LearningSys) in The Thirty-first Annual Conference on Neural Information Processing Systems (NIPS), (2017)
G. Amdahl. Proceedings of the April 18-20, 1967, Spring Joint Computer Conference, page 483–485. New York, NY, USA, Association for Computing Machinery, (1967)
Z. Zhao, B. Wu, M. Zhou, Y. Ding, J. Sun, X. Shen, and Y. Wu. Proceedings of the 2014 ACM International Conference on Object Oriented Programming Systems Languages & Applications, page 745--762. Association for Computing Machinery, (2014)
E. Rawashdeh, M. Qatawneh, and H. Ofeishat. International Journal of Computer Science and Information Technology (IJCSIT), 9 (5):
29 - 37(October 2017)
D. Terpstra, H. Jagode, H. You, and J. Dongarra. Tools for High Performance Computing 2009, page 157--173. Berlin, Heidelberg, Springer Berlin Heidelberg, (2010)
D. Chang, A. Desoky, M. Ouyang, and E. Rouchka. 2009 10th ACIS International Conference on Software Engineering, Artificial Intelligences, Networking and Parallel/Distributed Computing, page 501--506. IEEE, (2009)
Y. Liu, T. Pan, and S. Aluru. 2016 28th International Symposium on Computer Architecture and High Performance Computing (SBAC-PAD), page 141--149. IEEE, (2016)
B. Baker, O. Gupta, R. Raskar, and N. Naik. (2017)cite arxiv:1705.10823Comment: Submitted to International Conference on Learning Representations, (2018).
S. Syed, A. Bouchard-Côté, G. Deligiannidis, and A. Doucet. (2019)cite arxiv:1905.02939Comment: 61 pages, 18 figures. The method is implemented in an open source probabilistic programming available at https://github.com/UBC-Stat-ML/blangSDK.