Accessing external objects

foreign-code

Executes the embedded C/C++ code STRING ..., which should be a sequence of C statements, which are executed and return an unspecified result.

(foreign-code "doSomeInitStuff();") => #<unspecified>

Code wrapped inside foreign-code may not invoke callbacks into Scheme.

foreign-value

[syntax](foreign-value CODE TYPE)

Evaluates the embedded C/C++ expression CODE (which may be a string or symbol), returning a value of type given in the foreign-type specifier TYPE.

(print (foreign-value "my_version_string" c-string))

foreign-declare

[syntax](foreign-declare STRING ...)

Include given strings verbatim into header of generated file.

define-foreign-type

[syntax](define-foreign-type NAME TYPE [ARGCONVERT [RETCONVERT]])

Defines an alias for TYPE with the name NAME (a symbol). TYPE may be a type-specifier or a string naming a C type. The namespace of foreign type specifiers is separate from the normal Scheme namespace. The optional arguments ARGCONVERT and RETCONVERT should evaluate to procedures that map argument- and result-values to a value that can be transformed to TYPE:

Foreign type-definitions are only visible in the compilation-unit in which they are defined, so use include to use the same definitions in multiple files.

define-foreign-variable

[syntax](define-foreign-variable NAME TYPE [STRING])

Defines a foreign variable of name NAME (a symbol). STRING should be the real name of a foreign variable or parameterless macro. If STRING is not given, then the variable name NAME will be converted to a string and used instead. All references and assignments (via set!) are modified to correctly convert values between Scheme and C representation. This foreign variable can only be accessed in the current compilation unit, but the name can be lexically shadowed. Note that STRING can name an arbitrary C expression. If no assignments are performed, then STRING doesn't even have to specify an lvalue.

foreign-lambda

[syntax](foreign-lambda RETURNTYPE NAME ARGTYPE ...)

Represents a binding to an external routine. This form can be used in the position of an ordinary lambda expression. NAME specifies the name of the external procedure and should be a string or a symbol.

For obscure technical reasons you should use the C_return macro instead of the normal return statement to return a result from the foreign lambda body as some cleanup code has to be run before execution commences in the calling code.

foreign-safe-lambda

[syntax](foreign-safe-lambda RETURNTYPE NAME ARGTYPE ...)

This is similar to foreign-lambda, but also allows the called function to call Scheme functions and allocate Scheme data-objects. See Callbacks.

foreign-primitive

This is also similar to foreign-lambda* but the code will be executed in a primitive CPS context, which means it will not actually return, but call it's continuation on exit. This means that code inside this form may allocate Scheme data on the C stack (the nursery) with C_alloc (see below). If the RETURNTYPE is omitted it defaults to void. You can return multiple values inside the body of the foreign-primitive form by calling this C function:

C_values(N + 2, C_SCHEME_UNDEFINED, C_k, X1, ...)

where N is the number of values to be returned, and X1, ... are the results, which should be Scheme data objects. When returning multiple values, the return-type should be omitted.