# HG changeset patch # User Paul Boddie # Date 1386522053 -3600 # Node ID 5d8bc0f435248e148c4de530b2fb826320563a16 # Parent 3260064f3fae9f0f34403a8bdf27844e3006fced Moved the evaluation document into the low-level concepts document. diff -r 3260064f3fae -r 5d8bc0f43524 docs/evaluation.txt --- a/docs/evaluation.txt Sun Dec 08 17:58:59 2013 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,118 +0,0 @@ -Instruction Evaluation Model -============================ - -Programs use a value stack containing local and temporary storage. A value -stack pointer indicates the top of this stack. In addition, a separate stack -is used to record the invocation frames. All stack pointers refer to the next -address to be used by the stack, not the address of the uppermost element. - - Frame Stack Value Stack - ----------- ----------- Address of Callable - ------------------- - previous ... - current ------> callable -----> identifier - arg1 reference to code - arg2 - arg3 - local4 - local5 - ... - -Unlike the CPython virtual machine, programs do not use a value stack -containing the results of expression evaluations. Instead, temporary storage -is statically allocated and employed by instructions. - -Loading local names and temporary values is a matter of performing -frame-relative accesses to the value stack. - -Invocations and Argument Evaluation ------------------------------------ - -When preparing for an invocation, the caller first sets the invocation frame -pointer. A number of locations for the arguments required by the invocation -are then reserved. With a frame to prepare, positional arguments are added to -the frame in order such that the first argument positions are filled. The -names of keyword arguments are used (in the form of table index values) to -consult the parameter table and to find the frame location in which such -arguments are to be stored. - - fn(a, b, d=1, e=2, c=3) -> fn(a, b, c, d, e) - - Frame - ----- - - a a a a - b b b b - ___ ___ ___ --> 3 - ___ --> 1 1 | 1 - ___ | ___ --> 2 | 2 - | | | - 1 ----------- 2 ----------- 3 ----------- - -Conceptually, the frame can be considered as a collection of attributes, as -seen in other kinds of structures: - -Frame for invocation of fn: - - 0 1 2 3 4 5 - code a b c d e - reference - -Where arguments are specified positionally, such "attributes" are set in -order. Keyword arguments are set using a name-to-position attribute-like -mapping, where the position of each argument is discovered using the parameter -table. - -Method Invocations ------------------- - -Method invocations incorporate an implicit first argument which is obtained -from the context of the method: - - method(a, b, d=1, e=2, c=3) -> method(self, a, b, c, d, e) - - Frame - ----- - - context of method - a - b - 3 - 1 - 2 - -Although it could be possible to permit any object to be provided as the first -argument, in order to optimise instance attribute access in methods, we should -seek to restrict the object type. - -Verifying Supplied Arguments ----------------------------- - -In order to ensure a correct invocation, it is also necessary to check the -number of supplied arguments. If the target of the invocation is known at -compile-time, no additional instructions need to be emitted; otherwise, the -generated code must test for the following situations: - - 1. That the number of supplied arguments is equal to the number of expected - parameters. - - 2. That no keyword argument overwrites an existing positional parameter. - -Default Arguments ------------------ - -Some arguments may have default values which are used if no value is provided -in an invocation. Such defaults are initialised when the function itself is -initialised, and are used to fill in any invocation frames that are known at -compile-time. - -To obtain the default values, a reference to the function object is required. -This can be provided either in an additional frame location or in a special -register. - -Tuples, Frames and Allocation ------------------------------ - -Using the approach where arguments are treated like attributes in some kind of -structure, we could choose to allocate frames in places other than a stack. -This would produce something somewhat similar to a plain tuple object. diff -r 3260064f3fae -r 5d8bc0f43524 docs/lowlevel.txt --- a/docs/lowlevel.txt Sun Dec 08 17:58:59 2013 +0100 +++ b/docs/lowlevel.txt Sun Dec 08 18:00:53 2013 +0100 @@ -7,6 +7,11 @@ of a program. This document describes these considerations and indicates how syspython or other technologies might represent a working program. + * Objects and structures + * Instantiation + * List and tuple representations + * Instruction evaluation model + Objects and Structures ====================== @@ -239,3 +244,122 @@ main list structure. Since access to the contents of the list must go through the main list structure, underlying allocation activities may take place without the users of a list having to be aware of such activities. + +Instruction Evaluation Model +============================ + +Programs use a value stack containing local and temporary storage. A value +stack pointer indicates the top of this stack. In addition, a separate stack +is used to record the invocation frames. All stack pointers refer to the next +address to be used by the stack, not the address of the uppermost element. + + Frame Stack Value Stack + ----------- ----------- Address of Callable + ------------------- + previous ... + current ------> callable -----> identifier + arg1 reference to code + arg2 + arg3 + local4 + local5 + ... + +Unlike the CPython virtual machine, programs do not use a value stack +containing the results of expression evaluations. Instead, temporary storage +is statically allocated and employed by instructions. + +Loading local names and temporary values is a matter of performing +frame-relative accesses to the value stack. + +Invocations and Argument Evaluation +----------------------------------- + +When preparing for an invocation, the caller first sets the invocation frame +pointer. A number of locations for the arguments required by the invocation +are then reserved. With a frame to prepare, positional arguments are added to +the frame in order such that the first argument positions are filled. The +names of keyword arguments are used (in the form of table index values) to +consult the parameter table and to find the frame location in which such +arguments are to be stored. + + fn(a, b, d=1, e=2, c=3) -> fn(a, b, c, d, e) + + Frame + ----- + + a a a a + b b b b + ___ ___ ___ --> 3 + ___ --> 1 1 | 1 + ___ | ___ --> 2 | 2 + | | | + 1 ----------- 2 ----------- 3 ----------- + +Conceptually, the frame can be considered as a collection of attributes, as +seen in other kinds of structures: + +Frame for invocation of fn: + + 0 1 2 3 4 5 + code a b c d e + reference + +Where arguments are specified positionally, such "attributes" are set in +order. Keyword arguments are set using a name-to-position attribute-like +mapping, where the position of each argument is discovered using the parameter +table. + +Method Invocations +------------------ + +Method invocations incorporate an implicit first argument which is obtained +from the context of the method: + + method(a, b, d=1, e=2, c=3) -> method(self, a, b, c, d, e) + + Frame + ----- + + context of method + a + b + 3 + 1 + 2 + +Although it could be possible to permit any object to be provided as the first +argument, in order to optimise instance attribute access in methods, we should +seek to restrict the object type. + +Verifying Supplied Arguments +---------------------------- + +In order to ensure a correct invocation, it is also necessary to check the +number of supplied arguments. If the target of the invocation is known at +compile-time, no additional instructions need to be emitted; otherwise, the +generated code must test for the following situations: + + 1. That the number of supplied arguments is equal to the number of expected + parameters. + + 2. That no keyword argument overwrites an existing positional parameter. + +Default Arguments +----------------- + +Some arguments may have default values which are used if no value is provided +in an invocation. Such defaults are initialised when the function itself is +initialised, and are used to fill in any invocation frames that are known at +compile-time. + +To obtain the default values, a reference to the function object is required. +This can be provided either in an additional frame location or in a special +register. + +Tuples, Frames and Allocation +----------------------------- + +Using the approach where arguments are treated like attributes in some kind of +structure, we could choose to allocate frames in places other than a stack. +This would produce something somewhat similar to a plain tuple object.