[pypy-svn] r16564 - pypy/dist/pypy/doc
hpk at codespeak.net
hpk at codespeak.net
Fri Aug 26 10:25:34 CEST 2005
Author: hpk
Date: Fri Aug 26 10:25:32 2005
New Revision: 16564
Modified:
pypy/dist/pypy/doc/_ref.txt
pypy/dist/pypy/doc/index.txt
pypy/dist/pypy/doc/interpreter.txt
Log:
- improved/refined bytecode interpreter documentation
- fixed index.txt to not link to _sre_pypy which is gone
Modified: pypy/dist/pypy/doc/_ref.txt
==============================================================================
--- pypy/dist/pypy/doc/_ref.txt (original)
+++ pypy/dist/pypy/doc/_ref.txt Fri Aug 26 10:25:32 2005
@@ -1,7 +1,8 @@
.. _`demo/`: ../../demo
.. _`lib-python/`: ../../lib-python
-.. _`annotation/`:
-.. _`pypy/annotation`: ../../pypy/annotation
+.. _`lib-python/2.4.1/dis.py`: ../../lib-python/2.4.1/dis.py
+.. _`pypy/annotation`:
+.. _`annotation/`: ../../pypy/annotation
.. _`annotation/binaryop.py`: ../../pypy/annotation/binaryop.py
.. _`doc/`: ../../pypy/doc
.. _`doc/revreport/`: ../../pypy/doc/revreport
@@ -15,23 +16,23 @@
.. _`pypy/interpreter/nestedscope.py`: ../../pypy/interpreter/nestedscope.py
.. _`pypy/interpreter/pyopcode.py`: ../../pypy/interpreter/pyopcode.py
.. _`pypy/interpreter/typedef.py`: ../../pypy/interpreter/typedef.py
-.. _`lib/`:
-.. _`pypy/lib/`: ../../pypy/lib
-.. _`lib/test2/`:
-.. _`pypy/lib/test2`: ../../pypy/lib/test2
-.. _`module/`:
-.. _`pypy/module`: ../../pypy/module
+.. _`pypy/lib/`:
+.. _`lib/`: ../../pypy/lib
+.. _`pypy/lib/test2`:
+.. _`lib/test2/`: ../../pypy/lib/test2
+.. _`pypy/module`:
+.. _`module/`: ../../pypy/module
.. _`module/__builtin__/`: ../../pypy/module/__builtin__
.. _`pypy/module/__builtin__/__init__.py`: ../../pypy/module/__builtin__/__init__.py
-.. _`module/_sre_pypy/`: ../../pypy/module/_sre_pypy
+.. _`module/_sre/`: ../../pypy/module/_sre
.. _`module/parser/`: ../../pypy/module/parser
.. _`module/recparser/`: ../../pypy/module/recparser
.. _`module/sys/`: ../../pypy/module/sys
.. _`objspace/`:
.. _`pypy/objspace`: ../../pypy/objspace
.. _`objspace/flow/`: ../../pypy/objspace/flow
-.. _`objspace/std/`:
-.. _`pypy/objspace/std`: ../../pypy/objspace/std
+.. _`pypy/objspace/std`:
+.. _`objspace/std/`: ../../pypy/objspace/std
.. _`objspace/thunk.py`: ../../pypy/objspace/thunk.py
.. _`objspace/trace.py`:
.. _`pypy/objspace/trace.py`: ../../pypy/objspace/trace.py
@@ -44,8 +45,8 @@
.. _`tool/`: ../../pypy/tool
.. _`tool/pytest/`: ../../pypy/tool/pytest
.. _`tool/tb_server/`: ../../pypy/tool/tb_server
-.. _`translator/`:
-.. _`pypy/translator`: ../../pypy/translator
+.. _`pypy/translator`:
+.. _`translator/`: ../../pypy/translator
.. _`pypy/translator/annrpython.py`: ../../pypy/translator/annrpython.py
.. _`translator/c/`: ../../pypy/translator/c
.. _`translator/java/`: ../../pypy/translator/java
Modified: pypy/dist/pypy/doc/index.txt
==============================================================================
--- pypy/dist/pypy/doc/index.txt (original)
+++ pypy/dist/pypy/doc/index.txt Fri Aug 26 10:25:32 2005
@@ -34,6 +34,7 @@
`license`_ contains licensing details (basically a straight MIT-license).
+.. _FAQ: faq.html
.. _parser: parser.html
.. _`talks and related projects`: extradoc.html
.. _`license`: http://codespeak.net/svn/pypy/dist/LICENSE
@@ -73,8 +74,7 @@
`module/`_ contains `mixed modules`_ implementing core modules with
both application and interpreter level code
-`module/_sre_pypy/`_ an experimental approach wrapping CPython's ``_sre`` module
- without using faking
+`module/_sre/`_ full regular expression implementation
`module/__builtin__/`_ full implementation of CPython's ``__builtin__`` module.
Modified: pypy/dist/pypy/doc/interpreter.txt
==============================================================================
--- pypy/dist/pypy/doc/interpreter.txt (original)
+++ pypy/dist/pypy/doc/interpreter.txt Fri Aug 26 10:25:32 2005
@@ -15,25 +15,38 @@
`Bytecode Interpreter`_ and related Virtual Machine functionalities.
PyPy's bytecode interpreter has a structure reminiscent of
-CPython's Virtual Machine: Source code is parsed and compiled
-into code objects which encapsulate information about their
-respective functions, class and module body source codes.
-Interpreting such code objects means instantiating and
-initializing a `Frame class`_ and then calling its
-``frame.eval()`` method. This entry point then interprets
-each bytecode.
+CPython's Virtual Machine: It processes code objects parsed
+and compiled from Python source code. Code objects contain
+contensed information about their respective functions, class and
+module body source codes. Interpreting such code objects means
+instantiating and initializing a `Frame class`_ and then
+calling its ``frame.eval()`` method. This main entry point
+initialise appropriate namespaces and then interprets each
+bytecode instruction. Python's standard library contains
+the `lib-python/2.4.1/dis.py`_ module which allows to view
+the Virtual's machine bytecode instructions::
+
+ >>> import dis
+ >>> def f(x):
+ return x + 1
+ >>> dis.dis(f)
+ 4 0 LOAD_FAST 0 (x)
+ 3 LOAD_CONST 1 (1)
+ 6 BINARY_ADD
+ 7 RETURN_VALUE
CPython as well as PyPy are stack-based virtual machines, i.e.
they don't have registers but put object to and pull objects
from a stack. The bytecode interpreter is only responsible
for implementing control flow and putting and pulling black
-box objects to and from the value stack. It does not know how
-to perform operations on those black box (`wrapped`_) objects
-for which it delegates to the `object space`_. In order to
-implement a branch in a program's execution, however, it needs
-to gain minimal knowledge about a wrapped object. Thus, each
-object space has to offer a ``is_true(w_obj)`` operation which
-returns an interpreter-level boolean value.
+box objects to and from this value stack. The bytecode interpreter
+does not know how to perform operations on those black box
+(`wrapped`_) objects for which it delegates to the `object
+space`_. In order to implement a conditional branch in a program's
+execution, however, it needs to gain minimal knowledge about a
+wrapped object. Thus, each object space has to offer a
+``is_true(w_obj)`` operation which returns an
+interpreter-level boolean value.
For the understanding of the interpreter's inner workings it
is crucial to recognize the concepts of `interpreter-level and
@@ -55,25 +68,26 @@
transparent invocation of application-level helpers
(``app2interp``) at interpreter-level.
-Another task of the bytecode interpreter is to expose its basic
-code, frame, module and function objects to application-level
+Another task of the bytecode interpreter is to care for exposing 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
`how-to guide for descriptors`_ in Python, PyPy uses this model extensively).
-A significant complexity lies in `argument parsing`_. Python as a
-language offers very flexible ways of providing and receiving arguments
+A significant complexity lies in `function argument parsing`_. Python as a
+language offers flexible ways of providing and receiving arguments
for a particular function invocation. Not only does it take special care
to get this right, it also presents difficulties for the `annotation
pass`_ which performs a whole-program analysis on the
bytecode interpreter, argument parsing and gatewaying code
-in order to infer the types of all flowing values.
+in order to infer the types of all values flowing across function
+calls.
It is for this reason that PyPy resorts to generate
specialized frame classes and functions at `initialization
-time`_ in order to let the annotator only see static program
-flows with homogenous name-value assignments on e.g. function
-invocations.
+time`_ in order to let the annotator only see rather static
+program flows with homogenous name-value assignments on
+function invocations.
.. _`how-to guide for descriptors`: http://users.rcn.com/python/download/Descriptor.htm
.. _`annotation pass`: translation.html#the-annotation-pass
@@ -85,8 +99,7 @@
Bytecode Interpreter Implementation Classes
-===========================================
-
+================================================
.. _`Frame class`:
.. _`Frame`:
@@ -94,8 +107,8 @@
Frame classes
-----------------
-The concept of Frames is pervasive in executing programs and
-virtual machines in particular. They are sometimes called
+The concept of Frames is pervasive in executing programs and
+on virtual machines in particular. They are sometimes called
*execution frame* because they hold crucial information
regarding the execution of a Code_ object, which in turn is
often directly related to a Python `Function`_. Frame
@@ -104,7 +117,7 @@
- the local scope holding name-value bindings, usually implemented
via a "fast scope" which is an array of wrapped objects
-- a blockstack which has (nested) information regarding the
+- a blockstack containing (nested) information regarding the
control flow of a function (such as ``while`` and ``try`` constructs)
- a value stack where bytecode interpretation pulls object
@@ -190,7 +203,7 @@
the function given an `Arguments`_ class instance.
.. _Arguments:
-.. _`argument parsing`:
+.. _`function argument parsing`:
Arguments Class
--------------------
@@ -232,12 +245,14 @@
* ``__file__`` the source filename from which this module was instantiated
* ``__path__`` state used for relative imports
-Apart from the basic Module used for importing application-level files
-there is a more refined ``MixedModule`` class (see `pypy/interpreter/mixedmodule.py`_)
-which allows to define name-value bindings both at application level
-and at interpreter level. See the ``__builtin__`` module's
-`pypy/module/__builtin__/__init__.py`_ file for an example
-and the higher level `chapter on Modules in the coding guide`_.
+Apart from the basic Module used for importing
+application-level files there is a more refined
+``MixedModule`` class (see `pypy/interpreter/mixedmodule.py`_)
+which allows to define name-value bindings both at application
+level and at interpreter level. See the ``__builtin__``
+module's `pypy/module/__builtin__/__init__.py`_ file for an
+example and the higher level `chapter on Modules in the coding
+guide`_.
.. _`__builtin__ module`: http://codespeak.net/svn/pypy/dist/pypy/module/
.. _`chapter on Modules in the coding guide`: coding-guide.html#modules
@@ -248,12 +263,13 @@
----------------------
A unique PyPy property is the ability to easily cross the barrier
-between interpreted code and machine-level code. Both codes are
-implemented via Python source code but they usually look differently.
+between interpreted and machine-level code (often refered to as
+the difference between `interpreter-level and application-level`_).
Be aware that the according code (in `pypy/interpreter/gateway.py`_)
-for crossing the barrier in both directions is somewhat involved, mostly
-due to the fact that the type-infering annotator needs to keep
-track of the types of objects flowing across those barriers.
+for crossing the barrier in both directions is somewhat
+involved, mostly due to the fact that the type-infering
+annotator needs to keep track of the types of objects flowing
+across those barriers.
Making interpreter-level functions available at application-level
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
More information about the Pypy-commit
mailing list