9.2.5.4 Allocating Heap Objects

Heap objects are heap-allocated data pointed to by non-immediate SCM value. The first word of the heap object should contain a type code. The object may be any number of words in length, and is generally scanned by the garbage collector for additional unless the object was allocated using a “pointerless” allocation function.

You should generally not need these functions, unless you are implementing a new data type, and thoroughly understand the code in <libguile/scm.h>.

If you just want to allocate pairs, use scm_cons.

Function: SCM scm_words (scm_t_bits word_0, uint32_t n_words)

Allocate a new heap object containing n_words, and initialize the first slot to word_0, and return a non-immediate SCM value encoding a pointer to the object. Typically word_0 will contain the type tag.

There are also deprecated but common variants of scm_words that use the term “cell” to indicate 2-word objects.

Function: SCM scm_cell (scm_t_bits word_0, scm_t_bits word_1)

Allocate a new 2-word heap object, initialize the two slots with word_0 and word_1, and return it. Just like calling scm_words (word_0, 2), then initializing the second slot to word_1.

Note that word_0 and word_1 are of type scm_t_bits. If you want to pass a SCM object, you need to use SCM_UNPACK.

Function: SCM scm_double_cell (scm_t_bits word_0, scm_t_bits word_1, scm_t_bits word_2, scm_t_bits word_3)

Like scm_cell, but allocates a 4-word heap object.