source: project/chicken/branches/scrutiny/manual/Callbacks @ 14827

Last change on this file since 14827 was 14827, checked in by felix winkelmann, 10 years ago

merged trunk changes until 14826 into scrutiny branch

File size: 4.1 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Callbacks
5
6
7To enable an external C function to call back to Scheme, the form
8{{foreign-safe-lambda}} (or {{foreign-safe-lambda*}})
9has to be used. This generates special code to save and restore important
10state information during execution of C code. There are two ways of
11calling Scheme procedures from C: the first is to invoke the runtime
12function {{C_callback}} with the closure to be called and the number
13of arguments.  The second is to define an externally visible wrapper
14function around a Scheme procedure with the {{define-external}}
15form.
16
17Note: the names of all functions, variables and macros exported by the
18CHICKEN runtime system start with {{C_}}. It is advisable to
19use a different naming scheme for your own code to avoid name clashes.
20Callbacks (defined by {{define-external}})
21do not capture the lexical environment.
22
23Non-local exits leaving the scope of the invocation of a callback from
24Scheme into C will not remove the C call-frame from the stack (and
25will result in a memory leak).  '''Note:''' The same applies to
26SRFI-18 threading, which is implemented with {{call/cc}};
27additionally, if you enter one callback, switch threads and then exit
28a different callback, your program is likely to crash.
29
30
31=== define-external
32
33 [syntax] (define-external [QUALIFIERS] (NAME (ARGUMENTTYPE1 VARIABLE1) ...) RETURNTYPE BODY ...)
34 [syntax] (define-external NAME TYPE [INIT])
35
36The first form defines an externally callable Scheme
37procedure. {{NAME}} should be a symbol, which, when converted to a
38string, represents a legal C identifier. {{ARGUMENTTYPE1 ...}} and
39{{RETURNTYPE}} are foreign type specifiers for the argument variables
40{{VAR1 ...}} and the result, respectively.  {{QUALIFIERS}}
41is an optional qualifier for the foreign procedure definition, like
42{{__stdcall}}.
43
44<enscript highlight=scheme>
45(define-external (foo (c-string x)) int (string-length x))
46</enscript>
47
48The second form of {{define-external}} can be used to define
49variables that are accessible from foreign code. It declares
50a global variable named by the symbol {{NAME}} that
51has the type {{TYPE}}. {{INIT}} can be an arbitrary
52expression that is used to initialize the variable. {{NAME}} is
53accessible from Scheme just like any other foreign variable defined by
54{{define-foreign-variable}}. 
55
56<enscript highlight=scheme>
57(define-external foo int 42)
58((foreign-lambda* int ()
59  "C_return(foo);"))           ==> 42
60</enscript>
61
62'''Note:''' don't be tempted to
63assign strings or bytevectors to external variables. Garbage collection
64moves those objects around, so it is very bad idea to assign pointers
65to heap-data. If you have to do so, then copy the data object into
66statically allocated memory (for example by using {{object-evict}}).
67
68Results of type {{scheme-object}} returned by {{define-external}}
69are always allocated in the secondary heap, that is, not in the stack.
70=== C_callback
71
72 [C function] C_word C_callback (C_word closure, int argc)
73
74This function can be used to invoke the Scheme procedure {{closure}}.
75{{argc}} should contain the number of arguments that are passed to
76the procedure on the temporary stack. Values are put onto the temporary
77stack with the {{C_save}} macro.
78
79=== C_callback_adjust_stack
80
81 [C function] void C_callback_adjust_stack (C_word *ptr, int size)
82
83The runtime-system uses the stack as a special allocation area and
84internally holds pointers to estimated limits to distinguish between
85Scheme data objects inside the stack from objects outside of it.  If
86you invoke callbacks at wildly differing stack-levels, these limits
87may shift from invocation to invocation. Callbacks defined with
88{{define-external}} will perform appropriate adjustments
89automatically, but if you invoke {{C_callback}} manually, you should
90perform a {{C_callback_adjust_stack}} to make sure the internal limits
91are set properly. {{ptr}} should point to some data object on the
92stack and {{size}} is the number of words contained in the data object
93(or some estimate). The call will make sure the limits are adjusted so
94that the value pointed to by {{ptr}} is located in the stack.
95
96---
97Previous: [[Embedding]]
98
99Next: [[Locations]]
Note: See TracBrowser for help on using the repository browser.