[pypy-commit] pypy stacklet: Update the doc of the module.

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: stacklet
Changeset: r46688:a042078c604e
Date: 2011-08-21 17:37 +0200
http://bitbucket.org/pypy/pypy/changeset/a042078c604e/

Log:	Update the doc of the module.

diff --git a/pypy/module/_continuation/__init__.py b/pypy/module/_continuation/__init__.py
--- a/pypy/module/_continuation/__init__.py
+++ b/pypy/module/_continuation/__init__.py
@@ -4,26 +4,29 @@
 class Module(MixedModule):
     """This module exposes 'one-shot continuation containers'.
 
-A 'continuation' object from this module is a container that stores a
+A 'continulet' object from this module is a container that stores a
 one-shot continuation.  It is similar in purpose to the 'f_back'
 attribute of frames, which points to where execution should continue
 after this frame finishes.  The difference is that it will be changed
 (often repeatedly) before the frame actually returns.
 
-To make a 'continuation' object, call 'continuation' with a callable and
-optional extra arguments.  When later you switch() to the continuation,
-the callable is invoked wih the continuation as extra first argument.
+To make a continulet object, call 'continulet' with a callable and
+optional extra arguments.  Later, the first time you switch() to the
+continulet, the callable is invoked wih the same continulet object as
+the extra first argument.
 
-At this point, the one-shot continuation stored in the continuation
-container points to the caller of switch().  When switch() is called
-again, this one-shot continuation is exchanged with the current one; it
-means that the caller of switch() is suspended, its continuation stored
-in the container, and the old continuation from the container is
-resumed.
+At this point, the one-shot continuation stored in the continulet points
+to the caller of switch().  When switch() is called again, this one-shot
+continuation is exchanged with the current one; it means that the caller
+of switch() is suspended, its continuation stored in the container, and
+the old continuation from the continulet object is resumed.
 
-Flexible frames are internally implemented using stacklets.  Stacklets
+Continulets are internally implemented using stacklets.  Stacklets
 are a bit more primitive (they are really one-shot continuations), but
 that idea only works in C, not in Python, notably because of exceptions.
+
+The most primitive API is actually 'permute()', which just permutes the
+one-shot continuation stored in two (or more) continulets.
 """
 
     appleveldefs = {