source: project/wiki/Embedding @ 2878

Last change on this file since 2878 was 2878, checked in by felix winkelmann, 14 years ago

http-server-form-posts setup fix

File size: 9.2 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4
5== Embedding
6
7Compiled Scheme files can be linked with C code, provided the Scheme code was compiled
8in ''embedded'' mode by passing {{-DC_EMBEDDED}} to the C compiler (this will
9disable generation of a {{main()}} function). {{csc}} will do this, when given
10the {{-embedded}} option. Alternatively pass {{-embedded}} to {{csc}}.
11
12The following C API is available:
13
14=== CHICKEN_parse_command_line
15
16 [C function] void CHICKEN_parse_command_line (int argc, char *argv[], int *heap, int *stack int *symbols)
17
18Parse the programs command-line contained in {{argc}} and
19{{argv}} and return the heap-, stack- and symbol table limits
20given by runtime options of the form {{-:...}}, or choose default
21limits. The library procedure {{argv}} can access the command-line
22only if this function has been called by the containing application.
23
24
25=== CHICKEN_initialize
26
27 [C function] int CHICKEN_initialize (int heap, int stack, int symbols, void *toplevel)
28
29Initializes the Scheme execution context and memory. {{heap}}
30holds the number of bytes that are to be allocated for the secondary
31heap. {{stack}} holds the number of bytes for the primary
32heap. {{symbols}} contains the size of the symbol table. Passing
33{{0}} to one or more of these parameters will select a default
34size.
35{{toplevel}} should be a pointer to the toplevel entry point
36procedure. You should pass {{C_toplevel}} here. In any subsequent
37call to {{CHICKEN_run}} you can simply
38pass {{NULL}}.
39Calling this function more than once has no effect. If enough
40memory is available and initialization was successful, then {{1}}
41is returned, otherwise this function returns {{0}}.
42
43=== CHICKEN_run
44
45 [C function] C_word CHICKEN_run (void *toplevel)
46
47Starts the Scheme program. Call this function once to execute all toplevel expressions in your
48compiled Scheme program. If the runtime system was not initialized before,
49then {{CHICKEN_initialize}} is called with default sizes.
50{{toplevel}} is the toplevel entry-point procedure, you usually pass {{C_toplevel}} here.
51The result value is the continuation that can be used to re-invoke the Scheme code from the
52point after it called {{return-to-host}} (see below).
53
54If you just need a Scheme interpreter, you can also pass {{CHICKEN_default_toplevel}} as
55the toplevel procedure, which just uses the default library units.
56
57
58Once {{CHICKEN_run}} has been called, Scheme code is executing until all toplevel
59expressions have been evaluated or until {{return-to-host}} is called inside the
60Scheme program.
61
62=== return-to-host
63
64 [procedure] (return-to-host)
65
66Exits the Scheme code and returns to the invoking context that called {{CHICKEN_run}}
67or {{CHICKEN_continue}}.
68
69After {{return-to-host}} has been executed and once {{CHICKEN_run}} returns,
70you can invoke callbacks which have been defined with {{define-external}}.
71The {{eval}} library unit also provides ''boilerplate'' callbacks, that simplify invoking Scheme
72code embedded in a C or C++ application a lot.
73
74=== CHICKEN_eval
75
76 [C macro] int CHICKEN_eval (C_word exp, C_word *result)
77
78Evaluates the Scheme object passed in {{exp}}, writing the result value to {{result}}.
79The return value is 1 if the operation succeeded,
80or 0 if an error occurred. Call {{CHICKEN_get_error_message}} to obtain a description
81of the error.
82
83
84=== CHICKEN_eval_string
85
86 [C macro] int CHICKEN_eval_string (char *str, C_word *result)
87
88Evaluates the Scheme expression passed in the string {{str}}, writing the result value to {{result}}.
89
90
91=== CHICKEN_eval_to_string
92
93 [C macro] int CHICKEN_eval_to_string (C_word exp, char *result, int size)
94
95Evaluates the Scheme expression passed in {{exp}}, writing a textual representation
96of the result into {{result}}. {{size}} should specify the maximal size of the result string.
97
98
99=== CHICKEN_eval_string_to_string
100
101 [C macro] int CHICKEN_eval_string_to_string (char *str, char *result, int size)
102
103Evaluates the Scheme expression passed in the string {{str}}, writing a textual representation
104of the result into {{result}}. {{size}} should specify the maximal size of the result string.
105
106
107=== CHICKEN_apply
108
109 [C macro] int CHICKEN_apply (C_word func, C_word args, C_word *result)
110
111Applies the procedure passed in {{func}} to the list of arguments {{args}}, writing the result value to {{result}}.
112
113
114=== CHICKEN_apply_to_string
115
116 [C macro] int CHICKEN_apply_to_string (C_word func, C_word args, char *result, int size)
117
118Applies the procedure passed in {{func}} to the list of arguments {{args}}, writing a textual
119representation of the result into {{result}}.
120
121
122=== CHICKEN_read
123
124 [C macro] int CHICKEN_read (char *str, C_word *result)
125
126Reads a Scheme object from the string {{str}}, writing the result value to {{result}}.
127
128
129=== CHICKEN_load
130
131 [C macro] int CHICKEN_load (char *filename)
132
133Loads the Scheme file {{filename}} (either in source form or compiled).
134
135
136=== CHICKEN_get_error_message
137
138 [C macro] void CHICKEN_get_error_message (char *result, int size)
139
140Returns a textual description of the most recent error that occurred in executing embedded Scheme code.
141
142
143=== CHICKEN_yield
144
145 [C macro] int CHICKEN_yield (int *status)
146
147If threads have been spawned during earlier invocations of embedded Scheme code, then this function
148will run the next scheduled thread for one complete time-slice. This is useful, for example, inside
149an ''idle'' handler in a GUI application with background Scheme threads. Note that the
150{{srfi-18}} library unit has to be linked in for this.
151
152
153
154An example:
155
156 % cat x.scm
157 ;;; x.scm
158 
159 (define (bar x) (gc) (* x x))
160 
161 (define-external (baz (int i)) double
162   (sqrt i))
163 (return-to-host)
164 
165
166 % cat y.c
167 /* y.c */
168 
169 #include "chicken.h"
170 #include <assert.h>
171 
172 extern double baz(int);
173 
174 int main() {
175   char buffer[ 256 ];
176   int status;
177   C_word val = C_SCHEME_UNDEFINED;
178   C_word *data[ 1 ];
179 
180   data[ 0 ] = &val;
181 
182   CHICKEN_run(C_toplevel);
183 
184   status = CHICKEN_read("(bar 99)", &val);
185   assert(status);
186 
187   C_gc_protect(data, 1);
188 
189   printf("data: %08x\n", val);
190 
191   status = CHICKEN_eval_string_to_string("(bar)", buffer, 255);
192   assert(!status);
193 
194   CHICKEN_get_error_message(buffer, 255);
195   printf("ouch: %s\n", buffer);
196 
197   status = CHICKEN_eval_string_to_string("(bar 23)", buffer, 255);
198   assert(status);
199 
200   printf("-> %s\n", buffer);
201   printf("data: %08x\n", val);
202 
203   status = CHICKEN_eval_to_string(val, buffer, 255);
204   assert(status);
205   printf("-> %s\n", buffer);
206 
207   printf("->` %g\n", baz(22));
208 
209   return 0;
210 }
211 
212 % csc x.scm y.c -embedded
213
214It is also possible to re-enter the computation following the call to {{return-to-host}} by calling
215{{CHICKEN_continue}}:
216
217=== CHICKEN_continue
218
219 [C function] C_word CHICKEN_continue (C_word k)
220
221Re-enters Scheme execution. {{k}} is the continuation received from the previous invocation
222of {{CHICKEN_run}} or {{CHICKEN_continue}}. When {{return-to-host}} is called again,
223this function returns another continuation that can be used to restart again.
224
225If you invoke callbacks prior to calling {{CHICKEN_continue}}, make sure that the
226continuation is not reclaimed by garbage collection. This can be avoided by using {{C_gc_protect}}
227or gc-roots.
228
229Another example:
230
231 % cat x.scm
232 (require-extension srfi-18)
233 
234 (define m (make-mutex))
235 
236 (define (t)
237   (mutex-lock! m)
238   (thread-sleep! 1)
239   (print (thread-name (current-thread)))
240   (mutex-unlock! m)
241   (t) )
242 
243 (thread-start! (make-thread t 'PING!))
244 (thread-start! (make-thread t 'PONG!))
245 
246 (let loop ()
247   (return-to-host)
248   (thread-yield!)
249   (loop) )
250 
251 % cat y.c
252 #include "chicken.h"
253 
254 int main()
255 {
256   C_word k = CHICKEN_run(C_toplevel);
257 
258   for(;;)
259     k = CHICKEN_continue(k);
260 
261   return 0;
262 }
263 
264 % csc x.scm y.c -embedded
265
266It is advisable not to mix repeated uses of {{CHICKEN_continue}}/{{return-to-host}}
267(as in the example above) with callbacks. Once {{return-to-host}} is invoked, the runtime system
268and any Scheme code executed prior to the invocation is initialized and can be conveniently
269used via callbacks.
270
271A simpler interface For handling GC-safe references to Scheme data are the so called ''gc-roots'':
272
273=== CHICKEN_new_gc_root
274
275 [C function] void* CHICKEN_new_gc_root ()
276
277Returns a pointer to a ''GC root'', which is an object that holds a reference to a Scheme value
278that will always be valid, even after a garbage collection. The content of the gc root is initialized to
279an unspecified value.
280
281
282=== CHICKEN_delete_gc_root
283
284 [C function] void CHICKEN_delete_gc_root (void *root)
285
286Deletes the gc root.
287
288
289=== CHICKEN_gc_root_ref
290
291 [C macro] C_word CHICKEN_gc_root_ref (void *root)
292
293Returns the value stored in the gc root.
294
295
296=== CHICKEN_gc_root_set
297
298 [C macro] void CHICKEN_gc_root_set (void *root, C_word value)
299
300Sets the content of the GC root to a new value.
301
302
303
304Sometimes it is handy to access global variables from C code:
305
306=== CHICKEN_global_lookup
307
308 [C function] void* CHICKEN_global_lookup (char *name)
309
310Returns a GC root that holds the global variable with the name {{name}}. If no such variable
311exists, {{NULL}} is returned.
312
313
314=== CHICKEN_global_ref
315
316 [C function] C_word CHICKEN_global_ref (void *global)
317
318Returns the value of the global variable referenced by the GC root {{global}}.
319
320
321=== CHICKEN_global_set
322
323 [C function] void CHICKEN_global_set (void *global, C_word value)
324
325Sets the value of the global variable referenced by the GC root {{global}} to {{value}}.
326
327Previous: [[Foreign type specifiers]]
328
329Next: [[Callbacks]]
Note: See TracBrowser for help on using the repository browser.