Non-Immediate Objects ​

A Scheme object of type SCM that does not fulfill the SCM_IMP predicate holds an encoded reference to a heap object. This reference can be decoded to a C pointer to a heap object using the SCM_UNPACK_POINTER macro. The encoding of a pointer to a heap object into a SCM value is done using the SCM_PACK_POINTER macro.

Before Guile 2.0, Guile had a custom garbage collector that allocated heap objects in units of 2-word cells. With the move to the BDW-GC collector in Guile 2.0, Guile can allocate heap objects of any size, and the concept of a cell is now obsolete. Still, we mention it here as the name still appears in various low-level interfaces.

Macro: scm_t_bits * SCM_UNPACK_POINTER (SCM x) ​

Macro: scm_t_cell * SCM2PTR (SCM x) ​

Extract and return the heap object pointer from a non-immediate SCM object x. The name SCM2PTR is deprecated but still common.

Macro: SCM_PACK_POINTER (scm_t_bits * x) ​

Macro: SCM PTR2SCM (scm_t_cell * x) ​

Return a SCM value that encodes a reference to the heap object pointer x. The name PTR2SCM is deprecated but still common.

Note that it is also possible to transform a non-immediate SCM value by using SCM_UNPACK into a scm_t_bits variable. However, the result of SCM_UNPACK may not be used as a pointer to a heap object: only SCM_UNPACK_POINTER is guaranteed to transform a SCM object into a valid pointer to a heap object. Also, it is not allowed to apply SCM_PACK_POINTER to anything that is not a valid pointer to a heap object.

Summary:

  • Only use SCM_UNPACK_POINTER on SCM values for which SCM_IMP is false!
  • Don’t use (scm_t_cell *) SCM_UNPACK (x)! Use SCM_UNPACK_POINTER (x) instead!
  • Don’t use SCM_PACK_POINTER for anything but a heap object pointer!