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
}
} ;
+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." }
}
} ;
+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"
+ "]"
+ }
+} ;
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
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." } ;
--- /dev/null
+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." } ;
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 -- )
{ $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." }