[pypy-svn] r54632 - pypy/dist/pypy/doc

[arigo at codespeak.net]

Author: arigo
Date: Sat May 10 19:38:44 2008
New Revision: 54632

Modified:
   pypy/dist/pypy/doc/_ref.txt
   pypy/dist/pypy/doc/garbage_collection.txt
   pypy/dist/pypy/doc/index.txt
Log:
Describe (rough sketch) each of our framework GCs.


Modified: pypy/dist/pypy/doc/_ref.txt
==============================================================================
--- pypy/dist/pypy/doc/_ref.txt	(original)
+++ pypy/dist/pypy/doc/_ref.txt	Sat May 10 19:38:44 2008
@@ -75,6 +75,10 @@
 .. _`pypy/rpython/lltypesystem/lltype.py`:
 .. _`rpython/lltypesystem/lltype.py`: ../../pypy/rpython/lltypesystem/lltype.py
 .. _`rpython/memory/`: ../../pypy/rpython/memory
+.. _`rpython/memory/gc/generation.py`: ../../pypy/rpython/memory/gc/generation.py
+.. _`rpython/memory/gc/hybrid.py`: ../../pypy/rpython/memory/gc/hybrid.py
+.. _`rpython/memory/gc/marksweep.py`: ../../pypy/rpython/memory/gc/marksweep.py
+.. _`rpython/memory/gc/semispace.py`: ../../pypy/rpython/memory/gc/semispace.py
 .. _`rpython/ootypesystem/`: ../../pypy/rpython/ootypesystem
 .. _`rpython/ootypesystem/ootype.py`: ../../pypy/rpython/ootypesystem/ootype.py
 .. _`rpython/rint.py`: ../../pypy/rpython/rint.py

Modified: pypy/dist/pypy/doc/garbage_collection.txt
==============================================================================
--- pypy/dist/pypy/doc/garbage_collection.txt	(original)
+++ pypy/dist/pypy/doc/garbage_collection.txt	Sat May 10 19:38:44 2008
@@ -5,12 +5,85 @@
 .. contents::
 .. sectnum::
 
+Introduction
+============
 
-**Warning**: The text that was in this document was incomplete and
-outdated. A much more up-to-date view of garbage collection in PyPy
-can be found in the `EU-report on this topic`_.
+**Warning**: The overview and description of our garbage collection
+strategy and framework is not here but in the `EU-report on this
+topic`_.  The present document describes the specific garbage collectors
+that we wrote in our framework.
 
 .. _`EU-report on this topic`: http://codespeak.net/pypy/extradoc/eu-report/D07.1_Massive_Parallelism_and_Translation_Aspects-2007-02-28.pdf
 
 
+Garbage collectors currently written for the GC framework
+=========================================================
 
+(Very rough sketch only for now.)
+
+Reminder: to select which GC you want to include in a translated
+RPython program, use the ``--gc=NAME`` option of ``translate.py``.
+For more details, see the `overview of command line options for
+translation`_.
+
+.. _`overview of command line options for translation`: config/commandline.html#overview-of-command-line-options-for-translation
+
+Mark and Sweep
+--------------
+
+Classical Mark and Sweep collector.  Also contains a lot of experimental
+and half-unmaintained features.  See `rpython/memory/gc/marksweep.py`_.
+
+Semispace copying collector
+---------------------------
+
+Two arenas of equal size, with only one arena in use and getting filled
+with new objects.  When the arena is full, the live objects are copied
+into the other arena using Cheney's algorithm.  The old arena is then
+cleared.  See `rpython/memory/gc/semispace.py`_.
+
+On Unix the clearing is done by reading ``/dev/zero`` into the arena,
+which is extremely memory efficient at least on Linux: it lets the
+kernel free the RAM that the old arena used and replace it all with
+allocated-on-demand memory.
+
+The size of each semispace starts at 8MB but grows as needed when the
+amount of objects alive grows.
+
+Generational GC
+---------------
+
+This is a two-generations GC.  See `rpython/memory/gc/generation.py`_.
+
+It is implemented as a subclass of the Semispace copying collector.  It
+adds a nursery, which is a chunk of the current semispace.  Its size is
+computed to be half the size of the CPU Level 2 cache.  Allocations fill
+the nursery, and when it is full, it is collected and the objects still
+alive are moved to the rest of the current semispace.
+
+The idea is that it is very common for objects to die soon after they
+are created.  Generational GCs help a lot in this case, particularly if
+the amount of live objects really manipulated by the program fits in the
+Level 2 cache.  Moreover, the semispaces fill up much more slowly,
+making full collections less frequent.
+
+Hybrid GC
+---------
+
+This is a three-generations GC.
+
+It is implemented as a subclass of the Generational GC.  The Hybrid GC
+can handle both objects that are inside and objects that are outside the
+semispaces ("external").  The external objects are not moving and
+collected in a mark-and-sweep fashion.  Large objects are allocated as
+external objects to avoid costly moves.  Small objects that survive for
+a long enough time (several semispace collections) are also made
+external so that they stop moving.
+
+This is coupled with a segregation of the objects in three generations.
+Each generation is collected much less often than the previous one.  The
+division of the generations is slightly more complicated than just
+nursery / semispace / external; see the diagram at the start of the
+source code, in `rpython/memory/gc/hybrid.py`_.
+
+.. include:: _ref.txt

Modified: pypy/dist/pypy/doc/index.txt
==============================================================================
--- pypy/dist/pypy/doc/index.txt	(original)
+++ pypy/dist/pypy/doc/index.txt	Sat May 10 19:38:44 2008
@@ -136,6 +136,9 @@
 properties into our interpreter during the translation
 process. This document is also part of the `EU reports`_.
 
+`garbage collector`_ strategies that can be used by the virtual
+machines produced by the translation process.
+
 `parser`_ contains (outdated, unfinished) documentation about
 the parser.
 
@@ -271,7 +274,7 @@
 
 `rpython/ootypesystem/`_       the `object-oriented type system`_ for OO backends
 
-`rpython/memory/`_             the garbage collector construction framework
+`rpython/memory/`_             the `garbage collector`_ construction framework
 
 `tool/`_                       various utilities and hacks used from various places 
 
@@ -346,6 +349,7 @@
 .. _rtyper: rtyper.html
 .. _`low-level type system`: rtyper.html#low-level-type
 .. _`object-oriented type system`: rtyper.html#oo-type
+.. _`garbage collector`: garbage_collection.html
 .. _`Stackless Transform`: translation.html#the-stackless-transform
 .. _`PyPy Prolog Interpreter`: prolog-interpreter.html
 .. _`Prolog Interpreter`: prolog-interpreter.html