1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/concepts.txt Mon Apr 06 01:57:40 2009 +0200
1.3 @@ -0,0 +1,189 @@
1.4 +Concepts
1.5 +========
1.6 +
1.7 + * Contexts and values
1.8 + * Tables and lookups
1.9 + * Objects and structures
1.10 +
1.11 +Contexts and Values
1.12 +===================
1.13 +
1.14 +Values are used as the common reference representation in micropython: as
1.15 +stored representations of attributes (of classes, instances, modules, and
1.16 +other objects supporting attribute-like entities) as well as the stored values
1.17 +associated with names in functions and methods.
1.18 +
1.19 +Unlike other implementations, micropython does not create things like bound
1.20 +method objects for individual instances. Instead, all objects are referenced
1.21 +using a context, reference pair:
1.22 +
1.23 +Value Layout
1.24 +------------
1.25 +
1.26 + 0 1
1.27 + context object
1.28 + reference reference
1.29 +
1.30 +Specific implementations might reverse this ordering for optimisation
1.31 +purposes.
1.32 +
1.33 +Rationale
1.34 +---------
1.35 +
1.36 +To reduce the number of created objects whilst retaining the ability to
1.37 +support bound method invocations. The context indicates the context in which
1.38 +an invocation is performed, typically the owner of the method.
1.39 +
1.40 +Usage
1.41 +-----
1.42 +
1.43 +The context may be inserted as the first argument when a value is involved in
1.44 +an invocation. This argument may then be omitted from the invocation if its
1.45 +usage is not appropriate.
1.46 +
1.47 +See invocation.txt for details.
1.48 +
1.49 +Contexts in Acquired Values
1.50 +---------------------------
1.51 +
1.52 +There are two classes of instructions which provide values:
1.53 +
1.54 + Instruction Purpose Context Operations
1.55 + ----------- ------- ------------------
1.56 +
1.57 + LoadConst Load class, function, Combine null context with
1.58 + module, constant loaded object
1.59 +
1.60 + LoadAddress Load attribute from Preserve or override stored
1.61 + LoadAddressContext class, module, context (as described in
1.62 + LoadAttr instance assignment.txt)
1.63 + LoadAttrIndex
1.64 +
1.65 +In order to comply with traditional Python behaviour, contexts may or may not
1.66 +represent the object from which an attribute has been acquired.
1.67 +
1.68 +See assignment.txt for details.
1.69 +
1.70 +Contexts in Stored Values
1.71 +-------------------------
1.72 +
1.73 +There is only one class of instruction for storing values:
1.74 +
1.75 + Instruction Purpose Context Operations
1.76 + ----------- ------- ------------------
1.77 +
1.78 + StoreAddress Store attribute in a Preserve context; note that no
1.79 + known object test for class attribute
1.80 + assignment should be necessary
1.81 + since this instruction should only
1.82 + be generated for module globals
1.83 +
1.84 + StoreAttr Store attribute in an Preserve context; note that no
1.85 + instance test for class attribute
1.86 + assignment should be necessary
1.87 + since this instruction should only
1.88 + be generated for self accesses
1.89 +
1.90 + StoreAttrIndex Store attribute in an Preserve context; since the index
1.91 + unknown object lookup could yield a class
1.92 + attribute, a test of the nature of
1.93 + the nature of the structure is
1.94 + necessary in order to prevent
1.95 + assignments to classes
1.96 +
1.97 +Note that contexts are never changed in the stored value: they are preserved.
1.98 +
1.99 +See assignment.txt for details.
1.100 +
1.101 +Tables and Lookups
1.102 +==================
1.103 +
1.104 +Attribute lookups, where the exact location of an object attribute is deduced,
1.105 +are performed differently in micropython than in other implementations.
1.106 +Instead of providing attribute dictionaries, in which attributes are found,
1.107 +attributes are located at fixed places in object structures (described below)
1.108 +and their locations are stored using a special representation known as a
1.109 +table.
1.110 +
1.111 +For a given program, a table can be considered as being like a matrix mapping
1.112 +classes to attribute names. For example:
1.113 +
1.114 + class A:
1.115 + # has attributes x, y
1.116 +
1.117 + class B(A):
1.118 + # introduces attribute z
1.119 +
1.120 + class C:
1.121 + # has attributes a, b, z
1.122 +
1.123 +This would provide the following table:
1.124 +
1.125 + Class/attr a b x y z
1.126 +
1.127 + A 1 2
1.128 + B 1 2 3
1.129 + C 1 2 3
1.130 +
1.131 +A limitation of this representation is that instance attributes may not shadow
1.132 +class attributes: if an attribute with a given name is not defined on an
1.133 +instance, an attribute with the same name cannot be provided by the class of
1.134 +the instance or any superclass of the instance's class.
1.135 +
1.136 +The table can be compacted using a representation known as a displacement
1.137 +list:
1.138 +
1.139 + Classes with attribute offsets
1.140 +
1.141 + classcode A
1.142 + attrcode a b x y z
1.143 +
1.144 + B
1.145 + a b x y z
1.146 +
1.147 + C
1.148 + a b x y z
1.149 +
1.150 + List . . 1 2 1 2 3 1 2 . . 3
1.151 +
1.152 +Here, the classcode refers to the offset in the list at which a class's
1.153 +attributes are defined, whereas the attrcode defines the offset within a
1.154 +region of attributes corresponding to a single attribute of a given name.
1.155 +
1.156 +Objects and Structures
1.157 +======================
1.158 +
1.159 +As well as references, micropython needs to have actual objects to refer to.
1.160 +Since classes, functions and instances are all objects, it is desirable that
1.161 +certain common features and operations are supported in the same way for all
1.162 +of these things. To permit this, a common data structure format is used.
1.163 +
1.164 + Identifier Identifier Address Details Type Object ...
1.165 +
1.166 + 0 1 2 3 4 5 6
1.167 + classcode attrcode invocation invocation __class__ attribute ...
1.168 + reference #args, reference reference
1.169 + defaults
1.170 + reference
1.171 +
1.172 +Here, the classcode refers to the attribute lookup table for the object (as
1.173 +described above). Since classes and instances share the same classcode, they
1.174 +might resemble the following:
1.175 +
1.176 +Class C:
1.177 +
1.178 + 0 1 2 3 4 5 6
1.179 + code for C attrcode __new__ __new__ class type attribute ...
1.180 + for C reference #args, reference reference
1.181 + defaults
1.182 + reference
1.183 +
1.184 +Instance of C:
1.185 +
1.186 + 0 1 2 3 4 5 6
1.187 + code for C attrcode C.__call__ C.__call__ class C attribute ...
1.188 + for C reference #args, reference reference
1.189 + (if exists) defaults
1.190 + reference
1.191 +
1.192 +
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/index.txt Mon Apr 06 01:57:40 2009 +0200
2.3 @@ -0,0 +1,4 @@
2.4 +Documentation Index
2.5 +===================
2.6 +
2.7 +concepts.txt
3.1 --- a/docs/structures.txt Sun Apr 05 17:15:59 2009 +0200
3.2 +++ b/docs/structures.txt Mon Apr 06 01:57:40 2009 +0200
3.3 @@ -1,79 +1,6 @@
3.4 Data Structures
3.5 ===============
3.6
3.7 -The fundamental "value type" is a pair of references: one pointing to the
3.8 -referenced object represented by the interchangeable value; one referring to
3.9 -the context of the referenced object, typically the object through which the
3.10 -referenced object was acquired as an attribute.
3.11 -
3.12 -Value Layout
3.13 -------------
3.14 -
3.15 - 0 1
3.16 - object context
3.17 - reference reference
3.18 -
3.19 -Such values are used as the stored representations of attributes (of classes,
3.20 -instances, modules, and other objects supporting attribute-like entities) as
3.21 -well as the stored values associated with names in functions and methods.
3.22 -
3.23 -Stored Values and Contexts
3.24 ---------------------------
3.25 -
3.26 -See assignment.txt for information about contexts and transformations.
3.27 -
3.28 -Acquiring Values
3.29 -----------------
3.30 -
3.31 -There are two classes of instructions which provide values:
3.32 -
3.33 - Instruction Purpose Context Operations
3.34 - ----------- ------- ------------------
3.35 -
3.36 - LoadConst Load class, function, Combine null context with
3.37 - module, constant loaded object
3.38 -
3.39 - LoadAddress Load attribute from Preserve or override stored
3.40 - LoadAddressContext class, module, context (as described in
3.41 - LoadAttr instance assignment.txt)
3.42 - LoadAttrIndex
3.43 -
3.44 -Storing Values
3.45 ---------------
3.46 -
3.47 -There is only one class of instruction for storing values:
3.48 -
3.49 - Instruction Purpose Context Operations
3.50 - ----------- ------- ------------------
3.51 -
3.52 - StoreAddress Store attribute in a Preserve context; note that no
3.53 - known object test for class attribute
3.54 - assignment should be necessary
3.55 - since this instruction should only
3.56 - be generated for module globals
3.57 -
3.58 - StoreAttr Store attribute in an Preserve context; note that no
3.59 - instance test for class attribute
3.60 - assignment should be necessary
3.61 - since this instruction should only
3.62 - be generated for self accesses
3.63 -
3.64 - StoreAttrIndex Store attribute in an Preserve context; since the index
3.65 - unknown object lookup could yield a class
3.66 - attribute, a test of the nature of
3.67 - the nature of the structure is
3.68 - necessary in order to prevent
3.69 - assignments to classes
3.70 -
3.71 -Note that contexts are never changed in the stored value: they are preserved.
3.72 -See assignment.txt for more information.
3.73 -
3.74 -Objects
3.75 --------
3.76 -
3.77 -Since classes, functions and instances are all "objects", each must support
3.78 -certain features and operations in the same way.
3.79 -
3.80 The __class__ Attribute
3.81 -----------------------
3.82
3.83 @@ -95,36 +22,6 @@
3.84 Structure Layout
3.85 ----------------
3.86
3.87 -A suitable structure layout might be something like this:
3.88 -
3.89 - Identifier Identifier Address Details Type Object ...
3.90 -
3.91 - 0 1 2 3 4 5 6
3.92 - classcode attrcode invocation invocation __class__ attribute ...
3.93 - reference #args, reference reference
3.94 - defaults
3.95 - reference
3.96 -
3.97 -Here, the classcode refers to the attribute lookup table for the object. Since
3.98 -classes and instances share the same classcode, they might resemble the
3.99 -following:
3.100 -
3.101 -Class C:
3.102 -
3.103 - 0 1 2 3 4 5 6
3.104 - code for C attrcode __new__ __new__ class type attribute ...
3.105 - for C reference #args, reference reference
3.106 - defaults
3.107 - reference
3.108 -
3.109 -Instance of C:
3.110 -
3.111 - 0 1 2 3 4 5 6
3.112 - code for C attrcode C.__call__ C.__call__ class C attribute ...
3.113 - for C reference #args, reference reference
3.114 - (if exists) defaults
3.115 - reference
3.116 -
3.117 The __new__ reference would lead to code consisting of the following
3.118 instructions:
3.119
4.1 --- a/tests/call_func.py Sun Apr 05 17:15:59 2009 +0200
4.2 +++ b/tests/call_func.py Mon Apr 06 01:57:40 2009 +0200
4.3 @@ -7,12 +7,4 @@
4.4 f(1, b=2, c=3)
4.5 f(c=3, b=2, a=1)
4.6
4.7 -g = f
4.8 -g(1, c=3, b=2)
4.9 -
4.10 -def g(a, c, b):
4.11 - pass
4.12 -
4.13 -g(1, c=3, b=2)
4.14 -
4.15 # vim: tabstop=4 expandtab shiftwidth=4
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
5.2 +++ b/tests/call_func_uncertain.py Mon Apr 06 01:57:40 2009 +0200
5.3 @@ -0,0 +1,14 @@
5.4 +#!/usr/bin/env python
5.5 +
5.6 +def f(a, b, c):
5.7 + pass
5.8 +
5.9 +g = f
5.10 +g(1, c=3, b=2)
5.11 +
5.12 +def g(a, c, b):
5.13 + pass
5.14 +
5.15 +g(1, c=3, b=2)
5.16 +
5.17 +# vim: tabstop=4 expandtab shiftwidth=4
6.1 --- a/tests/call_instance.py Sun Apr 05 17:15:59 2009 +0200
6.2 +++ b/tests/call_instance.py Mon Apr 06 01:57:40 2009 +0200
6.3 @@ -5,6 +5,6 @@
6.4 return "called"
6.5
6.6 c = C()
6.7 -c()
6.8 +result = c()
6.9
6.10 # vim: tabstop=4 expandtab shiftwidth=4
7.1 --- a/tests/call_instance2.py Sun Apr 05 17:15:59 2009 +0200
7.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
7.3 @@ -1,15 +0,0 @@
7.4 -#!/usr/bin/env python
7.5 -
7.6 -class C:
7.7 - def __call__(self):
7.8 - return "called"
7.9 -
7.10 -class D:
7.11 - def __init__(self, x):
7.12 - self.x = x
7.13 -
7.14 -c = C()
7.15 -d = D(c)
7.16 -d.x()
7.17 -
7.18 -# vim: tabstop=4 expandtab shiftwidth=4
8.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
8.2 +++ b/tests/call_instance_attribute.py Mon Apr 06 01:57:40 2009 +0200
8.3 @@ -0,0 +1,15 @@
8.4 +#!/usr/bin/env python
8.5 +
8.6 +class C:
8.7 + def __call__(self):
8.8 + return "called"
8.9 +
8.10 +class D:
8.11 + def __init__(self, x):
8.12 + self.x = x
8.13 +
8.14 +c = C()
8.15 +d = D(c)
8.16 +result = d.x()
8.17 +
8.18 +# vim: tabstop=4 expandtab shiftwidth=4