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.
In an earlier post I mentioned that one goal of the new introductory curriculum at Carnegie Mellon is to teach parallelism as the general case of computing, rather than an esoteric, specialized subject for advanced students. Many people are incredulous when I tell them this, because it immediately conjures in their mind the myriad complexities…
R. Okuta, Y. Unno, D. Nishino, S. Hido, и 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, стр. 483–485. New York, NY, USA, Association for Computing Machinery, (1967)
Z. Zhao, B. Wu, M. Zhou, Y. Ding, J. Sun, X. Shen, и Y. Wu. Proceedings of the 2014 ACM International Conference on Object Oriented Programming Systems Languages & Applications, стр. 745--762. Association for Computing Machinery, (2014)
D. Terpstra, H. Jagode, H. You, и J. Dongarra. Tools for High Performance Computing 2009, стр. 157--173. Berlin, Heidelberg, Springer Berlin Heidelberg, (2010)