source: project/wiki/man/4/Embedding @ 25875

Last change on this file since 25875 was 25875, checked in by felix winkelmann, 9 years ago

merged some manual changes from master into wiki

File size: 9.5 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)</procedure>
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}}.
71
72The {{eval}} library unit also provides boilerplate callbacks, that simplify invoking Scheme
73code embedded in a C or C++ application:
74
75=== CHICKEN_eval
76
77 [C macro] int CHICKEN_eval (C_word exp, C_word *result)
78
79Evaluates the Scheme object passed in {{exp}}, writing the result value to {{result}}.
80The return value is 1 if the operation succeeded,
81or 0 if an error occurred. Call {{CHICKEN_get_error_message}} to obtain a description
82of the error.
83
84
85=== CHICKEN_eval_string
86
87 [C macro] int CHICKEN_eval_string (char *str, C_word *result)
88
89Evaluates the Scheme expression passed in the string {{str}}, writing the result value to {{result}}.
90
91
92=== CHICKEN_eval_to_string
93
94 [C macro] int CHICKEN_eval_to_string (C_word exp, char *result, int size)
95
96Evaluates the Scheme expression passed in {{exp}}, writing a textual representation
97of the result into {{result}}. {{size}} should specify the maximal size of the result string.
98
99
100=== CHICKEN_eval_string_to_string
101
102 [C macro] int CHICKEN_eval_string_to_string (char *str, char *result, int size)
103
104Evaluates the Scheme expression passed in the string {{str}}, writing a textual representation
105of the result into {{result}}. {{size}} should specify the maximal size of the result string.
106
107
108=== CHICKEN_apply
109
110 [C macro] int CHICKEN_apply (C_word func, C_word args, C_word *result)
111
112Applies the procedure passed in {{func}} to the list of arguments {{args}}, writing the result value to {{result}}.
113
114
115=== CHICKEN_apply_to_string
116
117 [C macro] int CHICKEN_apply_to_string (C_word func, C_word args, char *result, int size)
118
119Applies the procedure passed in {{func}} to the list of arguments {{args}}, writing a textual
120representation of the result into {{result}}.
121
122
123=== CHICKEN_read
124
125 [C macro] int CHICKEN_read (char *str, C_word *result)
126
127Reads a Scheme object from the string {{str}}, writing the result value to {{result}}.
128
129
130=== CHICKEN_load
131
132 [C macro] int CHICKEN_load (char *filename)
133
134Loads the Scheme file {{filename}} (either in source form or compiled).
135
136
137=== CHICKEN_get_error_message
138
139 [C macro] void CHICKEN_get_error_message (char *result, int size)
140
141Returns a textual description of the most recent error that occurred in executing embedded Scheme code.
142
143
144=== CHICKEN_yield
145
146 [C macro] int CHICKEN_yield (int *status)
147
148If threads have been spawned during earlier invocations of embedded Scheme code, then this function
149will run the next scheduled thread for one complete time-slice. This is useful, for example, inside
150an ''idle'' handler in a GUI application with background Scheme threads. Note that the
151{{srfi-18}} library unit has to be linked in for this.
152
153
154
155An example:
156
157 % cat x.scm
158 ;;; x.scm
159 
160 (define (bar x) (gc) (* x x))
161 
162 (define-external (baz (int i)) double
163   (sqrt i))
164 (return-to-host)
165 
166
167 % cat y.c
168 /* y.c */
169 
170 #include <chicken.h>
171 #include <assert.h>
172 
173 extern double baz(int);
174 
175 int main() {
176   char buffer[ 256 ];
177   int status;
178   C_word val = C_SCHEME_UNDEFINED;
179   C_word *data[ 1 ];
180 
181   data[ 0 ] = &val;
182 
183   CHICKEN_run(C_toplevel);
184 
185   status = CHICKEN_read("(bar 99)", &val);
186   assert(status);
187 
188   C_gc_protect(data, 1);
189 
190   printf("data: %08x\n", val);
191 
192   status = CHICKEN_eval_string_to_string("(bar)", buffer, 255);
193   assert(!status);
194 
195   CHICKEN_get_error_message(buffer, 255);
196   printf("ouch: %s\n", buffer);
197 
198   status = CHICKEN_eval_string_to_string("(bar 23)", buffer, 255);
199   assert(status);
200 
201   printf("-> %s\n", buffer);
202   printf("data: %08x\n", val);
203 
204   status = CHICKEN_eval_to_string(val, buffer, 255);
205   assert(status);
206   printf("-> %s\n", buffer);
207 
208   printf("->` %g\n", baz(22));
209 
210   return 0;
211 }
212 
213 % csc x.scm y.c -embedded
214
215It is also possible to re-enter the computation following the call to {{return-to-host}} by calling
216{{CHICKEN_continue}}:
217
218=== CHICKEN_continue
219
220 [C function] C_word CHICKEN_continue (C_word k)
221
222Re-enters Scheme execution. {{k}} is the continuation received from the previous invocation
223of {{CHICKEN_run}} or {{CHICKEN_continue}}. When {{return-to-host}} is called again,
224this function returns another continuation that can be used to restart again.
225
226If you invoke callbacks prior to calling {{CHICKEN_continue}}, make sure that the
227continuation is not reclaimed by garbage collection. This can be avoided by using {{C_gc_protect}}
228or gc-roots.
229
230Another example:
231
232 % cat x.scm
233 (require-extension srfi-18)
234 
235 (define m (make-mutex))
236 
237 (define (t)
238   (mutex-lock! m)
239   (thread-sleep! 1)
240   (print (thread-name (current-thread)))
241   (mutex-unlock! m)
242   (t) )
243 
244 (thread-start! (make-thread t 'PING!))
245 (thread-start! (make-thread t 'PONG!))
246 
247 (let loop ()
248   (return-to-host)
249   (thread-yield!)
250   (loop) )
251 
252 % cat y.c
253 #include <chicken.h>
254 
255 int main()
256 {
257   C_word k = CHICKEN_run(C_toplevel);
258 
259   for(;;)
260     k = CHICKEN_continue(k);
261 
262   return 0;
263 }
264 
265 % csc x.scm y.c -embedded
266
267It is advisable not to mix repeated uses of {{CHICKEN_continue}}/{{return-to-host}}
268(as in the example above) with callbacks. Once {{return-to-host}} is invoked, the runtime system
269and any Scheme code executed prior to the invocation is initialized and can be conveniently
270used via callbacks.
271
272A simpler interface For handling GC-safe references to Scheme data are the so called ''gc-roots'':
273
274=== CHICKEN_new_gc_root
275
276 [C function] void* CHICKEN_new_gc_root ()
277
278Returns a pointer to a ''GC root'', which is an object that holds a reference to a Scheme value
279that will always be valid, even after a garbage collection. The content of the gc root is initialized to
280an unspecified value.
281
282
283=== CHICKEN_new_finalizable_gc_root
284
285 [C function] void* CHICKEN_new_finalizable_gc_root ()
286
287Similar to {{CHICKEN_new_gc_root}}, but allows the stored value to
288be finalized: if this gc root holds reference to an otherwise
289unreferenced data object that has a finalizer, the finalizer is still
290invoked.
291
292
293=== CHICKEN_delete_gc_root
294
295 [C function] void CHICKEN_delete_gc_root (void *root)
296
297Deletes the gc root.
298
299
300=== CHICKEN_gc_root_ref
301
302 [C macro] C_word CHICKEN_gc_root_ref (void *root)
303
304Returns the value stored in the gc root.
305
306
307=== CHICKEN_gc_root_set
308
309 [C macro] void CHICKEN_gc_root_set (void *root, C_word value)
310
311Sets the content of the GC root to a new value.
312
313
314
315Sometimes it is handy to access global variables from C code:
316
317=== CHICKEN_global_lookup
318
319 [C function] void* CHICKEN_global_lookup (char *name)
320
321Returns a GC root that holds the global variable with the name {{name}}. If no such variable
322exists, {{NULL}} is returned.
323
324
325=== CHICKEN_global_ref
326
327 [C function] C_word CHICKEN_global_ref (void *global)
328
329Returns the value of the global variable referenced by the GC root {{global}}.
330
331
332=== CHICKEN_global_set
333
334 [C function] void CHICKEN_global_set (void *global, C_word value)
335
336Sets the value of the global variable referenced by the GC root {{global}} to {{value}}.
337
338---
339Previous: [[Foreign type specifiers]]
340
341Next: [[Callbacks]]
Note: See TracBrowser for help on using the repository browser.