[pypy-svn] r64276 - pypy/trunk/pypy/doc

arigo at codespeak.net arigo at codespeak.net
Fri Apr 17 16:01:51 CEST 2009


Author: arigo
Date: Fri Apr 17 16:01:50 2009
New Revision: 64276

Modified:
   pypy/trunk/pypy/doc/stackless.txt
Log:
Kill most of the section about "coroutine cloning".


Modified: pypy/trunk/pypy/doc/stackless.txt
==============================================================================
--- pypy/trunk/pypy/doc/stackless.txt	(original)
+++ pypy/trunk/pypy/doc/stackless.txt	Fri Apr 17 16:01:50 2009
@@ -437,86 +437,10 @@
 from a coroutine will be duplicated, and which will be shared with the
 original coroutine.
 
-For this reason, we implemented a direct cloning operation.  After some
-experiments, we determined that the following behavior is usually
-considered correct: when cloning a coroutine C, we duplicate exactly
-those objects that were created by C (i.e. while C was running).  The
-objects not created by C (e.g. pre-existing, or created outside) are not
-duplicated, but directly shared between C and its new copy.  This
-heuristic generally matches the intuition that the objects created by C
-are also the ones "owned" by C, in the sense that if C is cloned,
-the clone needs its own copy - to avoid mutating the same shared object
-in confliciting ways.  Conversely, objects of a more "global" nature, like
-modules and functions, which are typically created before the coroutine
-C started, should not be duplicated; this would result in unexpectedly
-invisible side-effects if they are mutated by the clone of C.
-
-The implementation of the above heuristic is based on support from the
-garbage collector.  For this reason, it is only available if both
-stackless and our own framework GC are compiled together in pypy-c::
-
-    cd pypy/translator/goal
-    python translate.py --stackless --gc=framework
-
-In this mode, our garbage collector is extended to support the notion of
-"pool": a pool is a linked list of allocated objects.  All objects
-allocated go to a "current" pool.  When the stackless module switches
-execution between two ClonableCoroutine objects, it switches the GC's
-current pool as well, so that the allocated objects end up segregated by
-coroutine.  Cloning is implemented by another GC extension which makes
-byte-level copies of allocated objects.  Pointers to objects inside the
-current pool cause the target objects to be recursively copied; pointers
-outside the current pool are simply shared.
-
-Two interfaces are available to clone a coroutine:
-
-* ``coro.clone()``
-
-    Clones a suspended coroutine, returning the new copy.
-
-* ``fork()``
-
-    This global function (from the ``_stackless`` module) clones the
-    currently running coroutine, returning the new copy - which, in this
-    case, is a children of the original coroutine (i.e. its parent is
-    the original coroutine).  When the parent or any other coroutine
-    eventually switches to the child, execution appears to return from
-    the same ``fork()`` call, this time with a ``None`` return value.
-
-
-Example
-~~~~~~~
-
-Forking is a natural way to implement backtracking.  Consider a
-coroutine other than the main one (the main coroutine cannot be cloned
-or forked) which issues a call to the following function::
-
-    def zero_or_one():
-        subcoro = fork()
-        if subcoro is not None:
-            try:
-                subcoro.switch()     # in the parent: run the child first
-            except Fail:
-                pass
-            return 1                 # then proceed with answer 1
-        else:
-            return 0                 # in the child: answer 0
-
-It clones the current coroutine, and switches to the new child.  In the
-latter, ``zero_or_one()`` returns 0, so the caller sees the value 0
-first.  But at any later point in time (even from a completely unrelated
-place, as long as it is still in the same coroutine) the caller may
-decide that 0 is not a suitable value, and backtrack and try again with
-the value 1.  To do so, it simply raises a Fail exception.  The
-exception stops the child coroutine, which comes back to the parent,
-where the Fail is caught and the value 1 is returned from
-``zero_or_one()``.
-
-The tests in `pypy/module/_stackless/test/test_clonable.py`_ contain an
-example using exactly the above function to search for a sequence of
-zeroes and ones that has a specific property, by trial-and-error.  This
-allow a style that looks similar to what is traditionally reserved to
-logic programming languages.
+For this reason, we implemented a direct cloning operation.  It has been
+deprecated for some time, however, as it was slightly buggy and relied
+on a specific (and deprecated) garbage collector.  It is not available
+out of the box right now, so we will not talk any more about this.
 
 
 Composability



More information about the Pypy-commit mailing list