source: project/chicken/branches/release/manual/C interface @ 7276

Last change on this file since 7276 was 7276, checked in by felix winkelmann, 12 years ago

merged trunk

File size: 10.7 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4
5== C interface
6
7
8The following functions and macros are available for C code that invokes
9Scheme or foreign procedures that are called by Scheme:
10
11
12
13=== C_save
14
15 [C macro] void C_save (C_word x) :
16
17Saves the Scheme data object {{x}} on the temporary stack.
18
19
20=== C_restore
21
22 [C macro] void C_restore
23
24Pops and returns the topmost value from the temporary stack.
25
26
27=== C_fix
28
29 [C macro] C_word C_fix (int integer)
30
31=== C_make_character
32
33 [C macro] C_word C_make_character (int char_code)
34
35=== C_SCHEME_END_OF_LIST
36
37 [C macro] C_SCHEME_END_OF_LIST
38
39=== C_word C_SCHEME_END_OF_FILE
40
41 [C macro] C_SCHEME_END_OF_FILE
42
43=== C_word C_SCHEME_FALSE
44
45 [C macro] C_SCHEME_FALSE
46
47=== C_word C_SCHEME_TRUE
48
49 [C macro] C_SCHEME_TRUE
50
51These macros return immediate Scheme data objects.
52
53
54=== C_string
55
56 [C function] C_word C_string (C_word **ptr, int length, char *string)
57
58=== C_string2
59
60 [C function] C_word C_string2 (C_word **ptr, char *zero_terminated_string)
61
62=== C_intern2
63
64 [C function] C_word C_intern2 (C_word **ptr, char *zero_terminated_string)
65
66=== C_intern3
67
68 [C function] C_word C_intern3 (C_word **ptr, char *zero_terminated_string, C_word initial_value)
69
70=== C_pair
71
72 [C function] C_word C_pair (C_word **ptr, C_word car, C_word cdr)
73
74=== C_flonum
75
76 [C function] C_word C_flonum (C_word **ptr, double number)
77
78=== C_int_to_num
79
80 [C function] C_word C_int_to_num (C_word **ptr, int integer)
81
82=== C_mpointer
83
84 [C function] C_word C_mpointer (C_word **ptr, void *pointer)
85
86=== C_vector
87
88 [C function] C_word C_vector (C_word **ptr, int length, ...)
89
90=== C_list
91
92 [C function] C_word C_list (C_word **ptr, int length, ...)
93
94These functions allocate memory from {{ptr}} and initialize a fresh
95data object. The new data object is returned. {{ptr}} should be the
96'''address''' of an allocation pointer created with {{C_alloc}}.
97
98
99=== C_alloc
100
101 [C macro] C_word* C_alloc (int words)
102
103Allocates memory from the C stack ({{C_alloc}}) and returns a pointer to
104it. {{words}} should be the number of words needed for all data
105objects that are to be created in this function.  Note that stack-allocated
106data objects have to be passed to Scheme callback functions, or they will
107not be seen by the garbage collector. This is really only usable for
108callback procedure invocations, make sure not to use it in normal code,
109because the allocated memory will be re-used after the foreign procedure
110returns. When invoking Scheme callback procedures a minor garbage
111collection is performed, so data allocated with {{C_alloc}}
112will already have moved to a safe place.
113
114Note that {{C_alloc}} is really just a wrapper around {{alloca}},
115and can also be simulated by declaring a stack-allocated array of
116{{C_word}}s:
117
118
119=== C_SIZEOF_LIST
120
121 [C macro] int C_SIZEOF_LIST (int length)
122
123=== C_SIZEOF_STRING
124
125 [C macro] int C_SIZEOF_STRING (int length)
126
127=== C_SIZEOF_VECTOR
128
129 [C macro] int C_SIZEOF_VECTOR (int length)
130
131=== C_SIZEOF_INTERNED_SYMBOL
132
133 [C macro] int C_SIZEOF_INTERNED_SYMBOL (int length)
134
135=== C_SIZEOF_PAIR
136
137 [C macro] int C_SIZEOF_PAIR
138
139=== C_SIZEOF_FLONUM
140
141 [C macro] int C_SIZEOF_FLONUM
142
143=== C_SIZEOF_POINTER
144
145 [C macro] int C_SIZEOF_POINTER
146
147=== C_SIZEOF_LOCATIVE
148
149 [C macro] int C_SIZEOF_LOCATIVE
150
151=== C_SIZEOF_TAGGED_POINTER
152
153 [C macro] int C_SIZEOF_TAGGED_POINTER
154
155These are macros that return the size in words needed for a data object
156of a given type.
157
158
159=== C_character_code
160
161 [C macro] int C_character_code (C_word character)
162
163=== C_unfix
164
165 [C macro] int C_unfix (C_word fixnum)
166
167=== C_flonum_magnitude
168
169 [C macro] double C_flonum_magnitude (C_word flonum)
170
171=== C_c_string
172
173 [C function] char* C_c_string (C_word string)
174
175=== C_num_to_int
176
177 [C function] int C_num_to_int (C_word fixnum_or_flonum)
178
179=== C_pointer_address
180
181 [C function] void* C_pointer_address (C_word pointer)
182
183These macros and functions can be used to convert Scheme data objects
184back to C data. Note that {{C_c_string()}} returns a pointer
185to the character buffer of the actual Scheme object and is not
186zero-terminated.
187
188
189=== C_header_size
190
191 [C macro] int C_header_size (C_word x)
192
193=== C_header_bits
194
195 [C macro] int C_header_bits (C_word x)
196
197Return the number of elements and the type-bits of the non-immediate
198Scheme data object {{x}}.
199
200
201=== C_block_item
202
203 [C macro] C_word C_block_item (C_word x, int index)
204
205This macro can be used to access slots of the non-immediate Scheme data
206object {{x}}.  {{index}} specifies the index of the slot to
207be fetched, starting at 0. Pairs have 2 slots, one for the '''car'''
208and one for the '''cdr'''. Vectors have one slot for each element.
209
210
211=== C_u_i_car
212
213 [C macro] C_word C_u_i_car (C_word x)
214
215=== C_u_i_cdr
216
217 [C macro] C_word C_u_i_cdr (C_word x)
218
219Aliases for {{C_block_item(x, 0)}} and {{C_block_item(x, 1)}}, respectively.
220
221
222=== C_data_pointer
223
224 [C macro] void* C_data_pointer (C_word x)
225
226Returns a pointer to the data-section of a non-immediate Scheme object.
227
228
229=== C_make_header
230
231 [C macro] C_word C_make_header (C_word bits, C_word size)
232
233A macro to build a Scheme object header from its bits and size parts.
234
235
236=== C_mutate
237
238 [C function] C_word C_mutate (C_word *slot, C_word val)
239
240Assign the Scheme value {{val}} to the location specified by
241{{slot}}.  If the value points to data inside the nursery (the first
242heap-generation), then the garbage collector will remember to handle the
243data appropriately. Assigning nursery-pointers directly will otherwise
244result in lost data. Note that no copying takes place at the moment
245when {{C_mutate}} is called, but later - at the next (minor) garbage
246collection.
247
248
249=== C_symbol_value
250
251 [C macro] C_word C_symbol_value (C_word symbol)
252
253Returns the global value of the variable with the name {{symbol}}. If the
254variable is unbound {{C_SCHEME_UNBOUND}} is returned. You can set a variable's
255value with {{C_mutate(&C_symbol_value(SYMBOL), VALUE)}}.
256
257
258=== C_gc_protect
259
260 [C function] void C_gc_protect (C_word *ptrs[], int n)
261
262Registers {{n}} variables at address {{ptrs}} to be garbage collection roots.
263The locations should not contain pointers to data allocated in the nursery, only
264immediate values or pointers to heap-data are valid. Any
265assignment of potential nursery data into a root-array should be done
266via {{C_mutate()}}. The variables have to be initialized to sensible values
267before the next garbage collection starts (when in doubt, set all locations
268in {{ptrs}} to {{C_SCHEME_UNDEFINED}})
269{{C_gc_protect}} may not called before the runtime system has been
270initialized (either by {{CHICKEN_initialize}}, {{CHICKEN_run}} or
271{{CHICKEN_invoke}}.
272
273For a slightly simpler interface to creating and using GC roots see
274{{CHICKEN_new_gc_root}}.
275
276
277=== C_gc_unprotect
278
279 [C function] void C_gc_unprotect (int n)
280
281Removes the last {{n}} registered variables from the set of
282root variables.
283
284
285=== C_pre_gc_hook
286
287 [C Variable] void (*C_pre_gc_hook)(int mode)
288
289If not {{NULL}}, the function pointed to by this variable will be
290called before each garbage collection with a flag indicating what kind
291of collection was performed (either {{0}} for a minor collection or
292{{2}} for a resizing collection). A "resizing" collection means a
293secondary collection that moves all live data into a enlarged (or
294shrinked) heap-space. Minor collections happen very frequently, so the
295hook function should not consume too much time. The hook function may
296not invoke Scheme callbacks.
297
298Note that resizing collections may be nested in normal major collections.
299
300=== C_post_gc_hook
301
302 [C Variable] void (*C_post_gc_hook)(int mode, long ms)
303
304If not {{NULL}}, the function pointed to by this variable will be
305called after each garbage collection with a flag indicating what kind
306of collection was performed (either {{0}} for a minor collection,
307{{1}} for a major collection or {{2}} for a resizing
308collection). Minor collections happen very frequently, so the hook
309function should not consume too much time. The hook function may not
310invoke Scheme callbacks. The {{ms}} argument records the number of
311milliseconds required for the garbage collection, if the collection
312was a major one. For minor collections the value of the {{ms}} argument
313is undefined.
314
315
316
317=== An example for simple calls to foreign code involving callbacks
318
319 % cat foo.scm
320 #>
321 extern int callout(int, int, int);
322 <#
323
324 (define callout (foreign-safe-lambda int "callout" int int int))
325
326 (define-external (callin (scheme-object xyz)) int
327   (print "This is 'callin': " xyz)
328   123)
329
330 (print (callout 1 2 3))
331
332 % cat bar.c
333 #include <stdio.h>
334 #include "chicken.h"
335
336 extern int callout(int, int, int);
337 extern int callin(C_word x);
338
339 int callout(int x, int y, int z)
340 {
341   C_word *ptr = C_alloc(C_SIZEOF_LIST(3));
342   C_word lst;
343
344   printf("This is 'callout': %d, %d, %d\n", x, y, z);
345   lst = C_list(&ptr, 3, C_fix(x), C_fix(y), C_fix(z));
346   return callin(lst);  /* Note: `callin' will have GC'd the data in `ptr' */
347 }
348
349 % csc foo.scm bar.c -o foo
350 % foo
351 This is 'callout': 1, 2, 3
352 This is 'callin': (1 2 3)
353 123
354
355
356=== Notes:
357
358Scheme procedures can call C functions, and C functions can call
359Scheme procedures, but for every pending C stack frame, the available
360size of the first heap generation (the ''nursery'') will be decreased,
361because the C stack is identical to the nursery. On systems with a small
362nursery this might result in thrashing, since the C code between the
363invocation of C from Scheme and the actual calling back to Scheme might
364build up several stack-frames or allocates large amounts of stack data.
365To prevent this it is advisable to increase the default nursery size,
366either when compiling the file (using the {{-nursery}} option)
367or when running the executable (using the {{-:s}} runtime option).
368
369Calls to Scheme/C may be nested arbitrarily, and Scheme
370continuations can be invoked as usual, but keep in mind that C stack
371frames will not be recovered, when a Scheme procedure call from C does
372not return normally.
373
374When multiple threads are running concurrently, and control switches
375from one thread to another, then the continuation of the current thread
376is captured and saved. Any pending C stack frame still active from a
377callback will remain on the stack until the threads is re-activated
378again. This means that in a multithreading situation, when C callbacks
379are involved, the available nursery space can be smaller than expected.
380So doing many nested Scheme->C->Scheme calls can reduce the available
381memory up to the point of thrashing. It is advisable to have only a
382single thread with pending C stack-frames at any given time.
383
384Pointers to Scheme data objects should not be stored in local or
385global variables while calling back to Scheme.  Any Scheme object not
386passed back to Scheme will be reclaimed or moved by the garbage collector.
387
388Calls from C to Scheme are never tail-recursive.
389
390Continuations captured via {{call-with-current-continuation}}
391and passed to C code can be invoked like any other Scheme procedure.
392
393
394
395Previous: [[Other support procedures]]
396
397Next: [[chicken-setup]]
Note: See TracBrowser for help on using the repository browser.