PHPLIB-501: Prevent memory leaks from generators

[alcaeus]

https://jira.mongodb.org/browse/PHPLIB-501

This was discovered while investigating doctrine/mongodb-odm#2092. The different behaviour can be seen in action here: https://3v4l.org/UIfIb. Note that when we don't specifically unset the generator, it stays around much longer even though the wrapping iterator has already been garbage collected.

[jmikola]

Would it make sense to just prepare the iterator here and store the current item? That might allow you to remove the prepareIterator() calls from other methods.

As-is, there might be a subtle behavioral change, since the original implementation did rewind the traversable, create the generator, and iterate once to store the current item?

[jmikola]

Renamed the issue to reflect the actual change and title in JIRA.

Also, re: your comment in doctrine/mongodb-odm#2100 (comment), can you elaborate on the subtle behavioral change by switching to IteratorIterator? Does it relate to my earlier comment about removing the prepareIterator() call?

[alcaeus]

That is correct. When using the generator, we immediately start iterating the wrapped traversable. When switching to IteratorIterator, we can still do that (by calling rewind in the constructor), but we may want to defer starting iteration of the wrapped traversable until the wrapping iterator is starting its iteration.

[alcaeus]

PR adapted to replicate previous behaviour: iteration of the traversable starts when CachingIterator is constructed, not when iteration of CachingIterator starts.