C_truep

C_immediatep

C_fitsinfixnump

[C macro] int C_fitsinfixnump(int number)

Will number fit in a fixnum? It will fit when there is room for one additional type bit to tag it as a fixnum (assuming one bit is already used for the sign). In practice this means that the number's top two bits must be identical.

C_ufitsinfixnump

[C macro] int C_ufitsinfixnump(unsigned int number)

Like C_fitsinfixnump but for unsigned integers. This checks the top two bits are zero, since fixnums always carry a sign.

Scheme predicates

These return Scheme booleans (ie, C_SCHEME_TRUE or C_SCHEME_FALSE). This means they can be used directly from Scheme using ##core#inline.

C_zero_length_p

[C macro] C_word C_zero_length_p(C_word x)

Is x a Scheme object of zero length? Only accepts non-immediate objects.

C_unboundvaluep

[C macro] C_word C_unboundvaluep(C_word x)

Is x the special unbound variable placeholder C_SCHEME_UNBOUND?

C_boundp

[C macro] C_word C_boundp(C_word x)

Is x a bound value? Only accepts non-immediate objects.

C_blockp

[C macro] C_word C_blockp(C_word x)

Is x a "block" value?

A "block" value is a value that contains a memory block, i.e. is not an immediate value.

C_immp

[C macro] C_word C_immp(C_word x)

Is x an immediate value?

C_forwardedp

[C macro] C_word C_forwardedp(C_word x)

Is x a GC-forwarded object?

C_flonump

[C macro] C_word C_flonump(C_word x)

Is x a Scheme flonum object? Accepts only non-immediate objects.

C_stringp

[C macro] C_word C_stringp(C_word x)

Is x a Scheme string object? Accepts only non-immediate objects.

C_symbolp

[C macro] C_word C_symbolp(C_word x)

Is x a symbol? Accepts only non-immediate objects.

C_pairp

[C macro] C_word C_pairp(C_word x)

Is x a pair? Accepts only non-immediate objects.

C_closurep

[C macro] C_word C_closurep(C_word x)

Is x a closure? Accepts only non-immediate objects.

C_vectorp

[C macro] C_word C_vectorp(C_word x)

Is x any kind of vector? Accepts only non-immediate objects.

This returns true for both regular heterogenous R5RS vectors and bytevectors ("blobs"). However, it does not return true for SRFI-4 vectors, as those are actually bytevectors wrapped in a structure with a type tag.

C_bytevectorp

[C macro] C_word C_bytevectorp(C_word x)

Is x a bytevector ("blob")? Accepts only non-immediate objects.

C_portp

[C macro] C_word C_portp(C_word x)

Is x a port object? Accepts only non-immediate objects.

C_structurep

[C macro] C_word C_structure(C_word x)

Is x a structure (record) object? Accepts only non-immediate objects.

C_locativep

[C macro] C_word C_locativep(C_word x)

Is x a locative object? Accepts only non-immediate objects.

C_charp

[C macro] C_word C_charp(C_word x)

Is x a character object?

C_booleanp

[C macro] C_word C_booleanp(C_word x)

Is x a boolean object?

C_eofp

[C macro] C_word C_eofp(C_word x)

Is x the #!eof object?

C_undefinedp

[C macro] C_word C_undefinedp(C_word x)

Is x the undefined value?

C_fixnump

[C macro] C_word C_fixnump(C_word x)

Is x a fixnum object?

C_nfixnump

[C macro] C_word C_nfixnump(C_word x)

Is xnot a fixnum object?

C_i_numberp

[C function] C_word C_i_numberp(C_word x)

Is x a number object (fixnum or flonum)?

C_pointerp

[C macro] C_word C_pointerp(C_word x)

Is x a C pointer object? Only accepts non-immediate objects.

C_taggedpointerp

[C macro] C_word C_taggedpointerp(C_word x)

Is x a tagged pointer object? Only accepts non-immediate objects.

C_swigpointerp

[C macro] C_word C_swigpointerp(C_word x)

Is x a SWIG pointer object? Only accepts non-immediate objects.

C_anypointerp

[C macro] C_word C_anypointerp(C_word x)

Is x any type of pointer object? Only accepts non-immediate objects.

C_lambdainfop

[C macro] C_word C_lambdainfop(C_word x)

Is x a lambda-info object? Only accepts non-immediate objects.

C_byteblockp

[C macro] C_word C_byteblockp(C_word x)

Is x a "byteblock" object? Only accepts non-immediate objects.

Strings, flonums, bytevectors and lambda-info objects are considered "byteblock" objects, as they are not containers for Scheme objects but simply point to contiguous memory ranges of bytes.

C_specialp

[C macro] C_word C_specialp(C_word x)

Is x a "special" object? Only accepts non-immediate objects.

Closures, ports, pointers and locatives are considered "special" objects, as they are not containers for Scheme objects (and they are not byte blocks either), so they have to be treated specially by the GC.

C_nullp

[C macro] C_word C_nullp(C_word x)

Is x the empty list, i.e. is it C_SCHEME_END_OF_LIST?

C_anyp

[C macro] C_word C_anyp(C_word x)

Always returns C_SCHEME_TRUE.

Constructors

Constructors for immediate Scheme objects

"immediate" Scheme objects are objects that are represented directly by a C_word. There's no additional memory used by them.

C_fix

[C macro] C_word C_fix (int integer)

C_make_character

[C macro] C_word C_make_character (int char_code)

C_mk_bool

[C macro] C_word C_mk_bool(int truth_value)

C_mk_nbool

[C macro] C_word C_mk_nbool(int truth_value_to_negate)

C_SCHEME_END_OF_LIST

[C macro] C_SCHEME_END_OF_LIST

C_SCHEME_END_OF_FILE

[C macro] C_SCHEME_END_OF_FILE

C_SCHEME_FALSE

[C macro] C_SCHEME_FALSE

C_SCHEME_TRUE

[C macro] C_SCHEME_TRUE

Constructors for non-immediate Scheme objects

Non-immediate Scheme objects are still represented and passed around by a single C_word, but this is basically just a pointer to the start of the object (which should never be treated as such, use the accessor macros instead).

Memory allocation

These can be used to allocate memory for non-immediate objects.

C_alloc

[C macro] C_word* C_alloc (int words)

Allocates memory from the C stack (C_alloc) and returns a pointer to it. words should be the number of words needed for all data objects that are to be created in this function. Note that stack-allocated data objects have to be passed to Scheme callback functions, or they will not be seen by the garbage collector. This is really only usable for callback procedure invocations, make sure not to use it in normal code, because the allocated memory will be re-used after the foreign procedure returns. When invoking Scheme callback procedures a minor garbage collection is performed, so data allocated with C_alloc will already have moved to a safe place.

Note that C_alloc is really just a wrapper around alloca, and can also be simulated by declaring a stack-allocated array of C_words:

C_SIZEOF_LIST

[C macro] int C_SIZEOF_LIST (int length)

C_SIZEOF_STRING

[C macro] int C_SIZEOF_STRING (int length)

C_SIZEOF_VECTOR

[C macro] int C_SIZEOF_VECTOR (int length)

C_SIZEOF_INTERNED_SYMBOL

[C macro] int C_SIZEOF_INTERNED_SYMBOL (int length)

C_SIZEOF_PAIR

[C macro] int C_SIZEOF_PAIR

C_SIZEOF_FLONUM

[C macro] int C_SIZEOF_FLONUM

C_SIZEOF_POINTER

[C macro] int C_SIZEOF_POINTER

C_SIZEOF_LOCATIVE

[C macro] int C_SIZEOF_LOCATIVE

C_SIZEOF_TAGGED_POINTER

[C macro] int C_SIZEOF_TAGGED_POINTER

These are macros that return the size in words needed for a data object of a given type.

Accessors

C_character_code

[C macro] int C_character_code (C_word character)

C_unfix

[C macro] int C_unfix (C_word fixnum)

C_flonum_magnitude

[C macro] double C_flonum_magnitude (C_word flonum)

C_c_string

[C function] char* C_c_string (C_word string)

C_num_to_int

[C function] int C_num_to_int (C_word fixnum_or_flonum)

C_pointer_address

[C function] void* C_pointer_address (C_word pointer)

These macros and functions can be used to convert Scheme data objects back to C data. Note that C_c_string() returns a pointer to the character buffer of the actual Scheme object and is not zero-terminated.

C_header_size

[C macro] int C_header_size (C_word x)

C_header_bits

[C macro] int C_header_bits (C_word x)

Return the number of elements and the type-bits of the non-immediate Scheme data object x.

C_block_item

[C macro] C_word C_block_item (C_word x, int index)

This macro can be used to access slots of the non-immediate Scheme data object x. index specifies the index of the slot to be fetched, starting at 0. Pairs have 2 slots, one for the car and one for the cdr. Vectors have one slot for each element.

C_u_i_car

[C macro] C_word C_u_i_car (C_word x)

C_u_i_cdr

[C macro] C_word C_u_i_cdr (C_word x)

Aliases for C_block_item(x, 0) and C_block_item(x, 1), respectively.

C_port_file

[C macro] C_word C_port_file (C_word x)

Alias for (FILE *)C_block_item(x, 0). To be used with port objects representing files (but will not work on sockets, for example).

C_data_pointer

[C macro] void* C_data_pointer (C_word x)

Returns a pointer to the data-section of a non-immediate Scheme object.

C_make_header

[C macro] C_word C_make_header (C_word bits, C_word size)

A macro to build a Scheme object header from its bits and size parts.

C_mutate

[C function] C_word C_mutate (C_word *slot, C_word val)

Assign the Scheme value val to the location specified by slot. If the value points to data inside the nursery (the first heap-generation), then the garbage collector will remember to handle the data appropriately. Assigning nursery-pointers directly will otherwise result in lost data. Note that no copying takes place at the moment when C_mutate is called, but later - at the next (minor) garbage collection.

C_symbol_value

[C macro] C_word C_symbol_value (C_word symbol)

Returns the global value of the variable with the name symbol. If the variable is unbound C_SCHEME_UNBOUND is returned. You can set a variable's value with C_mutate(&C_symbol_value(SYMBOL), VALUE).

GC interface

C_gc_protect

[C function] void C_gc_protect (C_word *ptrs[], int n)

Registers n variables at address ptrs to be garbage collection roots. The locations should not contain pointers to data allocated in the nursery, only immediate values or pointers to heap-data are valid. Any assignment of potential nursery data into a root-array should be done via C_mutate(). The variables have to be initialized to sensible values before the next garbage collection starts (when in doubt, set all locations in ptrs to C_SCHEME_UNDEFINED) C_gc_protect may not called before the runtime system has been initialized (either by CHICKEN_initialize, CHICKEN_run or CHICKEN_invoke.

For a slightly simpler interface to creating and using GC roots see CHICKEN_new_gc_root.

C_gc_unprotect

[C function] void C_gc_unprotect (int n)

Removes the last n registered variables from the set of root variables.

C_pre_gc_hook

[C Variable] void (*C_pre_gc_hook)(int mode)

If not NULL, the function pointed to by this variable will be called before each garbage collection with a flag indicating what kind of collection was performed (either 0 for a minor or major collection or 2 for a resizing collection). A "resizing" collection means a secondary collection that moves all live data into a enlarged (or shrinked) heap-space. Minor collections happen very frequently, so the hook function should not consume too much time. The hook function may not invoke Scheme callbacks.

Note that resizing collections may be nested in normal major collections.

C_post_gc_hook

[C Variable] void (*C_post_gc_hook)(int mode, long ms)

If not NULL, the function pointed to by this variable will be called after each garbage collection with a flag indicating what kind of collection was performed (either 0 for a minor collection, 1 for a major collection or 2 for a resizing collection). Minor collections happen very frequently, so the hook function should not consume too much time. The hook function may not invoke Scheme callbacks. The ms argument records the number of milliseconds required for the garbage collection, if the collection was a major one. For minor collections the value of the ms argument is undefined.

Type-specific macros and functions

The following are macros and functions to ask information or perform operations on objects once their types are already known. If you call it on any object of another type, it is not defined what will happen and likely your program will crash, especially if you pass immediates to procedures expecting non-immediates.

Vectors

C_vemptyp

[C macro] C_word C_vemptyp(C_word v)

Is the (byte- or heterogenous) vector v empty?

C_notvemptyp

[C macro] C_word C_notvemptyp(C_word v)

Is the (byte- or heterogenous) vector v nonempty?

Numbers

These procedures accept any type of number, so you can pass in either a fixnum or a flonum. You shouldn't pass in another type though, since that could crash your program.

C_u_i_exactp

[C macro] C_word C_u_i_exactp(C_word x)

Is x an exact number (i.e., a fixnum)?

C_u_i_inexactp

[C macro] C_word C_u_i_inexactp(C_word x)

Is x an inexact number (i.e., not a fixnum)?

C_i_finitep

[C function] C_word C_i_finitep(C_word x)

Is x a finite number? This returns false only when x is a flonum representing -inf or +inf.

Fixnums

Note: Fixnums are immediates, so there is no C_fixnum_equalp macro. You can just compare them without hassle (or use C_eqp if you prefer).

C_a_i_pointer_to_address

Convert back the pointer pptr to an address number, possibly using the storage at ptr. The number returned can be either a fixnum or a flonum, so you will have to pass a memory storage that can hold a flonum at ptr. Whether it is actually used depends on the size of the address.

Ports

C_tty_portp

[C macro] C_word C_tty_portp(C_word x)

Is x a TTY port object?

Structures

C_i_structurep

[C macro] C_word C_i_structurep(C_word x, C_word s)

Is x a structure (record) object with type tag s? This is completely safe to use, because it checks whether x is an immediate or not.

Characters

These understand only ASCII characters.

C_u_i_char_alphabeticp

[C macro] C_word C_u_i_char_alphabeticp(C_word c)

Is c an alphabetic character?

C_u_i_char_numericp

[C macro] C_word C_u_i_char_numericp(C_word c)

Is c a numeric character?

C_u_i_char_whitespacep

[C macro] C_word C_u_i_char_whitespacep(C_word c)

Is c a whitespace character?

C_u_i_char_upper_casep

[C macro] C_word C_u_i_char_upper_casep(C_word c)

Is c an uppercase character?

C_u_i_char_lower_casep

[C macro] C_word C_u_i_char_lower_casep(C_word c)

Is c a lowercase character?

Other Scheme procedures from C

There are a number of Scheme procedures that have a direct C implementation, so you can call them from C too.

Notes:

Scheme procedures can call C functions, and C functions can call Scheme procedures, but for every pending C stack frame, the available size of the first heap generation (the nursery) will be decreased, because the C stack is identical to the nursery. On systems with a small nursery this might result in thrashing, since the C code between the invocation of C from Scheme and the actual calling back to Scheme might build up several stack-frames or allocates large amounts of stack data. To prevent this it is advisable to increase the default nursery size, either when compiling the file (using the -nursery option) or when running the executable (using the -:s runtime option).

Calls to Scheme/C may be nested arbitrarily, and Scheme continuations can be invoked as usual, but keep in mind that C stack frames will not be recovered, when a Scheme procedure call from C does not return normally.

When multiple threads are running concurrently, and control switches from one thread to another, then the continuation of the current thread is captured and saved. Any pending C stack frame still active from a callback will remain on the stack until the threads is re-activated again. This means that in a multithreading situation, when C callbacks are involved, the available nursery space can be smaller than expected. So doing many nested Scheme->C->Scheme calls can reduce the available memory up to the point of thrashing. It is advisable to have only a single thread with pending C stack-frames at any given time.

Pointers to Scheme data objects should not be stored in local or global variables while calling back to Scheme. Any Scheme object not passed back to Scheme will be reclaimed or moved by the garbage collector.

Calls from C to Scheme are never tail-recursive.

Continuations captured via call-with-current-continuation and passed to C code can be invoked like any other Scheme procedure.