[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