SI-6409 Stream flatMap leaks memory if mapper returns many empties

Added Scaladoc explaining that this is necessary behavior, but closed ticket as wontfix.

1 files changed, 8 insertions, 0 deletions

diff --git a/src/library/scala/collection/immutable/Stream.scala b/src/library/scala/collection/immutable/Stream.scala
index 60de147477..d3ff5e8abf 100644
--- a/src/library/scala/collection/immutable/Stream.scala
+++ b/src/library/scala/collection/immutable/Stream.scala
@@ -97,6 +97,14 @@ import scala.language.implicitConversions
  *  If, on the other hand, there is nothing holding on to the head (e.g. we used
  *  `def` to define the `Stream`) then once it is no longer being used directly,
  *  it disappears.
+ *
+ *  - Note that some operations, including [[drop]], [[dropWhile]],
+ *  [[flatMap]] or [[collect]] may process a large number of intermediate
+ *  elements before returning.  These necessarily hold onto the head, since
+ *  they are methods on `Stream`, and a stream holds its own head.  For
+ *  computations of this sort where memoization is not desired, use
+ *  `Iterator` when possible.
+ *
  *  {{{
  *  // For example, let's build the natural numbers and do some silly iteration
  *  // over them.