stack-checker,compiler: docs for stack-checker and compiler words

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

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"
+    "]"
+  }
+} ;

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." } ;

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." } ;

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 -- )

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." }