1.1 --- a/docs/evaluation.txt Sun Dec 08 17:58:59 2013 +0100
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,118 +0,0 @@
1.4 -Instruction Evaluation Model
1.5 -============================
1.6 -
1.7 -Programs use a value stack containing local and temporary storage. A value
1.8 -stack pointer indicates the top of this stack. In addition, a separate stack
1.9 -is used to record the invocation frames. All stack pointers refer to the next
1.10 -address to be used by the stack, not the address of the uppermost element.
1.11 -
1.12 - Frame Stack Value Stack
1.13 - ----------- ----------- Address of Callable
1.14 - -------------------
1.15 - previous ...
1.16 - current ------> callable -----> identifier
1.17 - arg1 reference to code
1.18 - arg2
1.19 - arg3
1.20 - local4
1.21 - local5
1.22 - ...
1.23 -
1.24 -Unlike the CPython virtual machine, programs do not use a value stack
1.25 -containing the results of expression evaluations. Instead, temporary storage
1.26 -is statically allocated and employed by instructions.
1.27 -
1.28 -Loading local names and temporary values is a matter of performing
1.29 -frame-relative accesses to the value stack.
1.30 -
1.31 -Invocations and Argument Evaluation
1.32 ------------------------------------
1.33 -
1.34 -When preparing for an invocation, the caller first sets the invocation frame
1.35 -pointer. A number of locations for the arguments required by the invocation
1.36 -are then reserved. With a frame to prepare, positional arguments are added to
1.37 -the frame in order such that the first argument positions are filled. The
1.38 -names of keyword arguments are used (in the form of table index values) to
1.39 -consult the parameter table and to find the frame location in which such
1.40 -arguments are to be stored.
1.41 -
1.42 - fn(a, b, d=1, e=2, c=3) -> fn(a, b, c, d, e)
1.43 -
1.44 - Frame
1.45 - -----
1.46 -
1.47 - a a a a
1.48 - b b b b
1.49 - ___ ___ ___ --> 3
1.50 - ___ --> 1 1 | 1
1.51 - ___ | ___ --> 2 | 2
1.52 - | | |
1.53 - 1 ----------- 2 ----------- 3 -----------
1.54 -
1.55 -Conceptually, the frame can be considered as a collection of attributes, as
1.56 -seen in other kinds of structures:
1.57 -
1.58 -Frame for invocation of fn:
1.59 -
1.60 - 0 1 2 3 4 5
1.61 - code a b c d e
1.62 - reference
1.63 -
1.64 -Where arguments are specified positionally, such "attributes" are set in
1.65 -order. Keyword arguments are set using a name-to-position attribute-like
1.66 -mapping, where the position of each argument is discovered using the parameter
1.67 -table.
1.68 -
1.69 -Method Invocations
1.70 -------------------
1.71 -
1.72 -Method invocations incorporate an implicit first argument which is obtained
1.73 -from the context of the method:
1.74 -
1.75 - method(a, b, d=1, e=2, c=3) -> method(self, a, b, c, d, e)
1.76 -
1.77 - Frame
1.78 - -----
1.79 -
1.80 - context of method
1.81 - a
1.82 - b
1.83 - 3
1.84 - 1
1.85 - 2
1.86 -
1.87 -Although it could be possible to permit any object to be provided as the first
1.88 -argument, in order to optimise instance attribute access in methods, we should
1.89 -seek to restrict the object type.
1.90 -
1.91 -Verifying Supplied Arguments
1.92 -----------------------------
1.93 -
1.94 -In order to ensure a correct invocation, it is also necessary to check the
1.95 -number of supplied arguments. If the target of the invocation is known at
1.96 -compile-time, no additional instructions need to be emitted; otherwise, the
1.97 -generated code must test for the following situations:
1.98 -
1.99 - 1. That the number of supplied arguments is equal to the number of expected
1.100 - parameters.
1.101 -
1.102 - 2. That no keyword argument overwrites an existing positional parameter.
1.103 -
1.104 -Default Arguments
1.105 ------------------
1.106 -
1.107 -Some arguments may have default values which are used if no value is provided
1.108 -in an invocation. Such defaults are initialised when the function itself is
1.109 -initialised, and are used to fill in any invocation frames that are known at
1.110 -compile-time.
1.111 -
1.112 -To obtain the default values, a reference to the function object is required.
1.113 -This can be provided either in an additional frame location or in a special
1.114 -register.
1.115 -
1.116 -Tuples, Frames and Allocation
1.117 ------------------------------
1.118 -
1.119 -Using the approach where arguments are treated like attributes in some kind of
1.120 -structure, we could choose to allocate frames in places other than a stack.
1.121 -This would produce something somewhat similar to a plain tuple object.
2.1 --- a/docs/lowlevel.txt Sun Dec 08 17:58:59 2013 +0100
2.2 +++ b/docs/lowlevel.txt Sun Dec 08 18:00:53 2013 +0100
2.3 @@ -7,6 +7,11 @@
2.4 of a program. This document describes these considerations and indicates how
2.5 syspython or other technologies might represent a working program.
2.6
2.7 + * Objects and structures
2.8 + * Instantiation
2.9 + * List and tuple representations
2.10 + * Instruction evaluation model
2.11 +
2.12 Objects and Structures
2.13 ======================
2.14
2.15 @@ -239,3 +244,122 @@
2.16 main list structure. Since access to the contents of the list must go through
2.17 the main list structure, underlying allocation activities may take place
2.18 without the users of a list having to be aware of such activities.
2.19 +
2.20 +Instruction Evaluation Model
2.21 +============================
2.22 +
2.23 +Programs use a value stack containing local and temporary storage. A value
2.24 +stack pointer indicates the top of this stack. In addition, a separate stack
2.25 +is used to record the invocation frames. All stack pointers refer to the next
2.26 +address to be used by the stack, not the address of the uppermost element.
2.27 +
2.28 + Frame Stack Value Stack
2.29 + ----------- ----------- Address of Callable
2.30 + -------------------
2.31 + previous ...
2.32 + current ------> callable -----> identifier
2.33 + arg1 reference to code
2.34 + arg2
2.35 + arg3
2.36 + local4
2.37 + local5
2.38 + ...
2.39 +
2.40 +Unlike the CPython virtual machine, programs do not use a value stack
2.41 +containing the results of expression evaluations. Instead, temporary storage
2.42 +is statically allocated and employed by instructions.
2.43 +
2.44 +Loading local names and temporary values is a matter of performing
2.45 +frame-relative accesses to the value stack.
2.46 +
2.47 +Invocations and Argument Evaluation
2.48 +-----------------------------------
2.49 +
2.50 +When preparing for an invocation, the caller first sets the invocation frame
2.51 +pointer. A number of locations for the arguments required by the invocation
2.52 +are then reserved. With a frame to prepare, positional arguments are added to
2.53 +the frame in order such that the first argument positions are filled. The
2.54 +names of keyword arguments are used (in the form of table index values) to
2.55 +consult the parameter table and to find the frame location in which such
2.56 +arguments are to be stored.
2.57 +
2.58 + fn(a, b, d=1, e=2, c=3) -> fn(a, b, c, d, e)
2.59 +
2.60 + Frame
2.61 + -----
2.62 +
2.63 + a a a a
2.64 + b b b b
2.65 + ___ ___ ___ --> 3
2.66 + ___ --> 1 1 | 1
2.67 + ___ | ___ --> 2 | 2
2.68 + | | |
2.69 + 1 ----------- 2 ----------- 3 -----------
2.70 +
2.71 +Conceptually, the frame can be considered as a collection of attributes, as
2.72 +seen in other kinds of structures:
2.73 +
2.74 +Frame for invocation of fn:
2.75 +
2.76 + 0 1 2 3 4 5
2.77 + code a b c d e
2.78 + reference
2.79 +
2.80 +Where arguments are specified positionally, such "attributes" are set in
2.81 +order. Keyword arguments are set using a name-to-position attribute-like
2.82 +mapping, where the position of each argument is discovered using the parameter
2.83 +table.
2.84 +
2.85 +Method Invocations
2.86 +------------------
2.87 +
2.88 +Method invocations incorporate an implicit first argument which is obtained
2.89 +from the context of the method:
2.90 +
2.91 + method(a, b, d=1, e=2, c=3) -> method(self, a, b, c, d, e)
2.92 +
2.93 + Frame
2.94 + -----
2.95 +
2.96 + context of method
2.97 + a
2.98 + b
2.99 + 3
2.100 + 1
2.101 + 2
2.102 +
2.103 +Although it could be possible to permit any object to be provided as the first
2.104 +argument, in order to optimise instance attribute access in methods, we should
2.105 +seek to restrict the object type.
2.106 +
2.107 +Verifying Supplied Arguments
2.108 +----------------------------
2.109 +
2.110 +In order to ensure a correct invocation, it is also necessary to check the
2.111 +number of supplied arguments. If the target of the invocation is known at
2.112 +compile-time, no additional instructions need to be emitted; otherwise, the
2.113 +generated code must test for the following situations:
2.114 +
2.115 + 1. That the number of supplied arguments is equal to the number of expected
2.116 + parameters.
2.117 +
2.118 + 2. That no keyword argument overwrites an existing positional parameter.
2.119 +
2.120 +Default Arguments
2.121 +-----------------
2.122 +
2.123 +Some arguments may have default values which are used if no value is provided
2.124 +in an invocation. Such defaults are initialised when the function itself is
2.125 +initialised, and are used to fill in any invocation frames that are known at
2.126 +compile-time.
2.127 +
2.128 +To obtain the default values, a reference to the function object is required.
2.129 +This can be provided either in an additional frame location or in a special
2.130 +register.
2.131 +
2.132 +Tuples, Frames and Allocation
2.133 +-----------------------------
2.134 +
2.135 +Using the approach where arguments are treated like attributes in some kind of
2.136 +structure, we could choose to allocate frames in places other than a stack.
2.137 +This would produce something somewhat similar to a plain tuple object.