[pypy-svn] r28964 - pypy/dist/pypy/doc
antocuni at codespeak.net
antocuni at codespeak.net
Mon Jun 19 20:53:58 CEST 2006
Author: antocuni
Date: Mon Jun 19 20:53:52 2006
New Revision: 28964
Modified:
pypy/dist/pypy/doc/_ref.txt
pypy/dist/pypy/doc/rtyper.txt
Log:
Added docs about ootypesystem.
Modified: pypy/dist/pypy/doc/_ref.txt
==============================================================================
--- pypy/dist/pypy/doc/_ref.txt (original)
+++ pypy/dist/pypy/doc/_ref.txt Mon Jun 19 20:53:52 2006
@@ -52,6 +52,7 @@
.. _`pypy/rpython/extfunctable.py`: ../../pypy/rpython/extfunctable.py
.. _`pypy/rpython/lltypesystem/lltype.py`:
.. _`rpython/lltypesystem/lltype.py`: ../../pypy/rpython/lltypesystem/lltype.py
+.. _`rpython/ootypesystem/ootype.py`: ../../pypy/rpython/ootypesystem/ootype.py
.. _`rpython/memory/`: ../../pypy/rpython/memory
.. _`pypy/rpython/memory/gc.py`: ../../pypy/rpython/memory/gc.py
.. _`pypy/rpython/memory/lladdress.py`: ../../pypy/rpython/memory/lladdress.py
Modified: pypy/dist/pypy/doc/rtyper.txt
==============================================================================
--- pypy/dist/pypy/doc/rtyper.txt (original)
+++ pypy/dist/pypy/doc/rtyper.txt Mon Jun 19 20:53:52 2006
@@ -125,7 +125,7 @@
---------------
The RPython Typer uses a standard low-level model which we believe can
-correspond rather directly to various target languages from C to LLVM_ to Java.
+correspond rather directly to various target languages such as C and LLVM_.
This model is implemented in the first part of
`rpython/lltypesystem/lltype.py`_.
@@ -428,8 +428,194 @@
See for example `rpython/rlist.py`_.
+Object Oriented Types
+---------------------
+
+The standard `low-level type` model described above is fine for
+targeting low level backends such as C and LLVM, but it is not good
+enough for targeting higher level backends such as .NET CLI or Java
+JVM, so a new object oriented model has been introduced. This model is
+implemented in the first part of `rpython/ootypesystem/ootype.py`_.
+
+As for the low-level typesystem, the second part of
+`rpython/ootypesystem/ootype.py`_ is a runnable implementation of
+these types, for testing purposes.
+
+
+The target platform
++++++++++++++++++++
+
+There are plenty of object oriented languages and platforms around,
+each one with its own native features: they could be statically or
+dinamically typed, they could support or not things like multiple
+inheritance, classes and functions as first class order objects,
+generics, and so on.
+
+The goal of *ootypesystem* is to define a trade-off between all
+the potential backends that let them to use the native facilities when
+available while not preventing other backends to work when they
+aren't.
+
+
+Types and classes
++++++++++++++++++
+
+Most of the primitive types defined in *ootypesystem* are the very
+same of those found in *lltypesystem*: ``Bool``, ``Signed``,
+``Unsigned``, ``Float``, ``Char``, ``UniChar`` and ``Void``.
+
+The target platform is supposed to support classes and instances with
+**single inheritance**. Instances of user-defined classes are mapped
+to the ``Instance`` type, whose ``_superclass`` attribute indicates
+the base class of the instance. At the very beginning of the
+inheritance hierarchy there is the ``Root`` object, i.e. the common
+base class between all instances; if the target platform has the
+notion of a common base class too, the backend can choose to map the
+``Root`` class to its native equivalent.
+
+Object of ``Instance`` type can have attributes and methods:
+attributes are got and set by the ``oogetfield`` and ``oosetfield``
+operations, while method calls are expressed by the ``oosend``
+operation.
+
+Classes are passed around using the ``Class`` type: this is a first
+order class type whose only goal is to allow **runtime instantiation**
+of the class. Backends that don't support this feature natively, such
+as Java, may need to use some sort of placeholder instead.
+
+
+Static vs. dynamic typing
++++++++++++++++++++++++++
+
+The target platform is assumed to be **statically typed**, i.e. the
+type of each object is known at compile time.
+
+As usual, it is possibile to convert an object from type to type only
+under certain conditions; there is a number of predefined conversion
+between primitive types such as from ``Bool`` to ``Signed`` or from
+``Signed`` to ``Float``. For each one of these conversions there is a
+corresponding low level operation, such as ``cast_bool_to_int`` and
+``cast_int_to_float``.
+
+Moreover it is possibile to cast instances of a class up and down the
+inheritance hierarchy with the ``ooupcast`` and ``oodowncast`` low
+level operations. Implicit upcasting is not allowed, so you really
+need to do a ``ooupcast`` for converting from a subclass to a
+superclass.
+
+With this design statically typed backends can trivially insert
+appropriate casts when needed, while dynamically typed backends can
+simply ignore some of the operation such as ``ooupcast`` and
+``oodowncast``. Backends that supports implicit upcasting, such as CLI
+and Java, can simply ignore only ``ooupcast``.
+
+
+Exception handling
+++++++++++++++++++
+
+Since flow graphs are meant to be used also for very low level
+backends such as C, they are quite unstructured: this means that the
+target platform doesn't need to have a native exception handling
+mechanism, since at the very least the backend can handle exceptions
+just like ``genc`` does.
+
+By contrast we know that most of high level platforms natively support
+exception handling, so *ootypesystem* is designed to let them to use
+it. In particular the exception instances are typed with the
+``Instance`` type, so the usual inheritance exception hierarchy is
+preserved and the native way to catch exception should just work.
+
+
+Built-in types
+++++++++++++++
+
+It seems reasonable to assume high level platforms to provide built-in
+facilities for common types such as *lists* or *hashtables*.
+
+RPython standard types such as ``List`` and ``Dict`` are implemented
+on top of these common types; at the moment of writing there are six
+built-in types:
+
+ - **String**: self-descriptive
+
+ - **StringBuilder**: used for dynamic building of string
+
+ - **List**: a variable-sized, homogeneous list of object
+
+ - **Dict**: a hashtable of homogeneous keys and values
+
+ - **CustomDict**: same as dict, but with custom equal and hash
+ functions
+
+ - **DictItemsIterator**: a helper class for iterating over the
+ elements of a ``Dict``
+
+
+Each of these types is a subtype of ``BuiltinADTType`` and has set of
+ADT (Abstract Data Type) methods (hence the name of the base class)
+for being manipulated. Examples of ADT methods are ``ll_length`` for
+``List`` and ``ll_get`` for ``Dict``.
+
+From the backend point of view an instance of a built-in types is
+treated exactly as a plain ``Instance``, so usually no special-casing
+is needed. The backend is supposed to provide a bunch of classes
+wrapping the native ones in order to provide the right signature and
+semantic for the ADT methods.
+
+As an alternative, backends can special-case the ADT types to map them
+directly to the native equivalent, traslating the method names
+on-the-fly at compile time.
+
+Generics
+++++++++
+
+Some target platforms offer native support for **generics**, i.e.
+classes that can be parametrized on types, not only values. For
+example, if one wanted to create a list using generics, a possible
+declaration would be to say ``List<T>``, where ``T`` represented the
+type. When instantiated, one could create ``List<Integer>`` or
+``List<Animal>``. The list is then treated as a list of whichever type
+is specified.
+
+Each subclass of ``BuiltinADTTypes`` defines a bunch of type
+parameters by creating some class level placeholder in the form of
+``PARAMNAME_T``; then it fills up the ``_GENERIC_METHODS`` attribute
+by defining the signature of each of the ADT methods using those
+placeholders in the appropriace places. As an example, here is an
+extract of *ootypesystem*'s List type::
+
+ class List(BuiltinADTType):
+ # placeholders for types
+ SELFTYPE_T = object()
+ ITEMTYPE_T = object()
+
+ ...
+
+ def _init_methods(self):
+ # 'ITEMTYPE_T' is used as a placeholder for indicating
+ # arguments that should have ITEMTYPE type. 'SELFTYPE_T' indicates 'self'
+
+ self._GENERIC_METHODS = frozendict({
+ "ll_length": Meth([], Signed),
+ "ll_getitem_fast": Meth([Signed], self.ITEMTYPE_T),
+ "ll_setitem_fast": Meth([Signed, self.ITEMTYPE_T], Void),
+ "_ll_resize_ge": Meth([Signed], Void),
+ "_ll_resize_le": Meth([Signed], Void),
+ "_ll_resize": Meth([Signed], Void),
+ })
+
+ ...
+
+Thus backends that support generics can simply look for placeholders
+for discovering where the type parameters are used. Backends that
+don't support generics can simply use the ``Root`` class instead and
+insert the appropriate casts where needed. Note that placeholders
+might also stand for primitive types, which typically require more
+involved casts: e.g. in Java, making wrapper objects around ints.
+
+
HighLevelOp interface
-+++++++++++++++++++++
+---------------------
In the absence of more extensive documentation about how RPython types are
implemented, here is the interface and intended usage of the 'hop'
@@ -555,6 +741,17 @@
interpret_raises(IndexError, raise_exception, [42])
interpret_raises(ValueError, raise_exception, [43])
+By default the ``interpret`` and ``interpret_raises`` functions use
+the low-level typesystem. If you want to use the object oriented one
+you have to set the ``type_system`` parameter to the string
+``'ootype'``::
+
+ def test_invert():
+ def f(x):
+ return ~x
+ res = interpret(f, [3], type_system='ootype')
+ assert res == ~3
+
.. _annotator: translation.html#the-annotation-pass
.. _llvm: translation.html#the-llvm-back-end
.. _`rpython typer`:
More information about the Pypy-commit
mailing list