1 Concepts
2 ========
3
4 * Contexts and values
5 * Tables and lookups
6 * Objects and structures
7
8 Contexts and Values
9 ===================
10
11 Values are used as the common reference representation in micropython: as
12 stored representations of attributes (of classes, instances, modules, and
13 other objects supporting attribute-like entities) as well as the stored values
14 associated with names in functions and methods.
15
16 Unlike other implementations, micropython does not create things like bound
17 method objects for individual instances. Instead, all objects are referenced
18 using a context, reference pair:
19
20 Value Layout
21 ------------
22
23 0 1
24 context object
25 reference reference
26
27 Specific implementations might reverse this ordering for optimisation
28 purposes.
29
30 Rationale
31 ---------
32
33 To reduce the number of created objects whilst retaining the ability to
34 support bound method invocations. The context indicates the context in which
35 an invocation is performed, typically the owner of the method.
36
37 Usage
38 -----
39
40 The context may be inserted as the first argument when a value is involved in
41 an invocation. This argument may then be omitted from the invocation if its
42 usage is not appropriate.
43
44 See invocation.txt for details.
45
46 Contexts in Acquired Values
47 ---------------------------
48
49 There are two classes of instructions which provide values:
50
51 Instruction Purpose Context Operations
52 ----------- ------- ------------------
53
54 LoadConst Load class, function, Combine null context with
55 module, constant loaded object
56
57 LoadAddress Load attribute from Preserve or override stored
58 LoadAddressContext class, module, context (as described in
59 LoadAttr instance assignment.txt)
60 LoadAttrIndex
61
62 In order to comply with traditional Python behaviour, contexts may or may not
63 represent the object from which an attribute has been acquired.
64
65 See assignment.txt for details.
66
67 Contexts in Stored Values
68 -------------------------
69
70 There is only one class of instruction for storing values:
71
72 Instruction Purpose Context Operations
73 ----------- ------- ------------------
74
75 StoreAddress Store attribute in a Preserve context; note that no
76 known object test for class attribute
77 assignment should be necessary
78 since this instruction should only
79 be generated for module globals
80
81 StoreAttr Store attribute in an Preserve context; note that no
82 instance test for class attribute
83 assignment should be necessary
84 since this instruction should only
85 be generated for self accesses
86
87 StoreAttrIndex Store attribute in an Preserve context; since the index
88 unknown object lookup could yield a class
89 attribute, a test of the nature of
90 the nature of the structure is
91 necessary in order to prevent
92 assignments to classes
93
94 Note that contexts are never changed in the stored value: they are preserved.
95
96 See assignment.txt for details.
97
98 Tables and Lookups
99 ==================
100
101 Attribute lookups, where the exact location of an object attribute is deduced,
102 are performed differently in micropython than in other implementations.
103 Instead of providing attribute dictionaries, in which attributes are found,
104 attributes are located at fixed places in object structures (described below)
105 and their locations are stored using a special representation known as a
106 table.
107
108 For a given program, a table can be considered as being like a matrix mapping
109 classes to attribute names. For example:
110
111 class A:
112 # has attributes x, y
113
114 class B(A):
115 # introduces attribute z
116
117 class C:
118 # has attributes a, b, z
119
120 This would provide the following table:
121
122 Class/attr a b x y z
123
124 A 1 2
125 B 1 2 3
126 C 1 2 3
127
128 A limitation of this representation is that instance attributes may not shadow
129 class attributes: if an attribute with a given name is not defined on an
130 instance, an attribute with the same name cannot be provided by the class of
131 the instance or any superclass of the instance's class.
132
133 The table can be compacted using a representation known as a displacement
134 list:
135
136 Classes with attribute offsets
137
138 classcode A
139 attrcode a b x y z
140
141 B
142 a b x y z
143
144 C
145 a b x y z
146
147 List . . 1 2 1 2 3 1 2 . . 3
148
149 Here, the classcode refers to the offset in the list at which a class's
150 attributes are defined, whereas the attrcode defines the offset within a
151 region of attributes corresponding to a single attribute of a given name.
152
153 Objects and Structures
154 ======================
155
156 As well as references, micropython needs to have actual objects to refer to.
157 Since classes, functions and instances are all objects, it is desirable that
158 certain common features and operations are supported in the same way for all
159 of these things. To permit this, a common data structure format is used.
160
161 Identifier Identifier Address Details Type Object ...
162
163 0 1 2 3 4 5 6
164 classcode attrcode invocation invocation __class__ attribute ...
165 reference #args, reference reference
166 defaults
167 reference
168
169 Here, the classcode refers to the attribute lookup table for the object (as
170 described above). Since classes and instances share the same classcode, they
171 might resemble the following:
172
173 Class C:
174
175 0 1 2 3 4 5 6
176 code for C attrcode __new__ __new__ class type attribute ...
177 for C reference #args, reference reference
178 defaults
179 reference
180
181 Instance of C:
182
183 0 1 2 3 4 5 6
184 code for C attrcode C.__call__ C.__call__ class C attribute ...
185 for C reference #args, reference reference
186 (if exists) defaults
187 reference
188
189