[py-svn] r8889 - py/dist/py/documentation

[arigo at codespeak.net]

Author: arigo
Date: Sat Feb  5 00:38:17 2005
New Revision: 8889

Modified:
   py/dist/py/documentation/greenlet.txt
Log:
Document garbage-collection of greenlets.


Modified: py/dist/py/documentation/greenlet.txt
==============================================================================
--- py/dist/py/documentation/greenlet.txt	(original)
+++ py/dist/py/documentation/greenlet.txt	Sat Feb  5 00:38:17 2005
@@ -203,3 +203,25 @@
 contains an independent "main" greenlet with a tree of sub-greenlets.  It
 is not possible to mix or switch between greenlets belonging to different
 threads.
+
+Garbage-collecting live greenlets
+---------------------------------
+
+If all the references to a greenlet object go away (including the
+references from the parent attribute of other greenlets), then there is no
+way to ever switch back to this greenlet.  In this case, a GreenletExit
+exception is generated into the greenlet.  This is the only case where a
+greenlet receives the execution asynchronously.  This gives
+``try:finally:`` blocks a chance to clean up resources held by the
+greenlet.  This feature also enables a programming style in which
+greenlets are infinite loops waiting for data and processing it.  Such
+loops are automatically interrupted when the last reference to the
+greenlet goes away.
+
+The greenlet is expected to either die or be resurrected by having a new
+reference to it stored somewhere; just catching and ignoring the
+GreenletExit is likely to lead to an infinite loop.
+
+Greenlets do not participate in garbage collection; cycles involving data
+that is present in a greenlet's frames will not be detected.  Storing
+references to other greenlets cyclically may lead to leaks.