[pypy-svn] rev 2586 - pypy/trunk/doc/overview

[jacob at codespeak.net]

Author: jacob
Date: Fri Dec 19 17:28:06 2003
New Revision: 2586

Added:
   pypy/trunk/doc/overview/
   pypy/trunk/doc/overview/architecture
Log:
Initial arcitecture description.

Added: pypy/trunk/doc/overview/architecture
==============================================================================
--- (empty file)
+++ pypy/trunk/doc/overview/architecture	Fri Dec 19 17:28:06 2003
@@ -0,0 +1,71 @@
+PyPy - an implementation of Python in Python
+
+Architecture overview
+=====================
+In its current, rather simple incarnation Pypy has 2 major parts - The
+interpreter and an object space. Both parts are implemented in Python
+and run under CPython.
+
+The Interpreter
+===============
+The interpreter accepts a Python source code file and turns it into a
+series of byte codes, which are stored in .pyc file. The byte codes
+are instructions for a virtual machine, just like with regular
+CPython.
+
+The interpreter then takes the bytecodes one by one and performs
+whatever the bytecode instructs it to do. For all operations that
+affect objects, the actual change of the object is delegated to the
+object space.
+
+The Object Space
+================
+The object space contains all objects that have been created and knows
+how to perform operations on the objects. We currently have 2 working
+object spaces which are more or less interchangeable:
+
+- The trivial object space, which is a thin wrapper around CPython
+types. It was used to test the interpreter and is used from time to
+time for testing purposes. It is currently of little interest.
+
+- The standard object space, which is an almost complete
+implementation of Python types in Python. This is the main focus of
+this document, since it is the foundation of PyPy.
+
+The Standard Object Space
+=========================
+The Standard Object Space (SOS) itself is an object which implements a
+number of logistic services. At startup the SOS examines certain
+directories for modules that contain the implementation of the available
+Python types. It loads each such module, which in turn registers its
+type and all the operations on the type in multimethods in the SOS.
+
+Later in the execution, when the interpreter delegates the execution
+of an instruction to the SOS, the correct operation to perform is
+selected through the multimethod.
+
+We will examine how the multimethod mechanism works through an example.
+
+We examine the types float and int and disregard all other types for
+the moment. Each type has an __add__ operator, which is registered
+with the SOS at startup. The float add operator is registered with the
+type signature __add__(Float, Float) and the integer add operator is
+registered with the signature __add__(Int, Int).
+
+If we in our application program write the expression 2+3, the
+interpreter will create an object containing the value 2 and an object
+containing the value 3. We annotate these as Int(2) and Int(3)
+respectively. The interpreter then calls the SOS with 
+__add__(Int(2), Int(3)).
+
+The SOS then looks in its __add__ multimethod and finds a version that
+has the signature __add__(Int, Int). Since this is a direct hit, it
+can immediately dispatch the operation to the correct method.
+
+If we don't have any registered functions with the correct signature,
+as we would if we had the expression 2+3.0, we will test if we can use
+coercion to find a function with a signature that works. In this case
+we would coerce Int(2) to Float(2.0) in order to find a function in
+the multimethod that has a correct signature.
+
+