Alien Functions - FFI 0.1
Description: FFI 0.1

Next: Callbacks, Previous: Alien Data, Up: Top

## 4 Alien Functions

The `C-call` syntax produces code that applies `call-alien` to an alien function structure — a cache for the callout trampoline's entry address.

         (C-call "gtk_button_new" (make-alien '(* |GtkWidget|)))
         ==>
         (call-alien '#[alien-function gtk_button_new] (make-alien ...))

The alien function contains all the information needed to load the callout trampoline on demand (i.e. its name and library). Once the alien function has cached the entry address, `call-alien` can invoke the trampoline (via `#[primitive c-call]`). The trampoline gets its arguments off the Scheme stack, converts them to C values, calls the C function, conses a result, and returns it to Scheme. As a special case a function returning a pointer type expects an extra first argument. If this argument is `#f`, the return value is discarded. If the argument is an alien, the function's return value clobbers the alien's address. This makes it easy to grab pointers to toolkit resources without dropping them, or avoid unnecessary consing of aliens.

The `alien-function` structures are fasdumpable. The caching mechanism invalidates the cache when a band is restored, or a fasdumped object is fasloaded. The alien function will lookup the trampoline entry point again on demand.