[pypy-svn] r38280 - pypy/dist/pypy/doc
cfbolz at codespeak.net
cfbolz at codespeak.net
Fri Feb 9 18:37:49 CET 2007
Author: cfbolz
Date: Fri Feb 9 18:37:49 2007
New Revision: 38280
Modified:
pypy/dist/pypy/doc/objspace.txt
pypy/dist/pypy/doc/translation.txt
Log:
move the description of the flow model classes to translation.txt
Modified: pypy/dist/pypy/doc/objspace.txt
==============================================================================
--- pypy/dist/pypy/doc/objspace.txt (original)
+++ pypy/dist/pypy/doc/objspace.txt Fri Feb 9 18:37:49 2007
@@ -455,146 +455,10 @@
The Flow model
--------------
-``pypy.objspace.flow.model`` defines the data model used by the flow graphs, as
-created by the FlowObjSpace, manipulated by ``pypy.translator.simplify`` and
-``pypy.translator.transform``, and in general read by almost all the modules in
-``pypy.translator``.
+The data structures built up by the flow object space are described in the
+`translation document`_.
-It is recommended to play with ``python translator.py`` on a few examples to get
-an idea of the structure of flow graphs. Here is a short summary of the
-non-obvious parts.
-
-
-FunctionGraph
- A container for one graph (corresponding to one function).
-
- :startblock: the first block. It is where the control goes when the
- function is called. The input arguments of the startblock
- are the function's arguments. If the function takes a
- ``*args`` argument, the ``args`` tuple is given as the last
- input argument of the startblock.
-
- :returnblock: the (unique) block that performs a function return. It is
- empty, not actually containing any ``return`` operation; the
- return is implicit. The returned value is the unique input
- variable of the returnblock.
-
- :exceptblock: the (unique) block that raises an exception out of the
- function. The two input variables are the exception class
- and the exception value, respectively. (No other block will
- actually link to the exceptblock if the function does not
- explicitely raise exceptions.)
-
-
-Block
- A basic block, containing a list of operations and ending in jumps to other
- basic blocks. All the values that are "live" during the execution of the
- block are stored in Variables. Each basic block uses its own distinct
- Variables.
-
- :inputargs: list of fresh, distinct Variables that represent all the
- values that can enter this block from any of the previous
- blocks.
-
- :operations: list of SpaceOperations.
- :exitswitch: see below
-
- :exits: list of Links representing possible jumps from the end of this
- basic block to the beginning of other basic blocks.
-
- Each Block ends in one of the following ways:
-
- * unconditional jump: exitswitch is None, exits contains a single Link.
-
- * conditional jump: exitswitch is one of the Variables that appear in the
- Block, and exits contains one or more Links (usually 2). Each Link's
- exitcase gives a concrete value. This is the equivalent of a "switch":
- the control follows the Link whose exitcase matches the run-time value of
- the exitswitch Variable. It is a run-time error if the Variable doesn't
- match any exitcase.
-
- * exception catching: exitswitch is ``Constant(last_exception)``. The first
- Link has exitcase set to None and represents the non-exceptional path.
- The next Links have exitcase set to a subclass of Exception, and are taken
- when the *last* operation of the basic block raises a matching exception.
- (Thus the basic block must not be empty, and only the last operation is
- protected by the handler.)
-
- * return or except: the returnblock and the exceptblock have operations set
- to an empty tuple, exitswitch to None, and exits empty.
-
-
-Link
- A link from one basic block to another.
-
- :prevblock: the Block that this Link is an exit of.
-
- :target: the target Block to which this Link points to.
-
- :args: a list of Variables and Constants, of the same size as the
- target Block's inputargs, which gives all the values passed
- into the next block. (Note that each Variable used in the
- prevblock may appear zero, one or more times in the ``args``
- list.)
-
- :exitcase: see above.
-
- :last_exception: None or a Variable; see below.
-
- :last_exc_value: None or a Variable; see below.
-
- Note that ``args`` uses Variables from the prevblock, which are matched to
- the target block's ``inputargs`` by position, as in a tuple assignment or
- function call would do.
-
- If the link is an exception-catching one, the ``last_exception`` and
- ``last_exc_value`` are set to two fresh Variables that are considered to be
- created when the link is entered; at run-time, they will hold the exception
- class and value, respectively. These two new variables can only be used in
- the same link's ``args`` list, to be passed to the next block (as usual,
- they may actually not appear at all, or appear several times in ``args``).
-
-
-SpaceOperation
- A recorded (or otherwise generated) basic operation.
-
- :opname: the name of the operation. Generally one from the list in
- ``pypy.interpreter.baseobjspace``.
-
- :args: list of arguments. Each one is a Constant or a Variable seen
- previously in the basic block.
-
- :result: a *new* Variable into which the result is to be stored.
-
- Note that operations usually cannot implicitly raise exceptions at run-time;
- so for example, code generators can assume that a ``getitem`` operation on a
- list is safe and can be performed without bound checking. The exceptions to
- this rule are: (1) if the operation is the last in the block, which ends
- with ``exitswitch == Constant(last_exception)``, then the implicit
- exceptions must be checked for, generated, and caught appropriately; (2)
- calls to other functions, as per ``simple_call`` or ``call_args``, can
- always raise whatever the called function can raise --- and such exceptions
- must be passed through to the parent unless they are caught as above.
-
-
-Variable
- A placeholder for a run-time value. There is mostly debugging stuff here.
-
- :name: it is good style to use the Variable object itself instead of its
- ``name`` attribute to reference a value, although the ``name`` is
- guaranteed unique.
-
-
-Constant
- A constant value used as argument to a SpaceOperation, or as value to pass
- across a Link to initialize an input Variable in the target Block.
-
- :value: the concrete value represented by this Constant.
- :key: a hashable object representing the value.
-
- A Constant can occasionally store a mutable Python object. It represents a
- static, pre-initialized, read-only version of that object. The flow graph
- should not attempt to actually mutate such Constants.
+.. _`translation document`: translation.html#flow-model
How the FlowObjSpace works
Modified: pypy/dist/pypy/doc/translation.txt
==============================================================================
--- pypy/dist/pypy/doc/translation.txt (original)
+++ pypy/dist/pypy/doc/translation.txt Fri Feb 9 18:37:49 2007
@@ -104,16 +104,18 @@
.. _`interactive interface`: getting-started.html#try-out-the-translator
.. _`translatorshell.py`: http://codespeak.net/pypy/dist/pypy/bin/translatorshell.py
+.. _`flow model`:
+
The Flow Model
==============
-The `Flow Object Space`_ is described in detail in the `document
-describing object spaces`_, but as the data structures produced by the
-Flow Object Space are the basic data structures of the translation
-process, we quickly summarize them here.
+The `Flow Object Space`_ is described in the `document
+describing object spaces`_. Here we describe the data structures produced by it,
+which are the basic data structures of the translation
+process.
-All these types are defined in `pypy.objspace.flow.model`_ (which is the
-most imported module in the PyPy source base, to reinforce the point).
+All these types are defined in `pypy.objspace.flow.model`_ (which is a rather
+important module in the PyPy source base, to reinforce the point).
The flow graph of a function is represented by the class ``FunctionGraph``.
It contains a reference to a collection of ``Block``\ s connected by ``Link``\ s.
@@ -128,8 +130,146 @@
.. image:: image/bpnn_update.png
+It is recommended to play with ``python bin/translatorshell.py`` on a few
+examples to get an idea of the structure of flow graphs. The following describes
+the types and their attributes in some detail:
+
+
+``FunctionGraph``
+ A container for one graph (corresponding to one function).
+
+ :startblock: the first block. It is where the control goes when the
+ function is called. The input arguments of the startblock
+ are the function's arguments. If the function takes a
+ ``*args`` argument, the ``args`` tuple is given as the last
+ input argument of the startblock.
+
+ :returnblock: the (unique) block that performs a function return. It is
+ empty, not actually containing any ``return`` operation; the
+ return is implicit. The returned value is the unique input
+ variable of the returnblock.
+
+ :exceptblock: the (unique) block that raises an exception out of the
+ function. The two input variables are the exception class
+ and the exception value, respectively. (No other block will
+ actually link to the exceptblock if the function does not
+ explicitely raise exceptions.)
+
+
+``Block``
+ A basic block, containing a list of operations and ending in jumps to other
+ basic blocks. All the values that are "live" during the execution of the
+ block are stored in Variables. Each basic block uses its own distinct
+ Variables.
+
+ :inputargs: list of fresh, distinct Variables that represent all the
+ values that can enter this block from any of the previous
+ blocks.
+
+ :operations: list of SpaceOperations.
+ :exitswitch: see below
+
+ :exits: list of Links representing possible jumps from the end of this
+ basic block to the beginning of other basic blocks.
+
+ Each Block ends in one of the following ways:
+
+ * unconditional jump: exitswitch is None, exits contains a single Link.
+
+ * conditional jump: exitswitch is one of the Variables that appear in the
+ Block, and exits contains one or more Links (usually 2). Each Link's
+ exitcase gives a concrete value. This is the equivalent of a "switch":
+ the control follows the Link whose exitcase matches the run-time value of
+ the exitswitch Variable. It is a run-time error if the Variable doesn't
+ match any exitcase.
+
+ * exception catching: exitswitch is ``Constant(last_exception)``. The first
+ Link has exitcase set to None and represents the non-exceptional path.
+ The next Links have exitcase set to a subclass of Exception, and are taken
+ when the *last* operation of the basic block raises a matching exception.
+ (Thus the basic block must not be empty, and only the last operation is
+ protected by the handler.)
+
+ * return or except: the returnblock and the exceptblock have operations set
+ to an empty tuple, exitswitch to None, and exits empty.
+
+
+``Link``
+ A link from one basic block to another.
+
+ :prevblock: the Block that this Link is an exit of.
+
+ :target: the target Block to which this Link points to.
+
+ :args: a list of Variables and Constants, of the same size as the
+ target Block's inputargs, which gives all the values passed
+ into the next block. (Note that each Variable used in the
+ prevblock may appear zero, one or more times in the ``args``
+ list.)
+
+ :exitcase: see above.
+
+ :last_exception: None or a Variable; see below.
+
+ :last_exc_value: None or a Variable; see below.
+
+ Note that ``args`` uses Variables from the prevblock, which are matched to
+ the target block's ``inputargs`` by position, as in a tuple assignment or
+ function call would do.
+
+ If the link is an exception-catching one, the ``last_exception`` and
+ ``last_exc_value`` are set to two fresh Variables that are considered to be
+ created when the link is entered; at run-time, they will hold the exception
+ class and value, respectively. These two new variables can only be used in
+ the same link's ``args`` list, to be passed to the next block (as usual,
+ they may actually not appear at all, or appear several times in ``args``).
+
+
+``SpaceOperation``
+ A recorded (or otherwise generated) basic operation.
+
+ :opname: the name of the operation. The Flow Space produces only operations
+ from the list in ``pypy.interpreter.baseobjspace``, but later the
+ names can be changed arbitrarily.
+
+ :args: list of arguments. Each one is a Constant or a Variable seen
+ previously in the basic block.
+
+ :result: a *new* Variable into which the result is to be stored.
+
+ Note that operations usually cannot implicitly raise exceptions at run-time;
+ so for example, code generators can assume that a ``getitem`` operation on a
+ list is safe and can be performed without bound checking. The exceptions to
+ this rule are: (1) if the operation is the last in the block, which ends
+ with ``exitswitch == Constant(last_exception)``, then the implicit
+ exceptions must be checked for, generated, and caught appropriately; (2)
+ calls to other functions, as per ``simple_call`` or ``call_args``, can
+ always raise whatever the called function can raise --- and such exceptions
+ must be passed through to the parent unless they are caught as above.
+
+
+``Variable``
+ A placeholder for a run-time value. There is mostly debugging stuff here.
+
+ :name: it is good style to use the Variable object itself instead of its
+ ``name`` attribute to reference a value, although the ``name`` is
+ guaranteed unique.
+
+
+``Constant``
+ A constant value used as argument to a SpaceOperation, or as value to pass
+ across a Link to initialize an input Variable in the target Block.
+
+ :value: the concrete value represented by this Constant.
+ :key: a hashable object representing the value.
+
+ A Constant can occasionally store a mutable Python object. It represents a
+ static, pre-initialized, read-only version of that object. The flow graph
+ should not attempt to actually mutate such Constants.
+
.. _`document describing object spaces`: objspace.html
-.. _`pypy.objspace.flow.model`: http://codespeak.net/pypy/dist/pypy/objspace/flow/model.py
+.. _`pypy.objspace.flow.model`: ../objspace/flow/model.py
+
.. _Annotator:
More information about the Pypy-commit
mailing list