core/compiler/alien/alien-callback.facts

   1 IN: alien
   2 USING: errors help ;
   3
   4 HELP: alien-callback-error
   5 { $error-description "Thrown when " { $link alien-callback } " is called in the interpreter.  Words using " { $link alien-callback } " must be compiled first, and all three inputs to " { $link alien-callback } " must be literals." } ;
   6
   7 HELP: alien-callback
   8 { $values { "return" "a C return type" } { "parameters" "a sequence of C parameter types" } { "quot" "a quotation" } { "alien" "an alien address" } }
   9 { $description
  10     "Defines a callback from C to Factor which accepts the given set of parameters from the C caller, pushes them on the data stack, calls the quotation, and passes a return value back to the C caller. A return type of " { $snippet "\"void\"" } " indicates that no value is to be returned."
  11     $terpri
  12     "When a compiled reference to this word is called, it pushes the callback's alien address on the data stack. This address can be passed to any C function expecting a C function pointer with the correct signature. The callback is actually generated when the word calling " { $link alien-callback } " is compiled."
  13     $terpri
  14     "Callback quotations run with freshly-allocated stacks. This means the data stack contains the values passed by the C function, and nothing else. It also means that if the callback throws an error which is not caught, the Factor runtime will halt. See " { $link "errors" } " for error handling options."
  15 }
  16 { $examples
  17     "A simple example, showing a C function which returns the difference of two given integers:"
  18     { $code
  19         ": difference-callback ( -- alien )"
  20         "    \"int\" { \"int\" \"int\" } [ - ] alien-callback ;"
  21     }
  22 }
  23 { $errors "Throws an " { $link alien-callback-error } " if the word calling " { $link alien-callback } " is not compiled." }
  24 { $see-also alien-invoke alien-indirect } ;