diff --git a/basis/compiler/tree/tree-docs.factor b/basis/compiler/tree/tree-docs.factor index ef98930318..3d15f35de4 100644 --- a/basis/compiler/tree/tree-docs.factor +++ b/basis/compiler/tree/tree-docs.factor @@ -11,6 +11,9 @@ HELP: #alien-node HELP: #alien-invoke { $class-description "SSA tree node that calls a function in a dynamically linked library." } ; +HELP: #alien-callback +{ $class-description "SSA tree node that constructs an alien callback." } ; + HELP: #call { $class-description "SSA tree node that calls a word. It has the following slots:" { $table diff --git a/basis/stack-checker/alien/alien-docs.factor b/basis/stack-checker/alien/alien-docs.factor index 14f4e89639..6b67babaf9 100644 --- a/basis/stack-checker/alien/alien-docs.factor +++ b/basis/stack-checker/alien/alien-docs.factor @@ -10,6 +10,10 @@ HELP: alien-node-params } } ; +HELP: alien-callback-params +{ $class-description "Class that holds the parameter types and return value type of an alien callback call." } +{ $see-also #alien-callback } ; + HELP: param-prep-quot { $values { "params" alien-node-params } { "quot" quotation } } { $description "Builds a quotation which coerces values on the stack to the required types for the alien call." } @@ -21,5 +25,37 @@ HELP: param-prep-quot } } ; +HELP: callback-parameter-quot +{ $values { "params" alien-node-params } } +{ $description "Builds a quotation which coerces values on the stack to the required types for an alien callback. This word is essentially the opposite to " { $link param-prep-quot } "." } +{ $examples + { $unchecked-example + "USING: alien.c-types prettyprint stack-checker.alien ;" + "T{ alien-node-params { parameters { c-string } } } callback-parameter-quot ." + "[ { object } declare [ ] dip \ utf8 alien>string ]" + } +} ; + HELP: infer-alien-invoke { $description "Appends the necessary SSA nodes for performing an " { $link alien-invoke } " call to the IR tree being constructed." } ; + +HELP: wrap-callback-quot +{ $values { "params" alien-node-params } { "quot" quotation } } +{ $description "Wraps the given quotation in protective packaging so that it becomes suitable to be used as an alien callback. That means that the parameters are unpacked from C types to Factor types and, if the callback returns something, the top data stack item is afterwards converted to a C compatible value." } +{ $examples + "Here a callback that returns the length of a " { $link c-string } " is wrapped:" + { $unchecked-example + "USING: alien.c-types prettyprint stack-checker.alien ;" + "T{ alien-node-params { return int } { parameters { c-string } } } " + "[ length ] wrap-callback-quot ." + "[" + " [" + " { object } declare [ ] dip \ utf8 alien>string" + " length >fixnum" + " ] [" + " dup current-callback eq?" + " [ drop ] [ wait-for-callback ] if" + " ] do-callback" + "]" + } +} ; diff --git a/basis/stack-checker/backend/backend-docs.factor b/basis/stack-checker/backend/backend-docs.factor index fedce8310c..04a1a46f24 100644 --- a/basis/stack-checker/backend/backend-docs.factor +++ b/basis/stack-checker/backend/backend-docs.factor @@ -1,5 +1,5 @@ USING: compiler.tree effects help.markup help.syntax quotations sequences -stack-checker.visitor ; +stack-checker.state stack-checker.visitor ; IN: stack-checker.backend HELP: infer-quot-here @@ -13,3 +13,7 @@ HELP: introduce-values HELP: with-infer { $values { "quot" quotation } { "effect" effect } { "visitor" "a visitor, if any" } } { $description "Initializes the inference engine and then runs the given quotation which is supposed to perform the inferencing." } ; + +HELP: push-literal +{ $values { "obj" "something" } } +{ $description "Pushes a literal onto the " { $link literals } " sequence." } ; diff --git a/basis/stack-checker/state/state-docs.factor b/basis/stack-checker/state/state-docs.factor new file mode 100644 index 0000000000..734eb19357 --- /dev/null +++ b/basis/stack-checker/state/state-docs.factor @@ -0,0 +1,13 @@ +USING: help.markup help.syntax quotations sequences ; +IN: stack-checker.state + +HELP: meta-d +{ $values { "stack" sequence } } +{ $description "Compile-time data stack." } ; + +HELP: meta-r +{ $values { "stack" sequence } } +{ $description "Compile-time retain stack." } ; + +HELP: literals +{ $var-description "Uncommitted literals. This is a form of local dead-code elimination; the goal is to reduce the number of IR nodes which get constructed. Technically it is redundant since we do global DCE later, but it speeds up compile time." } ; diff --git a/basis/stack-checker/state/state.factor b/basis/stack-checker/state/state.factor index 67f8cdc67b..b48b0b14a6 100644 --- a/basis/stack-checker/state/state.factor +++ b/basis/stack-checker/state/state.factor @@ -18,16 +18,10 @@ DEFER: commit-literals SYMBOL: (meta-d) SYMBOL: (meta-r) -! Compile-time data stack : meta-d ( -- stack ) commit-literals (meta-d) get ; -! Compile-time retain stack : meta-r ( -- stack ) (meta-r) get ; -! Uncommitted literals. This is a form of local dead-code -! elimination; the goal is to reduce the number of IR nodes -! which get constructed. Technically it is redundant since -! we do global DCE later, but it speeds up compile time. SYMBOL: literals : (push-literal) ( obj -- ) diff --git a/core/continuations/continuations-docs.factor b/core/continuations/continuations-docs.factor index 12c259a485..d5bd657ae9 100644 --- a/core/continuations/continuations-docs.factor +++ b/core/continuations/continuations-docs.factor @@ -180,6 +180,10 @@ HELP: ignore-errors { $values { "quot" quotation } } { $description "Calls the quotation. If an exception is thrown in the dynamic extent of the quotation, restores the data stack and returns." } ; +HELP: in-callback? +{ $values { "?" "a boolean" } } +{ $description "t if Factor is currently executing a callback." } ; + HELP: rethrow { $values { "error" object } } { $description "Throws an error without saving the current continuation in the " { $link error-continuation } " global variable. This is done so that inspecting the error stacks sheds light on the original cause of the exception, rather than the point where it was rethrown." }