[pypy-svn] r16458 - pypy/dist/pypy/doc
cfbolz at codespeak.net
cfbolz at codespeak.net
Thu Aug 25 12:44:37 CEST 2005
Author: cfbolz
Date: Thu Aug 25 12:44:35 2005
New Revision: 16458
Modified:
pypy/dist/pypy/doc/architecture.txt
pypy/dist/pypy/doc/coding-guide.txt
pypy/dist/pypy/doc/getting-started.txt
pypy/dist/pypy/doc/interpreter.txt
pypy/dist/pypy/doc/objspace.txt
pypy/dist/pypy/doc/theory.txt
pypy/dist/pypy/doc/translation.txt
Log:
Tried to consistently use the term "bytecode interpreter" in our whole
documentation.
Modified: pypy/dist/pypy/doc/architecture.txt
==============================================================================
--- pypy/dist/pypy/doc/architecture.txt (original)
+++ pypy/dist/pypy/doc/architecture.txt Thu Aug 25 12:44:35 2005
@@ -92,7 +92,7 @@
The *standard interpreter* is the subsystem implementing the Python language.
It is divided in two components:
-- the `plain interpreter`_ which is responsible for interpreting
+- the `bytecode interpreter`_ which is responsible for interpreting
code objects and implementing bytecodes,
- the `standard object space`_ which implements creation, access and
@@ -102,12 +102,14 @@
(the C Implementation of Python led by Guido van Rossum), if one is
willing to pay for the double-interpretation performance penalty.
+XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Please note that we are using the term *interpreter* most often in
reference to the *plain interpreter* which just knows enough to read,
dispatch and implement *bytecodes* thus shuffling objects around on the
stack and between namespaces. The (plain) interpreter is completely
ignorant of how to access, modify or construct objects and their
structure and thus delegates such operations to a so called `Object Space`_.
+XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
In addition, the standard interpreter requires a parser and bytecode compiler
to turn the user's Python source code into a form amenable to
@@ -123,7 +125,7 @@
is done in four steps:
- producing a *flow graph* representation of the standard interpreter.
- A combination of a `plain interpreter`_ and a *flow object space*
+ A combination of a `bytecode interpreter`_ and a *flow object space*
performs *abstract interpretation* to record the flow of objects
and execution throughout a python program into such a *flow graph*.
@@ -138,7 +140,7 @@
See below for the `translation process in more details`_.
-.. _`plain interpreter`:
+.. _`bytecode interpreter`:
The Bytecode Interpreter
=========================
@@ -179,7 +181,7 @@
All object-space operations take and return `application-level`_ objects.
There are only a few, very simple, object-space operation which allows the
-interpreter to gain some knowledge about the value of an
+bytecode interpreter to gain some knowledge about the value of an
application-level object.
The most important one is ``is_true()``, which returns a boolean
interpreter-level value. This is necessary to implement, for example,
@@ -187,13 +189,13 @@
conditional-branching bytecodes into which if-statements get compiled).
We currently have four working object spaces which can be plugged into
-the interpreter:
+the bytecode interpreter:
.. _`standard object space`:
- The *Standard Object Space* is a complete implementation
of the various built-in types and objects of Python. The Standard Object
- Space, together with the interpreter, is the foundation of our Python
+ Space, together with the bytecode interpreter, is the foundation of our Python
implementation. Internally, it is a set of `interpreter-level`_ classes
implementing the various `application-level`_ objects -- integers, strings,
lists, types, etc. To draw a comparison with CPython, the Standard Object
@@ -210,9 +212,9 @@
globally replaces an object with another.
- the *Flow Object Space* transforms a Python program into a
- flow-graph representation, by recording all operations that the interpreter
- would like to perform when it is shown the given Python program. This
- technique is explained `later in this document`_.
+ flow-graph representation, by recording all operations that the bytecode
+ interpreter would like to perform when it is shown the given Python
+ program. This technique is explained `later in this document`_.
For a description of the object spaces, please see the
`objspace document`_. The sources of PyPy contain the various object spaces
@@ -348,8 +350,8 @@
==============================================
One of PyPy's now-short-term objectives is to enable translation of our
-interpreter and standard object space into a lower-level language. In
-order for our translation and type inference mechanisms to work
+bytecode interpreter and standard object space into a lower-level language.
+In order for our translation and type inference mechanisms to work
effectively, we need to restrict the dynamism of our interpreter-level
Python code at some point. However, in the start-up phase, we are
completely free to use all kind of nice python constructs, including
@@ -359,7 +361,7 @@
adhere to a more static subset of Python:
Restricted Python, also known as `RPython`_.
-The Flow Object Space then, with the help of our plain interpreter,
+The Flow Object Space then, with the help of our bytecode interpreter,
works through those initialized RPython code objects. The result of
this `abstract interpretation`_ is a flow graph: yet another
representation of a python program, but one which is suitable for
Modified: pypy/dist/pypy/doc/coding-guide.txt
==============================================================================
--- pypy/dist/pypy/doc/coding-guide.txt (original)
+++ pypy/dist/pypy/doc/coding-guide.txt Thu Aug 25 12:44:35 2005
@@ -363,7 +363,7 @@
Operations on ``w_xxx``
-----------------------
-The core interpreter considers wrapped objects as black boxes.
+The core bytecode interpreter considers wrapped objects as black boxes.
It is not allowed to inspect them directly. The allowed
operations are all implemented on the object space: they are
called ``space.xxx()``, where ``xxx`` is a standard operation
@@ -387,13 +387,13 @@
Building ``w_xxx`` objects
--------------------------
-From the core interpreter, wrapped objects are usually built as the result of
+From the bytecode interpreter, wrapped objects are usually built as the result of
an object space operation. The ways to directly create a wrapped object are:
* ``space.wrap(x)``: returns a wrapped object containing the
value ``x``. Only works if ``x`` is either a simple value
(integer, float, string) or an instance of an internal
- interpreter class (Function, Code, Frame...).
+ bytecode interpreter class (Function, Code, Frame...).
* ``space.newlist([w_x, w_y, w_z...])``: returns a wrapped
list from a list of already-wrapped objects.
@@ -424,7 +424,7 @@
Inspecting and unwrapping ``w_xxx`` objects
--------------------------------------------
-The most delicate operation is for the interpreter to inspect
+The most delicate operation is for the bytecode interpreter to inspect
a wrapped object, which must be done via the object space.
* ``space.is_true(w_x)``: checks if the given wrapped object
Modified: pypy/dist/pypy/doc/getting-started.txt
==============================================================================
--- pypy/dist/pypy/doc/getting-started.txt (original)
+++ pypy/dist/pypy/doc/getting-started.txt Thu Aug 25 12:44:35 2005
@@ -421,12 +421,12 @@
relative to the PyPy toplevel directory). You may look at our `directory reference`_
or start off at one of the following points:
-* `pypy/interpreter`_ contains the basic interpreter: bytecode dispatcher
+* `pypy/interpreter`_ contains the bytecode interpreter: bytecode dispatcher
in pyopcode.py_, frame and code objects in eval.py_ and pyframe.py_,
function objects and argument passing in function.py_ and argument.py_,
the object space interface definition in baseobjspace.py_, modules in
- module.py_ and mixedmodule.py_. Core types supporting the interpreter are
- defined in typedef.py_.
+ module.py_ and mixedmodule.py_. Core types supporting the bytecode
+ interpreter are defined in typedef.py_.
* `pypy/objspace/std`_ contains the `Standard object space`_. The main file
is objspace.py_. For each type, the files ``xxxtype.py`` and
@@ -435,7 +435,8 @@
* `pypy/objspace`_ contains a few other object spaces: the thunk_
one, the trace_ one, the flow_ one. The latter is a relatively short piece
- of code that builds the control flow graphs when the interpreter runs in it.
+ of code that builds the control flow graphs when the bytecode interpreter
+ runs in it.
* `pypy/translator`_ contains the code analysis and generation stuff.
Start reading from translator.py_, from which it should be easy to follow
Modified: pypy/dist/pypy/doc/interpreter.txt
==============================================================================
--- pypy/dist/pypy/doc/interpreter.txt (original)
+++ pypy/dist/pypy/doc/interpreter.txt Thu Aug 25 12:44:35 2005
@@ -55,7 +55,7 @@
transparent invocation of application-level helpers
(``app2interp``) at interpreter-level.
-Another task of the interpreter is to expose its basic
+Another task of the bytecode interpreter is to expose its basic
code, frame, module and function objects to application-level
code. Such runtime introspection and modification abilities are
implemented via `interpreter descriptors`_ (also see Raymond Hettingers
@@ -84,8 +84,8 @@
.. _`application level exceptions`: coding-guide.html#applevel-exceptions
-Interpreter Implementation Classes
-======================================
+Bytecode Interpreter Implementation Classes
+===========================================
.. _`Frame class`:
@@ -357,7 +357,7 @@
------------------------------
Python traditionally has a very far-reaching introspection model
-for interpreter related objects. In PyPy and in CPython read
+for bytecode interpreter related objects. In PyPy and in CPython read
and write accesses to such objects are routed to descriptors.
Of course, in CPython those are implemented in ``C`` while in
PyPy they are implemented in interpreter-level Python code.
Modified: pypy/dist/pypy/doc/objspace.txt
==============================================================================
--- pypy/dist/pypy/doc/objspace.txt (original)
+++ pypy/dist/pypy/doc/objspace.txt Thu Aug 25 12:44:35 2005
@@ -73,7 +73,11 @@
---------------------------------------
**wrap(x):**
- Returns a wrapped object that is a reference to the interpreter-level object x. This can be used either on simple immutable objects (integers, strings...) to create a new wrapped object, or on complex mutable objects to obtain an application-level-visible reference to them (e.g. instances of internal interpreter classes).
+ Returns a wrapped object that is a reference to the interpreter-level object
+ x. This can be used either on simple immutable objects (integers,
+ strings...) to create a new wrapped object, or on complex mutable objects to
+ obtain an application-level-visible reference to them (e.g. instances of
+ internal bytecode interpreter classes).
**newbool(b):**
Creates a Bool Object from an interpreter level object.
@@ -103,7 +107,8 @@
Return Interpreter Level equivalent of w_x
**interpclass_w(w_x):**
- If w_x is a wrapped instance of an interpreter class -- for example Function, Frame, Cell, etc. -- return it unwrapped. Otherwise return None.
+ If w_x is a wrapped instance of an bytecode interpreter class -- for example
+ Function, Frame, Cell, etc. -- return it unwrapped. Otherwise return None.
**int_w(w_x):**
If w_x is an application-level integer or long which can be converted without overflow to an integer, return an interpreter-level integer. Otherwise raise TypeError or OverflowError.
@@ -158,7 +163,17 @@
The Standard Object Space (StdObjSpace_) is the direct equivalent of CPython's object library (the "Objects/" subdirectory in the distribution). It is an implementation of the common Python types in a lower-level language.
-The Standard Object Space defines an abstract parent class, W_Object, and a bunch of subclasses like W_IntObject, W_ListObject, and so on. A wrapped object (a "black box" for the interpreter main loop) is thus an instance of one of these classes. When the main loop invokes an operation, say the addition, between two wrapped objects w1 and w2, the Standard Object Space does some internal dispatching (similar to "Object/abstract.c" in CPython) and invokes a method of the proper W_XyzObject class that can do the operation. The operation itself is done with the primitives allowed by RestrictedPython. The result is constructed as a wrapped object again. For example, compare the following implementation of integer addition with the function "int_add()" in "Object/intobject.c": ::
+The Standard Object Space defines an abstract parent class, W_Object, and a
+bunch of subclasses like W_IntObject, W_ListObject, and so on. A wrapped
+object (a "black box" for the bytecode interpreter main loop) is thus an
+instance of one of these classes. When the main loop invokes an operation, say
+the addition, between two wrapped objects w1 and w2, the Standard Object Space
+does some internal dispatching (similar to "Object/abstract.c" in CPython) and
+invokes a method of the proper W_XyzObject class that can do the
+operation. The operation itself is done with the primitives allowed by
+RestrictedPython. The result is constructed as a wrapped object again. For
+example, compare the following implementation of integer addition with the
+function "int_add()" in "Object/intobject.c": ::
def add__Int_Int(space, w_int1, w_int2):
x = w_int1.intval
@@ -282,9 +297,10 @@
The task of the FlowObjSpace_ is to generate a control-flow graph from a function. This graph will also contain a trace of the individual operations, so that it is actually just an alternate representation for the function.
-The FlowObjSpace is an object space, which means that it exports the standard object space interface and it is driven by the interpreter.
+The FlowObjSpace is an object space, which means that it exports the standard
+object space interface and it is driven by the bytecode interpreter.
-The basic idea is that if the interpreter is given a function, e.g.::
+The basic idea is that if the bytecode interpreter is given a function, e.g.::
def f(n):
return 3*n+2
@@ -293,7 +309,10 @@
.. _`Abstract Interpretation`: theory.html#abstract-interpretation
-For example, if the placeholder ``v1`` is given as the argument to the above function, the interpreter will call ``v2 = space.mul(space.wrap(3), v1)`` and then ``v3 = space.add(v2, space.wrap(2))`` and return ``v3`` as the result. During these calls the FlowObjSpace will record a basic block::
+For example, if the placeholder ``v1`` is given as the argument to the above
+function, the bytecode interpreter will call ``v2 = space.mul(space.wrap(3),
+v1)`` and then ``v3 = space.add(v2, space.wrap(2))`` and return ``v3`` as the
+result. During these calls the FlowObjSpace will record a basic block::
Block(v1): # input argument
v2 = mul(Constant(3), v1)
@@ -378,11 +397,27 @@
How the FlowObjSpace works
--------------------------
-The FlowObjSpace works by recording all operations issued by the interpreter into basic blocks. A basic block ends in one of two cases: when the interpreters calls ``is_true()``, or when a joinpoint is reached.
-
-* A joinpoint occurs when the next operation is about to be recorded into the current block, but there is already another block that records an operation for the same bytecode position. This means that the interpreter has closed a loop and is interpreting already-seen code again. In this situation, we interrupt the interpreter and we make a link from the end of the current block back to the previous block, thus closing the loop in the flow graph as well. (Note that this occurs only when an operation is about to be recorded, which allows some amount of constant-folding.)
-
-* If the interpreter calls ``is_true()``, the FlowObjSpace doesn't generally know if the answer should be True or False, so it puts a conditional jump and generates two successor blocks for the current basic block. There is some trickery involved so that the interpreter is fooled into thinking that ``is_true()`` first returns False (and the subsequent operations are recorded in the first successor block), and later the *same* call to ``is_true()`` also returns True (and the subsequent operations go this time to the other successor block).
+The FlowObjSpace works by recording all operations issued by the bytecode
+interpreter into basic blocks. A basic block ends in one of two cases: when
+the bytecode interpreters calls ``is_true()``, or when a joinpoint is reached.
+
+* A joinpoint occurs when the next operation is about to be recorded into the
+ current block, but there is already another block that records an operation
+ for the same bytecode position. This means that the bytecode interpreter
+ has closed a loop and is interpreting already-seen code again. In this
+ situation, we interrupt the bytecode interpreter and we make a link from the
+ end of the current block back to the previous block, thus closing the loop
+ in the flow graph as well. (Note that this occurs only when an operation is
+ about to be recorded, which allows some amount of constant-folding.)
+
+* If the bytecode interpreter calls ``is_true()``, the FlowObjSpace doesn't
+ generally know if the answer should be True or False, so it puts a
+ conditional jump and generates two successor blocks for the current basic
+ block. There is some trickery involved so that the bytecode interpreter is
+ fooled into thinking that ``is_true()`` first returns False (and the
+ subsequent operations are recorded in the first successor block), and later
+ the *same* call to ``is_true()`` also returns True (and the subsequent
+ operations go this time to the other successor block).
(This section to be extended...)
Modified: pypy/dist/pypy/doc/theory.txt
==============================================================================
--- pypy/dist/pypy/doc/theory.txt (original)
+++ pypy/dist/pypy/doc/theory.txt Thu Aug 25 12:44:35 2005
@@ -10,11 +10,21 @@
Abstract Interpretation
=======================
-Abstract Interpretation is a general technique which consists of an interpreter that follows the bytecode instructions of a user program, just like a normal interpreter does, but with abstract objects instead of concrete ones. Remember that in PyPy this is done by using alternate object spaces with the same interpreter main loop.
+Abstract Interpretation is a general technique which consists of an
+interpreter that follows the bytecode instructions of a user program, just
+like a normal interpreter does, but with abstract objects instead of concrete
+ones. Remember that in PyPy this is done by using alternate object spaces with
+the same bytecode interpreter main loop.
As a theoretical example, the most abstract object space would be the one manipulating the most abstract objects that you could imagine: they are all equivalent, because we have abstracted away any information about the object. There is actually only one of them left, and we could call it "the object". In Python terms, an AbstractObjectSpace could use None for all its wrapped objects. Any operation between wrapped objects gives None again as the wrapped result -- there is nothing else it could give anyway. So when you have said that the add method of AbstractObjectSpace takes None and None and returns None you have said everything.
-The point of such an object space is for example to check the bytecode. The interpreter will really run your bytecode, just with completely abstract arguments. If there is no problem then you are sure that the bytecode is valid. You could also record, during this abstract interpretation, how much the stack ever grows; that would give you a fool-proof method of computing or checking the co_stacksize argument of a code object. (There are subtleties which I won't describe here, but that's the basic idea.)
+The point of such an object space is for example to check the bytecode. The
+bytecode interpreter will really run your bytecode, just with completely
+abstract arguments. If there is no problem then you are sure that the bytecode
+is valid. You could also record, during this abstract interpretation, how much
+the stack ever grows; that would give you a fool-proof method of computing or
+checking the co_stacksize argument of a code object. (There are subtleties
+which I won't describe here, but that's the basic idea.)
Typically, however, abstract object spaces are a (little) bit less abstract, still maintaining a minimal amount of information about the objects. For example, a wrapped object could be represented by its type. You then define the object space's add to return int when the two arguments are int and int. That way, you abstractedly call a function with the input argument's types and what the interpreter will do is a type inference. (Here also there are subtle problems, even besides the remark that integer operations can overflow and actually return longs in a real Python implementation.)
Modified: pypy/dist/pypy/doc/translation.txt
==============================================================================
--- pypy/dist/pypy/doc/translation.txt (original)
+++ pypy/dist/pypy/doc/translation.txt Thu Aug 25 12:44:35 2005
@@ -992,11 +992,11 @@
Solution
--------
-This bootstrap issue is solved by invoking a new interpreter which
+This bootstrap issue is solved by invoking a new bytecode interpreter which
runs on FlowObjspace. FlowObjspace is complete without complicated
initialization. It is able to do abstract interpretation of any
Rpythonic code, without actually implementing anything. It just
-records all the operations the interpreter would have done by
+records all the operations the bytecode interpreter would have done by
building flowgraphs for all the code. What the Python backend does is
just to produce correct Python code from these flowgraphs and return
it as source code.
@@ -1023,8 +1023,9 @@
...
... """)
-This call has invoked a PyPy interpreter running on FlowObjspace, recorded every
-possible codepath into a flowgraph, and then rendered the following source code::
+This call has invoked a PyPy bytecode interpreter running on FlowObjspace,
+recorded every possible codepath into a flowgraph, and then rendered the
+following source code::
>>> print source
#!/bin/env python
More information about the Pypy-commit
mailing list