1 USING: definitions help.markup help.syntax kernel parser
2 quotations source-files stack-checker.errors words ;
5 ARTICLE: "compilation-units-internals" "Compilation units internals"
6 "These words do not need to be called directly, and only serve to support the implementation."
8 "Compiling a set of words:"
9 { $subsections compile }
10 "Words called to associate a definition with a compilation unit and a source file location:"
15 "Forward reference checking (see " { $link "definition-checking" } "):"
16 { $subsections forward-reference? }
17 "A hook to be called at the end of the compilation unit. If the optimizing compiler is loaded, this compiles new words with the " { $link "compiler" } ":"
18 { $subsections recompile }
19 "Low-level compiler interface exported by the Factor VM:"
20 { $subsections modify-code-heap } ;
22 ARTICLE: "compilation-units" "Compilation units"
23 "A " { $emphasis "compilation unit" } " scopes a group of related definitions. They are compiled and entered into the system in one atomic operation."
25 "When a source file is being parsed, all definitions are part of a single compilation unit, unless the " { $link POSTPONE: << } " parsing word is used to create nested compilation units."
27 "Words defined in a compilation unit may not be called until the compilation unit is finished. The parser detects this case for parsing words and throws a " { $link staging-violation } ". Similarly, an attempt to use a macro from a word defined in the same compilation unit will throw a " { $link transform-expansion-error } ". Calling any other word from within its own compilation unit throws an " { $link undefined } " error."
29 "This means that parsing words and macros generally cannot be used in the same source file as they are defined. There are two means of getting around this:"
31 { "The simplest way is to split off the parsing words and macros into sub-vocabularies; perhaps suffixed by " { $snippet ".syntax" } " and " { $snippet ".macros" } "." }
32 { "Alternatively, nested compilation units can be created using " { $link "syntax-immediate" } "." }
34 "Parsing words which create new definitions at parse time will implicitly add them to the compilation unit of the current source file."
36 "Code which creates new definitions at run time will need to explicitly create a compilation unit with a combinator. There is an additional combinator used by the parser to implement " { $link "syntax-immediate" } "."
37 { $subsections with-compilation-unit with-nested-compilation-unit }
39 { $subsections "compilation-units-internals" } ;
41 ABOUT: "compilation-units"
44 { $values { "definition" "a definition specifier" } }
45 { $description "Throws a " { $link redefine-error } "." }
46 { $error-description "Indicates that a single source file contains two definitions for the same artifact, one of which shadows the other. This is an error since it indicates a likely mistake, such as two words accidentally named the same by the developer; the error is restartable." } ;
48 HELP: remember-definition
49 { $values { "definition" "a definition specifier" } { "loc" "a " { $snippet "{ path line# }" } " pair" } }
50 { $description "Saves the location of a definition and associates this definition with the current source file." } ;
53 { $var-description "Stores a pair of sets where the members form the set of definitions which were defined by " { $link file } " the most recent time it was loaded." } ;
56 { $var-description "Stores a pair of sets where the members form the set of definitions which were defined so far by the current parsing of " { $link file } "." } ;
58 HELP: with-compilation-unit
59 { $values { "quot" quotation } }
60 { $description "Calls a quotation in a new compilation unit. The quotation can define new words and classes, as well as forget words. When the quotation returns, any changed words are recompiled, and changes are applied atomically." }
61 { $notes "Calls to " { $link with-compilation-unit } " may be nested."
63 "The parser wraps every source file in a compilation unit, so parsing words may define new words without having to perform extra work; to define new words at any other time, you must wrap your defining code with this combinator."
65 "Since compilation is relatively expensive, you should try to batch up as many definitions into one compilation unit as possible." } ;
67 HELP: with-nested-compilation-unit
68 { $values { "quot" quotation } }
69 { $description "Calls a quotation in a new compilation unit. The only difference between this word and " { $link with-compilation-unit } " is that variables used by the parser to associate definitions with source files are not rebound." }
70 { $notes "This word is used by " { $link "syntax-immediate" } " to ensure that definitions in nested blocks are correctly recorded. User code should not depend on parser internals in such a way that calling this combinator is required." } ;
73 { $values { "words" "a sequence of words" } { "alist" "an association list mapping words to compiled definitions" } }
74 { $contract "Internal word which compiles words. Called at the end of " { $link with-compilation-unit } "." } ;
76 HELP: no-compilation-unit
77 { $values { "word" word } }
78 { $description "Throws a " { $link no-compilation-unit } " error." }
79 { $error-description "Thrown when an attempt is made to define a word outside of a " { $link with-compilation-unit } " combinator." } ;
81 HELP: modify-code-heap
82 { $values { "alist" "an association list with words as keys" } { "update-existing?" boolean } { "reset-pics?" boolean } }
83 { $description "Lowest-level primitive for defining words. Associates words with code blocks in the code heap."
85 "The alist maps words to one of the following:"
87 { "a quotation - in this case, the quotation is compiled with the non-optimizing compiler and the word will call the quotation when executed." }
88 { "a 6-element array " { $snippet "{ parameters literals relocation labels code stack-frame-size }" } " - in this case, a code heap block is allocated with the given data and the word will call the code block when executed. This is used by the optimizing compiler." }
90 "If any of the redefined words may already be referenced by other words in the code heap, from outside of the compilation unit, then a scan of the code heap must be performed to update all word call sites. Passing " { $link t } " as the " { $snippet "update-existing?" } " parameter enables this code path."
92 "If classes, methods or generic words were redefined, then inline cache call sites need to be updated as well. Passing " { $link t } " as the " { $snippet "reset-pics?" } " parameter enables this code path."
95 "Manually creating a word using the non-optimizing compiler:"
97 "USING: compiler.units io ;"
98 "IN: test SYMBOL: foo"
99 "{ { foo [ \"hello!\" write nl ] } } t t modify-code-heap foo"
103 { $notes "This word is called at the end of " { $link with-compilation-unit } "." } ;
106 { $values { "words" "a sequence of words" } }
107 { $description "Compiles a set of words." } ;