1.1 --- a/README.txt Wed Sep 30 00:53:07 2009 +0200
1.2 +++ b/README.txt Sat Oct 10 01:52:27 2009 +0200
1.3 @@ -1,227 +1,51 @@
1.4 -Optimisations
1.5 -=============
1.6 -
1.7 -Some optimisations around constant objects might be possible; these depend on
1.8 -the following:
1.9 -
1.10 - * Reliable tracking of assignments: where assignment operations occur, the
1.11 - target of the assignment should be determined if any hope of optimisation
1.12 - is to be maintained. Where no guarantees can be made about the target of
1.13 - an assignment, no assignment-related information should be written to
1.14 - potential targets.
1.15 -
1.16 - * Objects acting as "containers" of attributes must be regarded as "safe":
1.17 - where assignments are recorded as occurring on an attribute, it must be
1.18 - guaranteed that no other unforeseen ways exist to assign to such
1.19 - attributes.
1.20 -
1.21 -The discussion below presents certain rules which must be imposed to uphold
1.22 -the above requirements.
1.23 -
1.24 -Safe Containers
1.25 ----------------
1.26 +Introduction
1.27 +------------
1.28
1.29 -Where attributes of modules, classes and instances are only set once and are
1.30 -effectively constant, it should be possible to circumvent the attribute lookup
1.31 -mechanism and to directly reference the attribute value. This technique may
1.32 -only be considered applicable for the following "container" objects, subject
1.33 -to the noted constraints:
1.34 -
1.35 - 1. For modules, "safety" is enforced by ensuring that assignments to module
1.36 - attributes are only permitted within the module itself either at the
1.37 - top-level or via names declared as globals. Thus, the following would not
1.38 - be permitted:
1.39 -
1.40 - another_module.this_module.attr = value
1.41 -
1.42 - In the above, this_module is a reference to the current module.
1.43 -
1.44 - 2. For classes, "safety" is enforced by ensuring that assignments to class
1.45 - attributes are only permitted within the class definition, outside
1.46 - methods. This would mean that classes would be "sealed" at definition time
1.47 - (like functions).
1.48 -
1.49 -Unlike the property of function locals that they may only sensibly be accessed
1.50 -within the function in which they reside, these cases demand additional
1.51 -controls or assumptions on or about access to the stored data. Meanwhile, it
1.52 -would be difficult to detect eligible attributes on arbitrary instances due to
1.53 -the need for some kind of type inference or abstract execution.
1.54 -
1.55 -Constant Attributes
1.56 --------------------
1.57 +Micropython is a language environment incorporating a compiler for a
1.58 +simplified version of the Python programming language which targets a simple
1.59 +instruction set supported by a virtual machine known as RSVP (a Really Simple
1.60 +Virtual Processor).
1.61
1.62 -When accessed via "safe containers", as described above, any attribute with
1.63 -only one recorded assignment on it can be considered a constant attribute and
1.64 -this eligible for optimisation, the consequence of which would be the
1.65 -replacement of a LoadAttrIndex instruction (which needs to look up an
1.66 -attribute using the run-time details of the "container" and the compile-time
1.67 -details of the attribute) with a LoadAttr instruction.
1.68 -
1.69 -However, some restrictions exist on assignment operations which may be
1.70 -regarded to cause only one assignment in the lifetime of a program:
1.71 -
1.72 - 1. For module attributes, only assignments at the top-level outside loop
1.73 - statements can be reliably assumed to cause only a single assignment.
1.74 +The RSVP instruction set is intended to map relatively closely to instructions
1.75 +employed by real processors, with only a few "macroinstructions" which would
1.76 +probably be implemented as short macros or library routines in programs
1.77 +translated to the instruction set of a real target processor.
1.78
1.79 - 2. For class attributes, only assignments at the top-level within class
1.80 - definitions and outside loop statements can be reliably assumed to cause
1.81 - only a single assignment.
1.82 -
1.83 -All assignments satisfying the "safe container" requirements, but not the
1.84 -requirements immediately above, should each be recorded as causing at least
1.85 -one assignment.
1.86 -
1.87 -Additional Controls
1.88 --------------------
1.89 -
1.90 -For the above cases for "container" objects, the following controls would need
1.91 -to apply:
1.92 +Quick Start
1.93 +-----------
1.94
1.95 - 1. Modules would need to be immutable after initialisation. However, during
1.96 - initialisation, there remains a possibility of another module attempting
1.97 - to access the original module. For example, if ppp/__init__.py contained
1.98 - the following...
1.99 -
1.100 - x = 1
1.101 - import ppp.qqq
1.102 - print x
1.103 -
1.104 - ...and if ppp/qqq.py contained the following...
1.105 -
1.106 - import ppp
1.107 - ppp.x = 2
1.108 +Currently, the test.py program is the principal means of compiling and running
1.109 +code. For example, to inspect the logical.py test program...
1.110
1.111 - ...then the value 2 would be printed. Since modules are objects which are
1.112 - registered globally in a program, it would be possible to set attributes
1.113 - in the above way.
1.114 + python -i test.py tests/logical.py -m
1.115
1.116 - 2. Classes would need to be immutable after initialisation. However, since
1.117 - classes are objects, any reference to a class after initialisation could
1.118 - be used to set attributes on the class.
1.119 -
1.120 -Solutions:
1.121 -
1.122 - 1. Insist on global scope for module attribute assignments.
1.123 -
1.124 - 2. Insist on local scope within classes.
1.125 +...will provide a number of objects which can then be inspected, notably the
1.126 +rm (RSVP machine) object which provides the following methods:
1.127
1.128 -Both of the above measures need to be enforced at run-time, since an arbitrary
1.129 -attribute assignment could be attempted on any kind of object, yet to uphold
1.130 -the properties of "safe containers", attempts to change attributes of such
1.131 -objects should be denied. Since foreseen attribute assignment operations have
1.132 -certain properties detectable at compile-time, it could be appropriate to
1.133 -generate special instructions (or modified instructions) during the
1.134 -initialisation of modules and classes for such foreseen assignments, whilst
1.135 -employing normal attribute assignment operations in all other cases. Indeed,
1.136 -the StoreAttr instruction, which is used to set attributes in "safe
1.137 -containers" would be used exclusively for this purpose; the StoreAttrIndex
1.138 -instruction would be used exclusively for all other attribute assignments.
1.139 -
1.140 -To ensure the "sealing" of modules and classes, entries in the attribute
1.141 -lookup table would encode whether a class or module is being accessed, so
1.142 -that the StoreAttrIndex instruction could reject such accesses.
1.143 -
1.144 -Constant Attribute Values
1.145 --------------------------
1.146 -
1.147 -Where an attribute value is itself regarded as constant, is a "safe container"
1.148 -and is used in an operation accessing its own attributes, the value can be
1.149 -directly inspected for optimisations or employed in the generated code. For
1.150 -the attribute values themselves, only objects of a constant nature may be
1.151 -considered suitable for this particular optimisation:
1.152 + * show - reveals the contents of the machine's memory
1.153 + * run - starts execution of the code in the memory
1.154 + * step - steps through the code one instruction at a time
1.155 + * dump - shows the machine's registers
1.156
1.157 - * Classes
1.158 - * Modules
1.159 - * Instances defined as constant literals
1.160 +To run a test and check the output, specify the -t option:
1.161
1.162 -This is because arbitrary objects (such as most instances) have no
1.163 -well-defined form before run-time and cannot be investigated further at
1.164 -compile-time or have a representation inserted into the generated code.
1.165 -
1.166 -Class Attributes and Access via Instances
1.167 ------------------------------------------
1.168 -
1.169 -Unlike module attributes, class attributes can be accessed in a number of
1.170 -different ways:
1.171 + python test.py tests/logical.py -t
1.172
1.173 - * Using the class itself:
1.174 -
1.175 - C.x = 123
1.176 - cls = C; cls.x = 234
1.177 -
1.178 - * Using a subclass of the class (for reading attributes):
1.179 +To run all tests, use the test_all.py program:
1.180
1.181 - class D(C):
1.182 - pass
1.183 - D.x # setting D.x would populate D, not C
1.184 -
1.185 - * Using instances of the class or a subclass of the class (for reading
1.186 - attributes):
1.187 -
1.188 - c = C()
1.189 - c.x # setting c.x would populate c, not C
1.190 + python test_all.py
1.191
1.192 -Since assignments are only achieved using direct references to the class, and
1.193 -since class attributes should be defined only within the class initialisation
1.194 -process, the properties of class attributes should be consistent with those
1.195 -desired.
1.196 -
1.197 -Method Access via Instances
1.198 ----------------------------
1.199 -
1.200 -It is desirable to optimise method access, even though most method calls are
1.201 -likely to occur via instances. It is possible, given the properties of methods
1.202 -as class attributes to investigate the kind of instance that the self
1.203 -parameter/local refers to within each method: it should be an instance either
1.204 -of the class in which the method is defined or a compatible class, although
1.205 -situations exist where this might not be the case:
1.206 -
1.207 - * Explicit invocation of a method:
1.208 -
1.209 - d = D() # D is not related to C
1.210 - C.f(d) # calling f(self) in C
1.211 -
1.212 -If blatant usage of incompatible instances were somehow disallowed, it would
1.213 -still be necessary to investigate the properties of an instance's class and
1.214 -its relationship with other classes. Consider the following example:
1.215 -
1.216 - class A:
1.217 - def f(self): ...
1.218 -
1.219 - class B:
1.220 - def f(self): ...
1.221 - def g(self):
1.222 - self.f()
1.223 +Both programs support optimisations either using the -o flag immediately
1.224 +followed (no space or separator) by a comma-separated list of options (defined
1.225 +in the docs/optimisations.txt document) or by specifying -omax to apply all
1.226 +possible optimisations.
1.227
1.228 - class C(A, B):
1.229 - pass
1.230 -
1.231 -Here, instances of B passed into the method B.g could be assumed to provide
1.232 -access to B.f when self.f is resolved at compile-time. However, instances of C
1.233 -passed into B.g would instead provide access to A.f when self.f is resolved at
1.234 -compile-time (since the method resolution order is C, A, B instead of just B).
1.235 +Contact, Copyright and Licence Information
1.236 +------------------------------------------
1.237
1.238 -One solution might be to specialise methods for each instance type, but this
1.239 -could be costly. Another less ambitious solution might only involve the
1.240 -optimisation of such internal method calls if an unambiguous target can be
1.241 -resolved.
1.242 -
1.243 -Narrowing Type Candidates using Attribute Names
1.244 ------------------------------------------------
1.245 +The current Web page for micropython at the time of release is:
1.246
1.247 -Within functions, it might be useful to record attribute accesses on local
1.248 -names and to collect the names in order to help resolve targets in the
1.249 -generated code. For example:
1.250 +http://www.boddie.org.uk/python/micropython.html
1.251
1.252 - def f(x, y):
1.253 - x.method(y)
1.254 - if x.something:
1.255 - ...
1.256 - return x.attr
1.257 -
1.258 -Here, the object referenced via x should have "method", "something" and "attr"
1.259 -as attributes. We could impose a test for a type providing these attributes at
1.260 -the earliest opportunity and then specialise the attribute accesses, perhaps
1.261 -also invocations, in the generated code. AttributeError occurrences would need
1.262 -to be considered, however, potentially disqualifying certain attributes from
1.263 -any optimisations, and control flow would also need to be considered.
1.264 +Copyright and licence information can be found in the docs directory - see
1.265 +docs/COPYING.txt and docs/gpl-3.0.txt for more information.