Add documentation and CHANGES

CHANGES.rst

@@ -18,6 +18,12 @@
 - Build with Cython 0.29 in '3str' mode.
 
 
+- There is new documentation on the possibility that `gevent.iwait` can produce
+  memory leaks when not fully consumed. To prevent such situations,
+  `gevent.iwait` now provides optional contextmanager support, which will ensure
+  that all resources are cleaned up. See :pr:`1290`, provided by Josh Snyder.
+
+
 1.3.7 (2018-10-12)
 ==================
 

src/gevent/_hub_primitives.py

@@ -180,6 +180,11 @@ def iwait_on_objects(objects, timeout=None, count=None):
     Iteratively yield *objects* as they are ready, until all (or *count*) are ready
     or *timeout* expired.
 
+    This function allocates resources which must be cleaned up. Consuming the
+    iterator until it is exhausted will automatically clean them up, and it is
+    also possible to use the returned object as a context manager to ensure
+    cleanup occurs.
+
     :param objects: A sequence (supporting :func:`len`) containing objects
         implementing the wait protocol (rawlink() and unlink()).
     :keyword int count: If not `None`, then a number specifying the maximum number