1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/evaluation.txt Fri Sep 26 23:48:05 2008 +0200
1.3 @@ -0,0 +1,113 @@
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 ----------- 2 ----------- 3 -----------
1.53 +
1.54 +Conceptually, the frame can be considered as a collection of attributes, as
1.55 +seen in other kinds of structures:
1.56 +
1.57 +Frame for invocation of fn:
1.58 +
1.59 + 0 1 2 3 4 5
1.60 + code a b c d e
1.61 + reference
1.62 +
1.63 +However, where arguments are specified positionally, such "attributes" are not
1.64 +set using a comparable approach to that employed with other structures.
1.65 +Keyword arguments are set using an attribute-like mechanism, though, where the
1.66 +position of each argument discovered using the parameter table.
1.67 +
1.68 +Method Invocations
1.69 +------------------
1.70 +
1.71 +Method invocations incorporate an implicit first argument which is obtained
1.72 +from the context of the method:
1.73 +
1.74 + method(a, b, d=1, e=2, c=3) -> method(self, a, b, c, d, e)
1.75 +
1.76 + Frame
1.77 + -----
1.78 +
1.79 + context of method
1.80 + a
1.81 + b
1.82 + 3
1.83 + 1
1.84 + 2
1.85 +
1.86 +Although it could be possible to permit any object to be provided as the first
1.87 +argument, in order to optimise instance attribute access in methods, we should
1.88 +seek to restrict the object type.
1.89 +
1.90 +Verifying Supplied Arguments
1.91 +----------------------------
1.92 +
1.93 +In order to ensure a correct invocation, it is also necessary to check the
1.94 +number of supplied arguments. If the target of the invocation is known at
1.95 +compile-time, no additional instructions need to be emitted; otherwise, the
1.96 +generated code must test for the following situations:
1.97 +
1.98 + 1. That the number of supplied arguments is equal to the number of expected
1.99 + parameters.
1.100 +
1.101 + 2. That no keyword argument overwrites an existing positional parameter.
1.102 +
1.103 +Default Arguments
1.104 +-----------------
1.105 +
1.106 +Some arguments may have default values which are used if no value is provided
1.107 +in an invocation. Such defaults are initialised when the function itself is
1.108 +initialised, and are used to fill in any invocation frames that are known at
1.109 +compile-time.
1.110 +
1.111 +Tuples, Frames and Allocation
1.112 +-----------------------------
1.113 +
1.114 +Using the approach where arguments are treated like attributes in some kind of
1.115 +structure, we could choose to allocate frames in places other than a stack.
1.116 +This would produce something somewhat similar to a plain tuple object.