alien-callback ( return parameters abi quot -- alien )

alien-callback ( return parameters abi quot -- alien )
Factor handbook » C library interface » Calling Factor from C

Vocabulary
alien

Inputs

return	a C return type
parameters	a sequence of C parameter types
abi	one of cdecl or stdcall
quot	a quotation

Outputs

alien

an alien

Word description
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 void indicates that no value is to be returned.

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 alien-callback is compiled.

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 Exception handling for error handling options.

Notes
C type names are documented in C type specifiers.

Examples
A simple example, showing a C function which returns the difference of two given integers:

: difference-callback ( -- alien ) int { int int } cdecl [ - ] alien-callback ;

Errors
Throws an callsite-not-compiled if the word calling alien-callback is not compiled.

See also
alien-invoke, alien-indirect, alien-assembly

Definition

IN: alien

: alien-callback ( return parameters abi quot -- alien )
\ alien-callback callsite-not-compiled ;