~ chicken-core (master) /manual/C interface
Trap1[[tags: manual]]2[[toc:]]345== C interface67The following functions and macros are available for C code that invokes8Scheme or foreign procedures that are called by Scheme:910=== Temporary stack1112==== C_save1314 [C macro] void C_save (C_word x) :1516Saves the Scheme data object {{x}} on the temporary stack.1718==== C_restore1920 [C macro] C_word C_restore2122Pops and returns the topmost value from the temporary stack.232425=== Type/value predicates2627When writing C code that accepts Scheme objects you often need to do28checking what type of object is passed. These can help you determine29the type of an object.3031==== C predicates3233These return regular C integer values (ie, zero is false, nonzero true).3435===== C_truep3637 [C macro] int C_truep(C_word x)3839Is {{x}} a truthy value, i.e. anything except {{C_SCHEME_FALSE}}?4041===== C_immediatep4243 [C macro] int C_immediatep(C_word x)4445Is {{x}} an immediate object?46(see below for a definition)4748===== C_fitsinfixnump4950 [C macro] int C_fitsinfixnump(int number)5152Will {{number}} fit in a fixnum? It will fit when there is room for53one additional type bit to tag it as a fixnum (assuming one bit is54already used for the sign). In practice this means that the number's55top two bits must be identical.5657===== C_ufitsinfixnump5859 [C macro] int C_ufitsinfixnump(unsigned int number)6061Like {{C_fitsinfixnump}} but for unsigned integers. This checks the62top ''two'' bits are zero, since fixnums '''always''' carry a sign.636465==== Scheme predicates6667These return Scheme booleans (ie, C_SCHEME_TRUE or C_SCHEME_FALSE).68This means they can be used directly from Scheme using {{##core#inline}}.6970===== C_zero_length_p7172 [C macro] C_word C_zero_length_p(C_word x)7374Is {{x}} a Scheme object of zero length? Only accepts non-immediate objects.7576===== C_unboundvaluep7778 [C macro] C_word C_unboundvaluep(C_word x)7980Is {{x}} the special unbound variable placeholder {{C_SCHEME_UNBOUND}}?8182===== C_boundp8384 [C macro] C_word C_boundp(C_word x)8586Is {{x}} a bound value? Only accepts non-immediate objects.8788===== C_blockp8990 [C macro] C_word C_blockp(C_word x)9192Is {{x}} a "block" value?9394A "block" value is a value that contains a memory block, i.e. is not95an immediate value.9697===== C_immp9899 [C macro] C_word C_immp(C_word x)100101Is {{x}} an immediate value?102103===== C_forwardedp104105 [C macro] C_word C_forwardedp(C_word x)106107Is {{x}} a GC-forwarded object?108109===== C_flonump110111 [C macro] C_word C_flonump(C_word x)112113Is {{x}} a Scheme flonum object? Accepts only non-immediate objects.114115===== C_stringp116117 [C macro] C_word C_stringp(C_word x)118119Is {{x}} a Scheme string object? Accepts only non-immediate objects.120121===== C_symbolp122123 [C macro] C_word C_symbolp(C_word x)124125Is {{x}} a symbol? Accepts only non-immediate objects.126127===== C_pairp128129 [C macro] C_word C_pairp(C_word x)130131Is {{x}} a pair? Accepts only non-immediate objects.132133===== C_closurep134135 [C macro] C_word C_closurep(C_word x)136137Is {{x}} a closure? Accepts only non-immediate objects.138139===== C_vectorp140141 [C macro] C_word C_vectorp(C_word x)142143Is {{x}} any kind of vector? Accepts only non-immediate objects.144145This returns true for both regular heterogenous R7RS vectors and146bytevectors. However, it does ''not'' return true for147SRFI-4 vectors, as those are actually bytevectors wrapped in a148structure with a type tag.149150===== C_bytevectorp151152 [C macro] C_word C_bytevectorp(C_word x)153154Is {{x}} a bytevector? Accepts only non-immediate objects.155156===== C_portp157158 [C macro] C_word C_portp(C_word x)159160Is {{x}} a port object? Accepts only non-immediate objects.161162===== C_structurep163164 [C macro] C_word C_structurep(C_word x)165166Is {{x}} a structure (record) object? Accepts only non-immediate objects.167168===== C_locativep169170 [C macro] C_word C_locativep(C_word x)171172Is {{x}} a locative object? Accepts only non-immediate objects.173174===== C_charp175176 [C macro] C_word C_charp(C_word x)177178Is {{x}} a character object?179180===== C_booleanp181182 [C macro] C_word C_booleanp(C_word x)183184Is {{x}} a boolean object?185186===== C_eofp187188 [C macro] C_word C_eofp(C_word x)189190Is {{x}} the {{#!eof}} object?191192===== C_undefinedp193194 [C macro] C_word C_undefinedp(C_word x)195196Is {{x}} the undefined value?197198===== C_fixnump199200 [C macro] C_word C_fixnump(C_word x)201202Is {{x}} a fixnum object?203204===== C_nfixnump205206 [C macro] C_word C_nfixnump(C_word x)207208Is {{x}} ''not'' a fixnum object?209210===== C_bignump211212 [C macro] C_word C_bignump(C_word x)213214Is {{x}} a Scheme bignum object? Accepts only non-immediate objects.215216===== C_i_numberp217218 [C function] C_word C_i_numberp(C_word x)219220Is {{x}} a number object (fixnum, bignum, flonum, ratnum, cplxnum)?221222===== C_i_bignump223224 [C function] C_word C_i_bignump(C_word x)225226Is {{x}} a Scheme bignum object?227228===== C_i_cplxnump229230 [C function] C_word C_i_cplxnump(C_word x)231232Is {{x}} a Scheme cplxnum object?233234===== C_i_ratnump235236 [C function] C_word C_i_ratnump(C_word x)237238Is {{x}} a Scheme ratnum object?239240===== C_i_flonump241242 [C function] C_word C_i_flonump(C_word x)243244Is {{x}} a flonum object?245246===== C_i_exact_integerp247248 [C macro] C_word C_i_exact_integerp(C_word x)249250Is {{x}} an exact integer (i.e., a fixnum or a bignum)?251252===== C_pointerp253254 [C macro] C_word C_pointerp(C_word x)255256Is {{x}} a C pointer object? Only accepts non-immediate objects.257258===== C_taggedpointerp259260 [C macro] C_word C_taggedpointerp(C_word x)261262Is {{x}} a tagged pointer object? Only accepts non-immediate objects.263264===== C_anypointerp265266 [C macro] C_word C_anypointerp(C_word x)267268Is {{x}} any type of pointer object? Only accepts non-immediate objects.269270===== C_lambdainfop271272 [C macro] C_word C_lambdainfop(C_word x)273274Is {{x}} a lambda-info object? Only accepts non-immediate objects.275276===== C_byteblockp277278 [C macro] C_word C_byteblockp(C_word x)279280Is {{x}} a "byteblock" object? Only accepts non-immediate objects.281282Strings, flonums, bytevectors and lambda-info objects are considered283"byteblock" objects, as they are not containers for Scheme objects but284simply point to contiguous memory ranges of bytes.285286===== C_specialp287288 [C macro] C_word C_specialp(C_word x)289290Is {{x}} a "special" object? Only accepts non-immediate objects.291292Closures, ports, pointers and locatives are considered "special"293objects, as they are not containers for Scheme objects (and they are294not byte blocks either), so they have to be treated specially by the GC.295296===== C_nullp297298 [C macro] C_word C_nullp(C_word x)299300Is {{x}} the empty list, i.e. is it {{C_SCHEME_END_OF_LIST}}?301302===== C_anyp303304 [C macro] C_word C_anyp(C_word x)305306Always returns {{C_SCHEME_TRUE}}.307308309=== Constructors310311==== Constructors for immediate Scheme objects312313"immediate" Scheme objects are objects that are represented directly314by a {{C_word}}. There's no additional memory used by them.315316===== C_fix317318 [C macro] C_word C_fix (int integer)319320===== C_make_character321322 [C macro] C_word C_make_character (int char_code)323324===== C_mk_bool325326 [C macro] C_word C_mk_bool(int truth_value)327328===== C_mk_nbool329330 [C macro] C_word C_mk_nbool(int truth_value_to_negate)331332===== C_SCHEME_END_OF_LIST333334 [C macro] C_SCHEME_END_OF_LIST335336===== C_SCHEME_END_OF_FILE337338 [C macro] C_SCHEME_END_OF_FILE339340===== C_SCHEME_FALSE341342 [C macro] C_SCHEME_FALSE343344===== C_SCHEME_TRUE345346 [C macro] C_SCHEME_TRUE347348349==== Constructors for non-immediate Scheme objects350351Non-immediate Scheme objects are still represented and passed around352by a single {{C_word}}, but this is basically just a pointer to the353start of the object (which should never be treated as such, use the354accessor macros instead).355356===== C_string357358 [C function] C_word C_string (C_word **ptr, int length, char *string)359360===== C_string2361362 [C function] C_word C_string2 (C_word **ptr, char *zero_terminated_string)363364===== C_intern365366 [C function] C_word C_intern (C_word **ptr, int length, char *string)367368===== C_intern2369370 [C function] C_word C_intern2 (C_word **ptr, char *zero_terminated_string)371372===== C_intern3373374 [C function] C_word C_intern3 (C_word **ptr, char *zero_terminated_string, C_word initial_value)375376===== C_a_pair377378 [C function] C_word C_a_pair (C_word **ptr, C_word car, C_word cdr)379380===== C_flonum381382 [C function] C_word C_flonum (C_word **ptr, double number)383384===== C_int_to_num385386 [C function] C_word C_int_to_num (C_word **ptr, int integer)387388===== C_mpointer389390 [C function] C_word C_mpointer (C_word **ptr, void *pointer)391392===== C_vector393394 [C function] C_word C_vector (C_word **ptr, int length, ...)395396===== C_bytevector397398 [C function] C_word C_bytevector (C_word **ptr, int length, C_char *data)399400===== C_structure401402 [C function] C_word C_structure (C_word **ptr, int length, ...)403404===== C_list405406 [C function] C_word C_list (C_word **ptr, int length, ...)407408===== C_closure409410 [C function] C_word C_closure (C_word **ptr, int length, C_word procedure, ...)411412These functions allocate memory from {{ptr}} and initialize a fresh413data object. The new data object is returned. {{ptr}} should be the414'''address''' of an allocation pointer created with {{C_alloc}}.415416To find out how big the memory block should be, use the {{C_SIZEOF_*}}417macros described below.418419Here's an example how to create a closure that accepts a vector,420stores the Scheme numbers 1, 2 and 3 and a given string in it and421returns that vector to its continuation:422423<enscript highlight=scheme>424#>425426#include <assert.h>427428void fill_vector(C_word c, C_word *av)429{430 C_word closure = av[0];431 C_word kontinuation = C_block_item(closure, 1);432 C_word vec = av[1];433434 C_block_item(vec, 0) = C_fix(1);435 C_block_item(vec, 1) = C_fix(2);436 C_block_item(vec, 2) = C_fix(3);437 C_block_item(vec, 3) = C_block_item(closure, 2);438439 C_kontinue(kontinuation, vec);440}441442void one_two_three(C_word continuation, C_word str)443{444 /*445 * Allocate room on the stack to hold the closure: 1 word for446 * the type tag, 1 word for the procedure and 2 words for the447 * values "closed over"; this procedure's continuation "k" and448 * the argument "str". We could also use C_alloc(4).449 */450 C_word closure[4], *cp = closure;451452 /* Allocate room for the argvector for C_allocate_vector */453 C_word av[6];454455 /* Create the closure. It holds 3 values, not counting the tag */456 C_word closure_object = C_closure(&cp, 3, (C_word)fill_vector, continuation, str);457458 /*459 * After this, cp points just beyond the last word of the allocated460 * data and closure_object is an opaque representation of the newly461 * created closure as a whole, i.e. the following relations hold:462 */463 assert( (closure + 4) == cp );464 assert( C_block_header(closure_object) == (*closure) );465 assert( C_data_pointer(closure_object) == (closure + 1) );466 assert( C_block_item(closure_object, 0) == (*(closure + 1)) );467468 /* Set up the arguments for C_allocate_vector */469 av[0] = (C_word)NULL; /* Closure of allocate_vector - unused, so pass NULL */470 av[1] = closure_object; /* Continuation to call after allocating Scheme vector */471 av[2] = C_fix(4); /* Size of Scheme vector to allocate */472 av[3] = C_SCHEME_FALSE; /* We want a regular vector, not a bytevector */473 av[4] = C_SCHEME_FALSE; /* Initialization value for slots. Don't care */474 av[5] = C_SCHEME_FALSE; /* Do not align at 8 byte (64-bit word) boundary */475 /* Make a vector of 4 objects and use closure_object as continuation */476 C_allocate_vector(6, av);477 /* .. C_allocate_vector does not return ... */478}479<#480481482(define one-two-three483 (foreign-primitive ((scheme-object str)) "one_two_three(C_k, str);"))484485(print (one-two-three "hi"))486</enscript>487488This is equivalent to the following in Scheme:489490<enscript highlight=scheme>491(define (one-two-three str)492 (let ((fill-vector (lambda (vec)493 (vector-set! vec 0 1)494 (vector-set! vec 1 2)495 (vector-set! vec 2 3)496 (vector-set! vec 3 str)497 vec)))498 (fill-vector (make-vector 4 #f))))499500(print (one-two-three "hi"))501</enscript>502503504==== Memory allocation505506These can be used to allocate memory for non-immediate objects.507508===== C_alloc509510 [C macro] C_word* C_alloc (int words)511512Allocates memory from the C stack ({{C_alloc}}) and returns a pointer to513it. {{words}} should be the number of words needed for all data514objects that are to be created in this function. Note that stack-allocated515data objects have to be passed to Scheme callback functions, or they will516not be seen by the garbage collector. This is really only usable for517callback procedure invocations, make sure not to use it in normal code,518because the allocated memory will be re-used after the foreign procedure519returns. When invoking Scheme callback procedures a minor garbage520collection is performed, so data allocated with {{C_alloc}}521will already have moved to a safe place.522523Note that {{C_alloc}} is really just a wrapper around {{alloca}},524and can also be simulated by declaring a stack-allocated array of525{{C_word}}s:526527528===== C_SIZEOF_LIST529530 [C macro] int C_SIZEOF_LIST (int length)531532Returns the size in words needed for allocation of a list with ''length'' elements.533534===== C_SIZEOF_STRING535536 [C macro] int C_SIZEOF_STRING (int length)537538Returns the size in words needed for allocation of a string with ''length'' characters.539540===== C_SIZEOF_BYTEVECTOR541542 [C macro] int C_SIZEOF_BYTEVECTOR (int length)543544Returns the size in words needed for allocation of a bytevector with ''length'' bytes of data.545546===== C_SIZEOF_VECTOR547548 [C macro] int C_SIZEOF_VECTOR (int length)549550Returns the size in words needed for allocation of vector with ''length'' elements.551552===== C_SIZEOF_CLOSURE553554 [C macro] int C_SIZEOF_CLOSURE (int length)555556Returns the size in words needed for allocation of a closure with {{length}} slots. The C function pointer also counts as a slot, so always remember to include it when calculating {{length}}.557558===== C_SIZEOF_STRUCT559560 [C macro] int C_SIZEOF_STRUCT (int length)561562Returns the size in words needed for allocation of a structure (record type) object with {{length}} slots. The structure's type tag also counts as a slot, so always remember to include it when calculating {{length}}.563564===== C_SIZEOF_BIGNUM565566 [C macro] int C_SIZEOF_BIGNUM (int length)567568Returns the size in words needed for allocation of a bignum object with {{length}} word-sized digits (limbs).569570===== C_SIZEOF_FIX_BIGNUM571572 [C macro] int C_SIZEOF_FIX_BIGNUM573574The size in words needed for allocation of a bignum object which is large enough to store any fixnum (ie, if it were converted to a denormalized bignum, because if a number ''can'' be represented as a fixnum, it ''will'' be).575576===== C_SIZEOF_INTERNED_SYMBOL577578 [C macro] int C_SIZEOF_INTERNED_SYMBOL (int length)579580===== C_SIZEOF_PAIR581582 [C macro] int C_SIZEOF_PAIR583584===== C_SIZEOF_FLONUM585586 [C macro] int C_SIZEOF_FLONUM587588===== C_SIZEOF_POINTER589590 [C macro] int C_SIZEOF_POINTER591592===== C_SIZEOF_LOCATIVE593594 [C macro] int C_SIZEOF_LOCATIVE595596===== C_SIZEOF_TAGGED_POINTER597598 [C macro] int C_SIZEOF_TAGGED_POINTER599600These are macros that return the size in words needed for a data object601of a given type.602603=== Accessors604605==== C_character_code606607 [C macro] int C_character_code (C_word character)608609==== C_unfix610611 [C macro] int C_unfix (C_word fixnum)612613==== C_flonum_magnitude614615 [C macro] double C_flonum_magnitude (C_word flonum)616617==== C_c_string618619 [C function] char* C_c_string (C_word string)620621==== C_num_to_int622623 [C function] int C_num_to_int (C_word fixnum_or_bignum)624625==== C_pointer_address626627 [C function] void* C_pointer_address (C_word pointer)628629These macros and functions can be used to convert Scheme data objects630back to C data. Note that {{C_c_string()}} takes a bytevector and returns631a pointer to the contents as a character pointer. If the bytevector is the632character sequence obtained from a string, then it is implicitly633zero-terminated.634635==== C_header_size636637 [C macro] int C_header_size (C_word x)638639==== C_header_bits640641 [C macro] int C_header_bits (C_word x)642643Return the number of elements and the type-bits of the non-immediate644Scheme data object {{x}}.645646647==== C_block_item648649 [C macro] C_word C_block_item (C_word x, int index)650651This macro can be used to access slots of the non-immediate Scheme data652object {{x}}. {{index}} specifies the index of the slot to653be fetched, starting at 0. Pairs have 2 slots, one for the '''car'''654and one for the '''cdr'''. Vectors have one slot for each element.655656657==== C_u_i_car658659 [C macro] C_word C_u_i_car (C_word x)660661==== C_u_i_cdr662663 [C macro] C_word C_u_i_cdr (C_word x)664665Aliases for {{C_block_item(x, 0)}} and {{C_block_item(x, 1)}}, respectively.666667==== C_port_file668669 [C macro] C_word C_port_file (C_word x)670671Alias for {{(FILE *)C_block_item(x, 0)}}. To be used with port672objects representing files (but will not work on sockets, for example).673674675==== C_data_pointer676677 [C macro] void* C_data_pointer (C_word x)678679Returns a pointer to the data-section of a non-immediate Scheme object.680681682=== C_make_header683684 [C macro] C_word C_make_header (C_word bits, C_word size)685686A macro to build a Scheme object header from its bits and size parts.687688689=== C_mutate690691 [C function] C_word C_mutate (C_word *slot, C_word val)692693Assign the Scheme value {{val}} to the location specified by694{{slot}}. If the value points to data inside the nursery (the first695heap-generation), then the garbage collector will remember to handle the696data appropriately. Assigning nursery-pointers directly will otherwise697result in lost data. Note that no copying takes place at the moment698when {{C_mutate}} is called, but later - at the next (minor) garbage699collection.700701702=== C_symbol_value703704 [C macro] C_word C_symbol_value (C_word symbol)705706Returns the global value of the variable with the name {{symbol}}. If the707variable is unbound {{C_SCHEME_UNBOUND}} is returned. You can set a variable's708value with {{C_mutate(&C_symbol_value(SYMBOL), VALUE)}}.709710711=== GC interface712713==== C_gc_protect714715 [C function] void C_gc_protect (C_word *ptrs[], int n)716717Registers {{n}} variables at address {{ptrs}} to be garbage collection roots.718The locations should not contain pointers to data allocated in the nursery, only719immediate values or pointers to heap-data are valid. Any720assignment of potential nursery data into a root-array should be done721via {{C_mutate()}}. The variables have to be initialized to sensible values722before the next garbage collection starts (when in doubt, set all locations723in {{ptrs}} to {{C_SCHEME_UNDEFINED}})724{{C_gc_protect}} may not called before the runtime system has been725initialized (either by {{CHICKEN_initialize}}, {{CHICKEN_run}} or726{{CHICKEN_invoke}}.727728For a slightly simpler interface to creating and using GC roots see729{{CHICKEN_new_gc_root}}.730731732==== C_gc_unprotect733734 [C function] void C_gc_unprotect (int n)735736Removes the last {{n}} registered variables from the set of737root variables.738739740==== C_pre_gc_hook741742 [C Variable] void (*C_pre_gc_hook)(int mode)743744If not {{NULL}}, the function pointed to by this variable will be745called before each garbage collection with a flag indicating what kind746of collection was performed (either {{0}} for a minor or major747collection or {{2}} for a resizing collection). A "resizing"748collection means a secondary collection that moves all live data into749a enlarged (or shrinked) heap-space. Minor collections happen very750frequently, so the hook function should not consume too much time. The751hook function may not invoke Scheme callbacks.752753Note that resizing collections may be nested in normal major collections.754755==== C_post_gc_hook756757 [C Variable] void (*C_post_gc_hook)(int mode, long ms)758759If not {{NULL}}, the function pointed to by this variable will be760called after each garbage collection with a flag indicating what kind761of collection was performed (either {{0}} for a minor collection,762{{1}} for a major collection or {{2}} for a resizing763collection). Minor collections happen very frequently, so the hook764function should not consume too much time. The hook function may not765invoke Scheme callbacks. The {{ms}} argument records the number of766milliseconds required for the garbage collection, if the collection767was a major one. For minor collections the value of the {{ms}} argument768is undefined.769770=== Type-specific macros and functions771772The following are macros and functions to ask information or perform773operations on objects once their types are already known. If you call774it on any object of another type, it is not defined what will happen775and likely your program will crash, especially if you pass immediates776to procedures expecting non-immediates.777778==== Vectors779780===== C_vemptyp781782 [C macro] C_word C_vemptyp(C_word v)783784Is the (byte- or heterogenous) vector {{v}} empty?785786===== C_notvemptyp787788 [C macro] C_word C_notvemptyp(C_word v)789790Is the (byte- or heterogenous) vector {{v}} nonempty?791792==== Numbers793794These procedures accept any type of number, so you can pass in a795fixnum, a flonum, a bignum, a ratnum or a cplxnum. You shouldn't pass796in another type though, since that could crash your program.797798===== C_u_i_exactp799800 [C macro] C_word C_u_i_exactp(C_word x)801802Is {{x}} an exact number (i.e., a fixnum, bignum, ratnum or exact cplxnum)?803804===== C_u_i_inexactp805806 [C macro] C_word C_u_i_inexactp(C_word x)807808Is {{x}} an inexact number (i.e., a flonum or an inexact cplxnum)?809810===== C_i_finitep811812 [C function] C_word C_i_finitep(C_word x)813814Is {{x}} a finite number? This returns false only when {{x}} is a815flonum representing {{-inf}} or {{+inf}}.816817==== Bignums818819===== C_bignum_negativep820821 [C macro] int C_bignum_negativep(C_word b)822823Returns nonzero if the bignum {{b}} is negative, zero if it is not.824825===== C_bignum_digits826827 [C macro] C_uword *C_bignum_digits(C_word b)828829Returns a pointer to the first digit (the least significant one) of the bignum {{b}}.830831===== C_bignum_size832833 [C macro] C_word C_bignum_size(b)834835Returns the number of digits in the bignum {{b}}, as an unboxed C number. If you want a fixnum, use {{C_u_i_bignum_size}}.836837===== C_u_i_bignum_size838839 [C macro] C_word C_u_i_bignum_size(b)840841Returns the number of digits in the bignum {{b}}, as a Scheme fixnum. If you want an unboxed integer, use {{C_bignum_size}}.842843===== C_i_bignum_cmp844845 [C macro] C_word C_i_bignum_cmp(x, y)846847Compares the bignums {{x}} and {{y}} and returns the fixnums {{-1}}, {{0}} or {{1}} if {{x}} is less than, equal to or greater than {{y}}, respectively.848849==== Fixnums850851Note: Fixnums are immediates, so there is no {{C_fixnum_equalp}}852macro. You can just compare them without hassle (or use853[[#c-eqp|C_eqp]] if you prefer).854855===== C_i_fixnumevenp856857 [C macro] C_word C_i_fixnumevenp(C_word x)858859Is {{x}} an even fixnum?860861===== C_i_fixnumoddp862863 [C macro] C_word C_i_fixnumoddp(C_word x)864865Is {{x}} an odd fixnum?866867===== C_fixnum_times868869 [C macro] C_word C_fixnum_times(C_word n1, C_word n2)870871Multiply fixnum n1 by fixnum n2. Will not overflow into a bignum, but872will handle overflows safely in the sense that it always produces a873fixnum.874875===== C_a_i_fixnum_times876877 [C macro] C_word C_a_i_fixnum_times(C_word **ptr, C_word n, C_word x, C_word y)878879Calculate {{x}} * {{y}}, safely overflowing into a bignum, using the880storage in {{ptr}} (which should be at least {{C_SIZEOF_BIGNUM(2)}}).881882883===== C_fixnum_plus884885 [C macro] C_word C_fixnum_plus(C_word n1, C_word n2)886887Add fixnum {{n1}} to fixnum {{n2}}. Will not overflow into a bignum,888but will handle overflows safely in the sense that it always produces889a fixnum.890891===== C_u_fixnum_plus892893 [C macro] C_word C_u_fixnum_plus(C_word n1, C_word n2)894895Like {{C_fixnum_plus}}, but unsafe (assumes no overflow/underflow).896897===== C_a_i_fixnum_plus898899 [C macro] C_word C_a_i_fixnum_plus(C_word **ptr, C_word n, C_word x, C_word y)900901Calculate {{x}} + {{y}}, safely overflowing into a bignum, using the902storage in {{ptr}} (which should be at least {{C_SIZEOF_FIX_BIGNUM}}).903904===== C_fixnum_difference905906 [C macro] C_word C_fixnum_difference(C_word n1, C_word n2)907908Calculate {{n1}} - {{n2}}. Will not overflow into a bignum, but will909handle overflows safely in the sense that it always produces a fixnum.910911===== C_u_fixnum_difference912913 [C macro] C_word C_u_fixnum_difference(C_word n1, C_word n2)914915Like {{C_fixnum_difference}}, but unsafe (assumes no overflow/underflow).916917===== C_a_i_fixnum_difference918919 [C macro] C_word C_a_i_fixnum_difference(C_word **ptr, C_word n, C_word x, C_word y)920921Calculate {{x}} - {{y}}, safely overflowing into a bignum, using the922storage in {{ptr}} (which should be at least {{C_SIZEOF_FIX_BIGNUM}}).923924925===== C_fixnum_divide926===== C_u_fixnum_divide927928 [C macro] C_word C_fixnum_divide(C_word n1, C_word n2)929 [C macro] C_word C_u_fixnum_divide(C_word n1, C_word n2)930931Divide {{n1}} by {{n2}}, returning the quotient (i.e., integer932division). {{C_fixnum_divide}} signals an error if {{n2}} is zero.933934===== C_fixnum_modulo935===== C_u_fixnum_modulo936937 [C macro] C_word C_fixnum_modulo(C_word n1, C_word n2)938 [C macro] C_word C_u_fixnum_modulo(C_word n1, C_word n2)939940Calculate {{n1}} modulo {{n2}}. {{C_fixnum_modulo}} signals an error if {{n2}} is zero. Neither handles overflow into bignums.941942===== C_a_i_fixnum_quotient_checked943944 [C macro] C_word C_a_i_fixnum_quotient_checked(C_word **ptr, C_word n, C_word x, C_word y)945946Calculate integer division of {{x}} / {{y}}, safely overflowing into a947bignum (which can happen when dividing by {{C_MOST_NEGATIVE_FIXNUM}}),948using the storage in {{ptr}} (which should be at least949{{C_SIZEOF_FIX_BIGNUM}}). If {{y}} is zero, this will signal an950error.951952===== C_i_fixnum_remainder_checked953954 [C macro] C_word C_i_fixnum_remainder_checked(C_word x, C_word y)955956Calculate the remainder of integer division {{x}} / {{y}}. If {{y}}957is zero, this will signal an error.958959960===== C_fixnum_and961962 [C macro] C_word C_fixnum_and(C_word n1, C_word n2)963964Calculate the bitwise {{AND}} of the integral values of {{n1}} and {{n2}}.965966===== C_u_fixnum_and967968 [C macro] C_word C_u_fixnum_and(C_word n1, C_word n2)969970Like {{C_fixnum_and}}, but unsafe.971972===== C_fixnum_or973974 [C macro] C_word C_fixnum_or(C_word n1, C_word n2)975976Calculate the bitwise {{OR}} of the integral values of {{n1}} and {{n2}}.977978===== C_u_fixnum_or979980 [C macro] C_word C_u_fixnum_or(C_word n1, C_word n2)981982Like {{C_fixnum_or}}, but unsafe.983984===== C_fixnum_xor985986 [C macro] C_word C_fixnum_xor(C_word n1, C_word n2)987988Calculate the bitwise {{XOR}} of the integral values of {{n1}} and {{n2}}.989990===== C_fixnum_not991992 [C macro] C_word C_fixnum_not(C_word n)993994Calculate the bitwise {{NOT}} (inversion of bits) of the integral995value of {{n}}.996997===== C_fixnum_shift_left998999 [C macro] C_word C_fixnum_shift_left(C_word n1, C_word n2)10001001Shift the integral value of {{n1}} left by {{n2}} positions.10021003===== C_fixnum_shift_right10041005 [C macro] C_word C_fixnum_shift_right(C_word n1, C_word n2)10061007Shift the integral value of {{n1}} right by {{n2}}10081009===== C_fixnum_negate10101011 [C macro] C_word C_fixnum_negate(C_word n)10121013Negate {{n}}, i.e. return {{-n}}. This will ''not'' overflow into a1014bignum.10151016===== C_a_i_fixnum_negate10171018 [C macro] C_word C_a_i_fixnum_negate(C_word **ptr, C_word n, C_word x)10191020Negate {{n}}, i.e. return {{-n}}. This will not overflow into a1021bignum, using the storage pointed to by {{ptr}}, which should at least1022be {{C_SIZEOF_FIX_BIGNUM}}.102310241025===== C_fixnum_greaterp10261027 [C macro] C_word C_fixnum_greaterp(C_word n1, C_word n2)10281029Returns {{C_SCHEME_TRUE}} when {{n1}} is greater than {{n2}},1030{{C_SCHEME_FALSE}} if not.10311032===== C_fixnum_greater_or_equal_p10331034 [C macro] C_word C_fixnum_greater_or_equalp(C_word n1, C_word n2)10351036Returns {{C_SCHEME_TRUE}} when {{n1}} is greater than or equal to1037{{n2}}, {{C_SCHEME_FALSE}} if not.10381039===== C_fixnum_lessp10401041 [C macro] C_word C_fixnum_lessp(C_word n1, C_word n2)10421043Returns {{C_SCHEME_TRUE}} when {{n1}} is less than {{n2}},1044{{C_SCHEME_FALSE}} if not.10451046===== C_fixnum_less_or_equal_p10471048 [C macro] C_word C_fixnum_less_or_equalp(C_word n1, C_word n2)10491050Returns {{C_SCHEME_TRUE}} when {{n1}} is less than or equal to1051{{n2}}, {{C_SCHEME_FALSE}} if not.10521053===== C_i_fixnum_positivep10541055 [C macro] C_word C_i_fixnum_positivep(C_word n)10561057Returns {{C_SCHEME_TRUE}} when {{n}} is a positive fixnum,1058{{C_SCHEME_FALSE}} if it is zero or negative.10591060===== C_i_fixnum_negativep10611062 [C macro] C_word C_i_fixnum_negativep(C_word n)10631064Returns {{C_SCHEME_TRUE}} when {{n}} is a negative fixnum,1065{{C_SCHEME_FALSE}} if it is zero or positive.10661067===== C_fixnum_increase10681069 [C macro] C_word C_fixnum_increase(C_word n)10701071Adds 1 to {{n}}10721073===== C_u_fixnum_increase10741075 [C macro] C_word C_u_fixnum_increase(C_word n)10761077As {{C_fixnum_increase}}, but unsafe (assumes the result will not overflow).10781079===== C_fixnum_decrease10801081 [C macro] C_word C_fixnum_decrease(C_word n)10821083Subtracts 1 from {{n}}10841085===== C_u_fixnum_decrease10861087 [C macro] C_word C_u_fixnum_decrease(C_word n)10881089As {{C_fixnum_increase}}, but unsafe (assumes the result will not underflow).10901091===== C_fixnum_abs10921093 [C macro] C_word C_fixnum_abs(C_word n)10941095Returns the absolute value of {{n}}.10961097===== C_i_fixnum_min10981099 [C function] C_word C_i_fixnum_min(C_word n1, C_word n2)11001101Returns the smallest of the two fixnums {{n1}} and {{n2}}.11021103===== C_i_fixnum_max11041105 [C function] C_word C_i_fixnum_max(C_word n1, C_word n2)11061107Returns the largest of the two fixnums {{n1}} and {{n2}}.11081109===== C_i_fixnum_gcd11101111 [C function] C_word C_i_fixnum_gcd(C_word n1, C_word n2)11121113Returns the greatest common divisor of the two fixnums {{n1}} and {{n2}}.11141115===== C_i_fixnum_length11161117 [C function] C_word C_i_fixnum_length(C_word x)11181119Returns the integer length in bits of the fixnum {{x}} (as a fixnum).112011211122==== Flonums11231124===== C_flonum_equalp11251126 [C macro] C_word C_flonum_equalp(C_word n1, C_word n2)11271128Returns {{C_SCHEME_TRUE}} when {{n1}} and {{n2}} are equal flonums,1129{{C_SCHEME_FALSE}} otherwise.11301131===== C_flonum_greaterp11321133 [C macro] C_word C_flonum_greaterp(C_word n1, C_word n2)11341135Returns {{C_SCHEME_TRUE}} when {{n1}} is greater than {{n2}},1136{{C_SCHEME_FALSE}} if not.11371138===== C_flonum_greater_or_equal_p11391140 [C macro] C_word C_flonum_greater_or_equal_p(C_word n1, C_word n2)11411142Returns {{C_SCHEME_TRUE}} when {{n1}} is greater than or equal to {{n2}},1143{{C_SCHEME_FALSE}} if not.11441145===== C_flonum_lessp11461147 [C macro] C_word C_flonum_lessp(C_word n1, C_word n2)11481149Returns {{C_SCHEME_TRUE}} when {{n1}} is less than {{n2}},1150{{C_SCHEME_FALSE}} if not.11511152===== C_flonum_less_or_equal_p11531154 [C macro] C_word C_flonum_less_or_equal_p(C_word n1, C_word n2)11551156Returns {{C_SCHEME_TRUE}} when {{n1}} is less than or equal to {{n2}},1157{{C_SCHEME_FALSE}} if not.11581159===== C_a_i_flonum_plus11601161 [C macro] C_word C_a_i_flonum_plus(C_word **ptr, int c, C_word n1, C_word n2)11621163Adds the flonum {{n1}} to the flonum {{n2}}, using the storage at1164{{ptr}}. {{c}} should always be 2.11651166Example:11671168<enscript highlight=scheme>1169#include <chicken.h>1170#include <stdio.h>11711172int main(void)1173{1174 C_word *mema, *memb, *memresult;1175 C_word a, b, result;11761177 mema = C_alloc(C_SIZEOF_FLONUM);1178 memb = C_alloc(C_SIZEOF_FLONUM);1179 memresult = C_alloc(C_SIZEOF_FLONUM);1180 a = C_flonum(&mema, 1.2);1181 b = C_flonum(&memb, 4.7);1182 result = C_a_i_flonum_plus(&memresult, 2, a, b);1183 printf("%lf\n", C_flonum_magnitude(result));1184 return 0;1185}1186</enscript>11871188This will print {{5.9}}11891190===== C_a_i_flonum_difference11911192 [C macro] C_word C_a_i_flonum_difference(C_word **ptr, int c, C_word n1, C_word n2)11931194Subtracts the flonum {{n2}} from the flonum {{n1}}, using the storage at1195{{ptr}}. {{c}} should always be 2.11961197===== C_a_i_flonum_times11981199 [C macro] C_word C_a_i_flonum_times(C_word **ptr, int c, C_word n1, C_word n2)12001201Multiplies the flonum {{n1}} by the flonum {{n2}}, using the storage at1202{{ptr}}. {{c}} should always be 2.12031204===== C_a_i_flonum_quotient12051206 [C macro] C_word C_a_i_flonum_quotient(C_word **ptr, int c, C_word n1, C_word n2)1207 [C macro] C_word C_a_i_flonum_quotient_checked(C_word **ptr, int c, C_word n1, C_word n2)12081209These are misnamed because they don't calculate the Scheme "quotient",1210but the simple result of flonum {{n1}} divided by the flonum {{n2}},1211using the storage at {{ptr}}. {{c}} should always be 2.12121213{{C_a_i_flonum_quotient_checked}} will signal an error if {{n2}} is zero.12141215===== C_a_i_flonum_actual_quotient_checked12161217 [C macro] C_word C_a_i_flonum_actual_quotient_checked(C_word **ptr, int c, C_word n1, C_word n2)12181219Due to the misnaming of {{C_a_i_flonum_quotient[_checked]}}, this1220function has a peculiar name. It calculates the Scheme integer1221quotient of {{n1}} divided by {{n2}}, using the storage at {{ptr}}.1222{{c}} should always be 2.12231224If {{n2}} is zero or either of the numbers is not an integral flonum,1225an error will be signaled.12261227===== C_a_i_flonum_gcd12281229 [C macro] C_word C_a_i_flonum_gcd(C_word **ptr, int c, C_word n1, C_word n2)12301231Calculates the greatest common divisor of the flonums {{n1}} and1232{{n2}}, using the storage at {{ptr}}. {{c}} should always be 2.12331234===== C_a_i_flonum_negate12351236 [C macro] C_word C_a_i_flonum_negate(C_word **ptr, int c, C_word n)12371238Negates the flonum {{n}}, using the storage at {{ptr}}. {{c}} should1239always be 1.12401241===== C_a_i_flonum_truncate12421243 [C macro] C_word C_a_i_flonum_truncate(C_word **ptr, int c, C_word n)12441245Truncate the flonum {{n}}, using the storage at {{ptr}}. {{c}} should1246always be 1.12471248===== C_a_i_flonum_ceiling12491250 [C macro] C_word C_a_i_flonum_ceiling(C_word **ptr, int c, C_word n)12511252Round the flonum {{n}}, rounding upwards, using the storage at1253{{ptr}}. {{c}} should always be 1.12541255===== C_a_i_flonum_floor12561257 [C macro] C_word C_a_i_flonum_floor(C_word **ptr, int c, C_word n)12581259Round the flonum {{n}}, rounding downwards, using the storage at1260{{ptr}}. {{c}} should always be 1.12611262===== C_a_i_flonum_round12631264 [C macro] C_word C_a_i_flonum_round(C_word **ptr, int c, C_word n)12651266Round the flonum {{n}}, rounding towards the nearest integer, using1267the storage at {{ptr}}. {{c}} should always be 1.12681269This macro returns the value like returned by C's {{round()}}1270function. That means it rounds to the larger value (away from 0) when1271rounding numbers halfway between two integers.12721273===== C_a_i_flonum_round_proper12741275 [C macro] C_word C_a_i_flonum_round_proper(C_word **ptr, int c, C_word n)12761277Round the flonum {{n}}, rounding towards the nearest integer, using1278the storage at {{ptr}}. {{c}} should always be 1.12791280This macro returns the value like returned by Scheme's {{round}}1281procedure. That means it rounds to even numbers when rounding1282numbers halfway between two integers.12831284===== C_a_i_flonum_sin12851286 [C macro] C_word C_a_i_flonum_sin(C_word **ptr, int c, C_word n)12871288Calculates the sine of {{n}} (in radians).12891290===== C_a_i_flonum_cos12911292 [C macro] C_word C_a_i_flonum_cos(C_word **ptr, int c, C_word n)12931294Calculates the cosine of {{n}} (in radians).12951296===== C_a_i_flonum_tan12971298 [C macro] C_word C_a_i_flonum_tan(C_word **ptr, int c, C_word n)12991300Calculates the tangent of {{n}} (in radians).13011302===== C_a_i_flonum_asin13031304 [C macro] C_word C_a_i_flonum_asin(C_word **ptr, int c, C_word n)13051306Calculates the arc sine of {{n}} (in radians, in the range -pi/2 through +pi/2).13071308===== C_a_i_flonum_acos13091310 [C macro] C_word C_a_i_flonum_acos(C_word **ptr, int c, C_word n)13111312Calculates the arc cosine of {{n}} (in radians, in the range 0 through pi).13131314===== C_a_i_flonum_atan13151316 [C macro] C_word C_a_i_flonum_atan(C_word **ptr, int c, C_word n)13171318Calculates the arc tangent of {{n}} (in radians, in the range -pi/2 through +pi/2).13191320Like C's {{atan()}} or Scheme's unary {{atan}}.13211322===== C_a_i_flonum_atan213231324 [C macro] C_word C_a_i_flonum_atan2(C_word **ptr, int c, C_word n1, C_word n2)13251326Calculates the arc tangent of {{n1/n2}} (in radians), using the sign of both1327to determine the quadrant of the result.13281329Like C's {{atan2()}} or Scheme's binary {{atan}}.13301331===== C_a_i_flonum_log13321333 [C macro] C_word C_a_i_flonum_log(C_word **ptr, int c, C_word n)13341335Calculate the natural (base {{e}}) logarithm of {{n}}.13361337===== C_a_i_flonum_exp13381339 [C macro] C_word C_a_i_flonum_exp(C_word **ptr, int c, C_word n)13401341Calculates the base {{e}} exponent of {{n}} (i.e., the inverse1342operation of {{C_a_i_flonum_log}}).13431344===== C_a_i_flonum_expt13451346 [C macro] C_word C_a_i_flonum_expt(C_word **ptr, int c, C_word n1, C_word n2)13471348Calculates {{n1}} raised to the power {{n2}}.13491350===== C_a_i_flonum_sqrt13511352 [C macro] C_word C_a_i_flonum_sqrt(C_word **ptr, int c, C_word n)13531354Calculates the square root of {{n}}.13551356===== C_a_i_flonum_abs13571358 [C macro] C_word C_a_i_flonum_abs(C_word **ptr, int c, C_word n)13591360Calculates the absolute value of {{n}}.13611362===== C_u_i_flonum_nanp13631364 [C macro] C_word C_u_i_flonum_nanp(C_word n)13651366Is {{n}} a flonum NaN value?13671368===== C_u_i_flonum_finitep13691370 [C macro] C_word C_u_i_flonum_finitep(C_word n)13711372Is {{n}} a finite flonum (i.e., not NaN or one of the infinities)?13731374===== C_u_i_flonum_infinitep13751376 [C macro] C_word C_u_i_flonum_infinitep(C_word n)13771378Is {{n}} an infinite flonum?13791380==== Exact integers13811382Often you know a value is an integer, but you don't know whether it's1383a fixnum or a bignum. In those cases, there are some optimized C1384functions and macros to perform operations on them.13851386===== C_i_integer_evenp13871388 [C macro] C_word C_i_integer_evenp(C_word n)13891390Returns {{C_SCHEME_TRUE}} when {{n}} is an even fixnum or bignum,1391{{C_SCHEME_FALSE}} if it is odd.13921393===== C_i_integer_oddp13941395 [C macro] C_word C_i_integer_oddp(C_word n)13961397Returns {{C_SCHEME_TRUE}} when {{n}} is an odd fixnum or bignum,1398{{C_SCHEME_FALSE}} if it is even.13991400===== C_i_integer_positivep14011402 [C macro] C_word C_i_integer_positivep(C_word n)14031404Returns {{C_SCHEME_TRUE}} when {{n}} is a positive fixnum or bignum,1405{{C_SCHEME_FALSE}} if it is zero or negative.14061407===== C_i_integer_negativep14081409 [C macro] C_word C_i_integer_negativep(C_word n)14101411Returns {{C_SCHEME_TRUE}} when {{n}} is a negative fixnum or bignum,1412{{C_SCHEME_FALSE}} if it is zero or positive.14131414===== C_i_integer_equalp14151416 [C macro] C_word C_i_integer_equalp(x, y)14171418Returns {{C_SCHEME_TRUE}} when {{x}} and {{y}} are numerically equal,1419{{C_SCHEME_FALSE}} if they differ.14201421===== C_i_integer_greaterp14221423 [C macro] C_word C_i_integer_greaterp(x, y)14241425Returns {{C_SCHEME_TRUE}} when {{x}} is greater than {{y}},1426{{C_SCHEME_FALSE}} if it is equal or less.14271428===== C_i_integer_greater_or_equalp14291430 [C macro] C_word C_i_integer_greaterp(x, y)14311432Returns {{C_SCHEME_TRUE}} when {{x}} is greater than or equal to {{y}},1433{{C_SCHEME_FALSE}} if it is less.14341435===== C_i_integer_lessp14361437 [C macro] C_word C_i_integer_lessp(x, y)14381439Returns {{C_SCHEME_TRUE}} when {{x}} is less than {{y}},1440{{C_SCHEME_FALSE}} if it is equal or greater.14411442===== C_i_integer_less_or_equalp14431444 [C macro] C_word C_i_integer_less_or_equalp(x, y)14451446Returns {{C_SCHEME_TRUE}} when {{x}} is less than or equal to {{y}},1447{{C_SCHEME_FALSE}} if it is greater.144814491450==== Pointers14511452===== C_null_pointerp14531454 [C macro] C_word C_null_pointerp(C_word x)14551456Is {{x}} a NULL pointer?14571458===== C_a_i_address_to_pointer14591460 [C macro] C_word C_a_i_address_to_pointer(C_word **ptr, int c, C_word addr)14611462Convert {{addr}} to a pointer object using the storage at {{ptr}}.1463{{addr}} is can be either a flonum or a fixnum representing a memory1464address.14651466===== C_a_i_pointer_to_address14671468 [C macro] C_word C_a_i_pointer_to_address(C_word **ptr, int c, C_word pptr)14691470Convert back the pointer {{pptr}} to an address number, possibly using1471the storage at {{ptr}}. The number returned can be either a fixnum or1472a flonum, so you will have to pass a memory storage that can hold a1473flonum at {{ptr}}. Whether it is actually used depends on the size of1474the address.147514761477==== Ports14781479===== C_tty_portp14801481 [C macro] C_word C_tty_portp(C_word x)14821483Is {{x}} a TTY port object?14841485==== Structures14861487===== C_i_structurep14881489 [C macro] C_word C_i_structurep(C_word x, C_word s)14901491Is {{x}} a structure (record) object with type tag {{s}}? This is1492completely safe to use, because it checks whether x is an immediate or1493not.14941495==== Characters14961497These understand only ASCII characters.14981499===== C_u_i_char_alphabeticp15001501 [C macro] C_word C_u_i_char_alphabeticp(C_word c)15021503Is {{c}} an alphabetic character?15041505===== C_u_i_char_numericp15061507 [C macro] C_word C_u_i_char_numericp(C_word c)15081509Is {{c}} a numeric character?15101511===== C_u_i_char_whitespacep15121513 [C macro] C_word C_u_i_char_whitespacep(C_word c)15141515Is {{c}} a whitespace character?15161517===== C_u_i_char_upper_casep15181519 [C macro] C_word C_u_i_char_upper_casep(C_word c)15201521Is {{c}} an uppercase character?15221523===== C_u_i_char_lower_casep15241525 [C macro] C_word C_u_i_char_lower_casep(C_word c)15261527Is {{c}} a lowercase character?152815291530=== Other Scheme procedures from C15311532There are a number of Scheme procedures that have a direct C1533implementation, so you can call them from C too.15341535==== C_eqp15361537 [C macro] C_word C_eqp(C_word a, C_word b)15381539The C version of {{(eq? a b)}}.15401541==== C_equalp15421543 [C macro] C_word C_equalp(C_word a, C_word b)15441545The C version of {{(equal? a b)}}.15461547==== C_i_pairp15481549 [C function] C_word C_i_pairp(C_word x)15501551The C version of {{(pair? x)}}.15521553==== C_i_not_pair_p15541555 [C macro] C_word C_i_not_pair_p(C_word x)15561557The C version of {{(not (pair? x))}}.155815591560=== An example for simple calls to foreign code involving callbacks15611562 % cat foo.scm1563 #>1564 extern int callout(int, int, int);1565 <#15661567 (define callout (foreign-safe-lambda int "callout" int int int))15681569 (define-external (callin (scheme-object xyz)) int1570 (print "This is 'callin': " xyz)1571 123)15721573 (print (callout 1 2 3))15741575 % cat bar.c1576 #include <stdio.h>1577 #include "chicken.h"15781579 extern int callout(int, int, int);1580 extern int callin(C_word x);15811582 int callout(int x, int y, int z)1583 {1584 C_word *ptr = C_alloc(C_SIZEOF_LIST(3));1585 C_word lst;15861587 printf("This is 'callout': %d, %d, %d\n", x, y, z);1588 lst = C_list(&ptr, 3, C_fix(x), C_fix(y), C_fix(z));1589 return callin(lst); /* Note: `callin' will have GC'd the data in `ptr' */1590 }15911592 % csc foo.scm bar.c -o foo1593 % foo1594 This is 'callout': 1, 2, 31595 This is 'callin': (1 2 3)1596 123159715981599=== Notes:16001601* Scheme procedures can call C functions, and C functions can call1602 Scheme procedures, but for every pending C stack frame, the available1603 size of the first heap generation (the ''nursery'') will be decreased,1604 because the C stack is identical to the nursery. On systems with a small1605 nursery this might result in thrashing, since the C code between the1606 invocation of C from Scheme and the actual calling back to Scheme might1607 build up several stack-frames or allocates large amounts of stack data.1608 To prevent this it is advisable to increase the default nursery size,1609 either when compiling the file (using the {{-nursery}} option)1610 or when running the executable (using the {{-:s}} runtime option).1611* Calls to Scheme/C may be nested arbitrarily, and Scheme1612 continuations can be invoked as usual, but keep in mind that C stack1613 frames will not be recovered, when a Scheme procedure call from C does1614 not return normally.1615* When multiple threads are running concurrently, and control switches1616 from one thread to another, then the continuation of the current thread1617 is captured and saved. Any pending C stack frame still active from a1618 callback will remain on the stack until the threads is re-activated1619 again. This means that in a multithreading situation, when C callbacks1620 are involved, the available nursery space can be smaller than expected.1621 So doing many nested Scheme->C->Scheme calls can reduce the available1622 memory up to the point of thrashing. It is advisable to have only a1623 single thread with pending C stack-frames at any given time.1624* Pointers to Scheme data objects should not be stored in local or1625 global variables while calling back to Scheme. Any Scheme object not1626 passed back to Scheme will be reclaimed or moved by the garbage collector.1627* Calls from C to Scheme are never tail-recursive.1628* Continuations captured via {{call-with-current-continuation}}1629 and passed to C code can be invoked like any other Scheme procedure.163016311632---1633Previous: [[Embedding]]16341635Next: [[Data representation]]