1 Concepts
2 ========
3
4 * Contexts and values
5 * Tables, attributes and lookups
6 * Objects and structures
7 * Parameters and lookups
8 * Instantiation
9
10 Contexts and Values
11 ===================
12
13 Values are used as the common reference representation in micropython: as
14 stored representations of attributes (of classes, instances, modules, and
15 other objects supporting attribute-like entities) as well as the stored values
16 associated with names in functions and methods.
17
18 Unlike other implementations, micropython does not create things like bound
19 method objects for individual instances. Instead, all objects are referenced
20 using a context, reference pair:
21
22 Value Layout
23 ------------
24
25 0 1
26 context object
27 reference reference
28
29 Specific implementations might reverse this ordering for optimisation
30 purposes.
31
32 Rationale
33 ---------
34
35 To reduce the number of created objects whilst retaining the ability to
36 support bound method invocations. The context indicates the context in which
37 an invocation is performed, typically the owner of the method.
38
39 Usage
40 -----
41
42 The context may be inserted as the first argument when a value is involved in
43 an invocation. This argument may then be omitted from the invocation if its
44 usage is not appropriate.
45
46 See invocation.txt for details.
47
48 Contexts in Acquired Values
49 ---------------------------
50
51 There are two classes of instructions which provide values:
52
53 Instruction Purpose Context Operations
54 ----------- ------- ------------------
55
56 LoadConst Load class, function, Combine null context with
57 module, constant loaded object
58
59 LoadAddress Load attribute from Preserve or override stored
60 LoadAddressContext class, module, context (as described in
61 LoadAttr instance assignment.txt)
62 LoadAttrIndex
63
64 In order to comply with traditional Python behaviour, contexts may or may not
65 represent the object from which an attribute has been acquired.
66
67 See assignment.txt for details.
68
69 Contexts in Stored Values
70 -------------------------
71
72 There is only one class of instruction for storing values:
73
74 Instruction Purpose Context Operations
75 ----------- ------- ------------------
76
77 StoreAddress Store attribute in a Preserve context; note that no
78 known object test for class attribute
79 assignment should be necessary
80 since this instruction should only
81 be generated for module globals
82
83 StoreAttr Store attribute in an Preserve context; note that no
84 instance test for class attribute
85 assignment should be necessary
86 since this instruction should only
87 be generated for self accesses
88
89 StoreAttrIndex Store attribute in an Preserve context; since the index
90 unknown object lookup could yield a class
91 attribute, a test of the nature of
92 the nature of the structure is
93 necessary in order to prevent
94 assignments to classes
95
96 Note that contexts are never changed in the stored value: they are preserved.
97
98 See assignment.txt for details.
99
100 Tables, Attributes and Lookups
101 ==============================
102
103 Attribute lookups, where the exact location of an object attribute is deduced,
104 are performed differently in micropython than in other implementations.
105 Instead of providing attribute dictionaries, in which attributes are found,
106 attributes are located at fixed places in object structures (described below)
107 and their locations are stored using a special representation known as a
108 table.
109
110 For a given program, a table can be considered as being like a matrix mapping
111 classes to attribute names. For example:
112
113 class A:
114 # instances have attributes x, y
115
116 class B(A):
117 # introduces attribute z for instances
118
119 class C:
120 # instances have attributes a, b, z
121
122 This would provide the following table, referred to as an object table in the
123 context of classes and instances:
124
125 Class/attr a b x y z
126
127 A 1 2
128 B 1 2 3
129 C 1 2 3
130
131 A limitation of this representation is that instance attributes may not shadow
132 class attributes: if an attribute with a given name is not defined on an
133 instance, an attribute with the same name cannot be provided by the class of
134 the instance or any superclass of the instance's class.
135
136 The table can be compacted using a representation known as a displacement
137 list (referred to as an object list in this context):
138
139 Classes with attribute offsets
140
141 classcode A
142 attrcode a b x y z
143
144 B
145 a b x y z
146
147 C
148 a b x y z
149
150 List . . 1 2 1 2 3 1 2 . . 3
151
152 Here, the classcode refers to the offset in the list at which a class's
153 attributes are defined, whereas the attrcode defines the offset within a
154 region of attributes corresponding to a single attribute of a given name.
155
156 Attribute Locations
157 -------------------
158
159 The locations stored in table/list elements are for instance attributes
160 relative to the location of the instance, whereas those for class attributes
161 and modules are absolute addresses (although these could also be changed to
162 object-relative locations).
163
164 Objects and Structures
165 ======================
166
167 As well as references, micropython needs to have actual objects to refer to.
168 Since classes, functions and instances are all objects, it is desirable that
169 certain common features and operations are supported in the same way for all
170 of these things. To permit this, a common data structure format is used.
171
172 Header........................................ Attributes.................
173
174 Identifier Identifier Address Details Object Object ...
175
176 0 1 2 3 4 5 6
177 classcode attrcode invocation invocation __class__ attribute ...
178 reference #args, reference reference
179 defaults
180 reference
181
182 Here, the classcode refers to the attribute lookup table for the object (as
183 described above). Classes and instances share the same classcode, and their
184 structures reflect this. Functions all belong to the same type and thus employ
185 the classcode for the function built-in type, whereas modules have distinct
186 types since they must support different sets of attributes.
187
188 Class C:
189
190 0 1 2 3 4 5 6
191 classcode attrcode __new__ __new__ class type attribute ...
192 for C for C reference #args, reference reference
193 defaults
194 reference
195
196 Instance of C:
197
198 0 1 2 3 4 5 6
199 classcode attrcode C.__call__ C.__call__ class C attribute ...
200 for C for C reference #args, reference reference
201 (if exists) defaults
202 reference
203
204 Function f:
205
206 0 1 2 3 4 5 6
207 classcode attrcode code code class attribute ...
208 for for reference #args, function (default)
209 function function defaults reference reference
210 reference
211
212 Module m:
213
214 0 1 2 3 4 5 6
215 classcode attrcode (unused) (unused) module type attribute ...
216 for m for m reference (global)
217 reference
218
219 The __class__ Attribute
220 -----------------------
221
222 All objects support the __class__ attribute and this is illustrated above with
223 the first attribute.
224
225 Class: refers to the type class (type.__class__ also refers to the type class)
226 Function: refers to the function class
227 Instance: refers to the class instantiated to make the object
228
229 Testing Instance Compatibility with Classes (attrcode)
230 ------------------------------------------------------
231
232 Although it would be possible to have a data structure mapping classes to
233 compatible classes, such as a matrix indicating the subclasses (or
234 superclasses) of each class, the need to retain the key to such a data
235 structure for each class might introduce a noticeable overhead.
236
237 Instead of having a separate structure, descendant classes of each class are
238 inserted as special attributes into the object table. This requires an extra
239 key to be retained, since each class must provide its own attribute code such
240 that upon an instance/class compatibility test, the code may be obtained and
241 used in the object table.
242
243 Invocation and Code References
244 ------------------------------
245
246 Modules: there is no meaningful invocation reference since modules cannot be
247 explicitly called.
248
249 Functions: a simple code reference is employed pointing to code implementing
250 the function. Note that the function locals are completely distinct from this
251 structure and are not comparable to attributes. Instead, attributes are
252 reserved for default parameter values, although they do not appear in the
253 object table described above, appearing instead in a separate parameter table
254 described below.
255
256 Classes: given that classes must be invoked in order to create instances, a
257 reference must be provided in class structures. However, this reference does
258 not point directly at the __init__ method of the class. Instead, the
259 referenced code belongs to a special initialiser function, __new__, consisting
260 of the following instructions:
261
262 create instance for C
263 call C.__init__(instance, ...)
264 return instance
265
266 Instances: each instance employs a reference to any __call__ method defined in
267 the class hierarchy for the instance, thus maintaining its callable nature.
268
269 Both classes and modules may contain code in their definitions - the former in
270 the "body" of the class, potentially defining attributes, and the latter as
271 the "top-level" code in the module, potentially defining attributes/globals -
272 but this code is not associated with any invocation target. It is thus
273 generated in order of appearance and is not referenced externally.
274
275 Invocation Operation
276 --------------------
277
278 Consequently, regardless of the object an invocation is always done as
279 follows:
280
281 get invocation reference from the header
282 jump to reference
283
284 Additional preparation is necessary before the above code: positional
285 arguments must be saved in the invocation frame, and keyword arguments must be
286 resolved and saved to the appropriate position in the invocation frame.
287
288 See invocation.txt for details.
289
290 Parameters and Lookups
291 ======================
292
293 Since Python supports keyword arguments when making invocations, it becomes
294 necessary to record the parameter names associated with each function or
295 method. Just as object tables record attributes positions on classes and
296 instances, parameter tables record parameter positions in function or method
297 parameter lists.
298
299 For a given program, a parameter table can be considered as being like a
300 matrix mapping functions/methods to parameter names. For example:
301
302 def f(x, y, z):
303 pass
304
305 def g(a, b, c):
306 pass
307
308 def h(a, x):
309 pass
310
311 This would provide the following table, referred to as a parameter table in
312 the context of functions and methods:
313
314 Function/param a b c x y z
315
316 f 1 2 3
317 g 1 2 3
318 h 1 2
319
320 Just as with parameter tables, a displacement list can be prepared from a
321 parameter table:
322
323 Functions with parameter (attribute) offsets
324
325 funccode f
326 attrcode a b c x y z
327
328 g
329 a b c x y z
330
331 h
332 a b c x y z
333
334 List . . . 1 2 3 1 2 3 1 . . 2 . .
335
336 Here, the funccode refers to the offset in the list at which a function's
337 parameters are defined, whereas the attrcode defines the offset within a
338 region of attributes corresponding to a single parameter of a given name.
339
340 Instantiation
341 =============
342
343 When instantiating classes, memory must be reserved for the header of the
344 resulting instance, along with locations for the attributes of the instance.
345 Since the instance header contains data common to all instances of a class, a
346 template header is copied to the start of the newly reserved memory region.