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

[alex at codespeak.net]

Author: alex
Date: Fri Dec 19 19:15:31 2003
New Revision: 2608

Removed:
   pypy/trunk/doc/overview/architecture
Modified:
   pypy/trunk/doc/overview/architecture.txt
Log:
close to finished, with more editing and materials, but still needs more work
to be considered a complete first draft.



Deleted: /pypy/trunk/doc/overview/architecture
==============================================================================
--- /pypy/trunk/doc/overview/architecture	Fri Dec 19 19:15:31 2003
+++ (empty file)
@@ -1,107 +0,0 @@
-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 hands it off
-to the compiler (PyPy's currently using CPython's built-in compiler)
-which turns it into a series of *byte codes* (the byte codes may be
-stored in a ``.pyc`` file, if the source code is being imported rather
-than directly run). The byte codes are instructions for a virtual
-machine, which is just the same as the one used in regular CPython.
-Each byte code is made up of an operation code (opcode) and optionally
-some operands.
-
-The interpreter then takes the bytecodes, one by one, and performs
-whatever operation each opcode instructs it to do. For all operations
-that affect or consult objects, the PyPy interpreter delegates all
-actual work on the object 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. You may think of an object
-space as being essentially a complete library implementing a fixed API,
-a set of *operations*, with implementations that correspond to giving
-some semantics to Python object types. An example of an operation might
-be *add*: add's implementations are responsible for performing numeric
-addition when add works on built-in numbers, concatenation when it
-works on built-in sequences.
-
-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. The SOS loads each such module, and, in turn, each module
-so loaded registers the type it deals with, and all the operations and
-implementations for the type, in *multimethod* objects in the SOS.
-
-Later in the execution, when the interpreter delegates the execution
-of an instruction to the SOS, the SOS selects the correct
-implementation of the operation to perform 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 in our application program we 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 delegates the operation to the ``__add__`` multimethod, which
-finds an implementation that has the signature ``__add__(Int, Int)``. Since
-this is a "direct hit", the multimethod can immediately dispatch the
-operation to the correct method, i.e., the one registered as the
-implementation for this signature.
-
-If the multimethod doesn't have any registered functions with the
-correct signature, as would be the case for example for the expression
-``2+3.0``, the multimethod tests if it 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.
-
-Application-level and interpreter-level
-=======================================
-Since the same language (Python) is what PyPy both **uses** and **deals
-with**, a given piece of Python source can be playing either of two
-rather distinct roles in the PyPy system.  To be systematic in
-distinguishing these roles, we call them *interpreter level* (Python
-used to implement the interpreter and object space) and *application
-level* (Python that we are interpreting).  To show the difference with
-an example: to sum the contents of two variables ``a`` and ``b``, typical
-application-level code is ``a+b`` -- in constrast, typical
-interpreter-level code is ``space.add(w_a, w_b)``, where ``space`` is an
-instance of the standard object space class and ``w_a`` and ``w_b`` are
-typical names for the *wrapped* versions of the two variables.
-
-
-
-Wrapping
-========
-
-barfoo
-

Modified: pypy/trunk/doc/overview/architecture.txt
==============================================================================
--- pypy/trunk/doc/overview/architecture.txt	(original)
+++ pypy/trunk/doc/overview/architecture.txt	Fri Dec 19 19:15:31 2003
@@ -111,17 +111,58 @@
 the purpose of implementing interpreter-level operations.
 
 Application-level code is much higher-level, and therefore easier to
-write and debug.  Instead of implementing a dict object's update method
-by simple, application-level code that goes something like::
-
-    def app_dict_update__ANY_ANY(d, o):
-        for k in o.keys():
-            d[k] = o[k]
-
-
+write and debug.  For example, suppose we want to implement the
+``update`` method of dict objects.  Programming at the application
+level, we can write the obvious, simple implementation, one that looks
+like an executable-pseudocode **definition** of ``update``::
+
+    def update(self, other):
+        for k in other.keys():
+            self[k] = other[k]
+
+If we had to code only at the interpreter level, we would have to
+code something much lower-level and involved, say something like::
+
+    def update(space, w_self, w_other):
+        w_keys = space.call_method(w_other, 'keys')
+        w_iter = space.iter(w_keys)
+        while True:
+            try: w_key = space.next(w_iter)
+            except NoValue: break
+            w_value = space.getitem(w_other, w_key)
+            space.setitem(w_self, w_key, w_value)
+
+This interpreter-level implementation looks much closer to the C source
+code implementing this functionality in CPython, although, depending on
+one's relative familiarity with C, Python, and PyPy's coding
+conventions, it may still be considered somewhat more readable.  In any
+case, it should be obvious that the application-level implementation is
+definitely more readable and maintainable than the interpreter-level
+one.
 
 Wrapping
 ========
 
-barfoo
+The ``w_`` prefixes so lavishly used in the previous example indicate,
+by PyPy coding convention, that we are dealing with *wrapped* objects,
+that is, objects constructed by the object space at interpreter level to
+implement corresponding application-level objects.  Each object space
+supplies ``wrap`` and ``unwrap`` operations that move between the two
+levels for objects of simple built-in types; other Python types are
+implemented by interpreter-level classes with some amount of internal
+structure.
+
+For example, an application-level Python ``list`` is implemented as an
+instance of ``W_ListObject```, which has an instance attribute
+``ob_item`` (an interpreter-level list which contains the
+application-level list's items as wrapped objects) and another attribute
+``ob_size`` which records the application-level list's length (we want
+to be able to do "over-allocation" in ``ob_item``, for the same reasons
+of performance that lead CPython to do it, and therefore the length of
+``ob_item`` is allowed to be greater than the length of the
+application-level list -- it is for this reason that the length in
+question has to be explicitly recorded in ``ob_size``).
+
+
+TODO: review and see what else we need to add!