13.21 Pointer objects

A pointer is a fixed length memory block, two words wide, referenced by machine words tagged as vectors. The first machine word of a pointer block is tagged has pointer in its least significant bits and it has the most significant bits set to zero. The second machine word of a pointer block holds the actual pointer value.

|------------------------|-------------| reference to pointer
      heap pointer         vector tag

|------------------------|-------------| pointer first word
   all set to zero         pointer tag

|--------------------------------------| pointer second word
            pointer value

Basic operations

Pointers are allocated on the Scheme heap as follows:

ikpcb_t * pcb   = ik_the_pcb();
ikptr_t   s_ptr;

s_ptr = ik_safe_alloc(pcb, pointer_size) | vector_tag;
IK_POINTER_TAG(s_ptr) = pointer_tag;

To set or retrieve the pointer value we do:

ikptr_t  s_ptr = the_pointer;
void * ptr;

ptr = IK_POINTER_DATA_VOIDP(X);
IK_POINTER_DATA_VOIDP(X) = ptr;

Preprocessor Symbol: pointer_size

The number of bytes to allocate to hold a pointer memory block.

Preprocessor Symbol: pointer_tag

The tag of ikptr_t values used as first words in pointer memory blocks.

Preprocessor Symbol: disp_pointer_tag

Displacement of secondary tag word. The number of bytes to add to an untagged pointer to pointer object to get the pointer to the first byte in the word holding the pointer tag.

Preprocessor Symbol: disp_pointer_data

Displacement of data area. The number of bytes to add to an untagged pointer to pointer object to get the pointer to the first byte of the data area.

Preprocessor Symbol: off_pointer_tag

An integer to add to add to a tagged ikptr_t pointer to pointer object to get the pointer to the first byte in the word holding the pointer tag.

Preprocessor Symbol: off_pointer_data

An integer to add to a tagged ikptr_t pointer to pointer object to get the pointer to the first byte of the word holding the pointer value.

Convenience preprocessor macros

Preprocessor Macro: int IK_IS_POINTER (ikptr_t X)

Evaluate to true if X is a pointer object.

Preprocessor Macro: ikptr_t IK_POINTER_TAG (ikptr_t X)

Evaluate to the location of the first word in a pointer object; X must be a tagged pointer referencing a pointer object.

Preprocessor Macro: ikptr_t IK_POINTER_DATA (ikptr_t X)

Return the value of the pointer as ikptr_t; X must be a tagged pointer referencing a pointer object.

Preprocessor Macro: void * IK_POINTER_DATA_VOIDP (ikptr_t X)

Preprocessor Macro: char * IK_POINTER_DATA_CHARP (ikptr_t X)

Preprocessor Macro: uint8_t * IK_POINTER_DATA_UINT8P (ikptr_t X)

Preprocessor Macro: long * IK_POINTER_DATA_LONG (ikptr_t X)

Preprocessor Macro: ik_llong * IK_POINTER_DATA_LLONG (ikptr_t X)

Preprocessor Macro: ik_ulong * IK_POINTER_DATA_ULONG (ikptr_t X)

Preprocessor Macro: ik_ullong * IK_POINTER_DATA_ULLONG (ikptr_t X)

Return the value of the pointer cast to a specific type; X must be a tagged pointer referencing a pointer object.

Preprocessor Macro: ikptr_t IK_POINTER_SET (ikptr_t X, void * ptr)

Reset to ptr the value of the pointer X; X must be a tagged pointer referencing a pointer object.

Preprocessor Macro: ikptr_t IK_POINTER_SET_NULL (ikptr_t X)

Reset to NULL the value of the pointer; X must be a tagged pointer referencing a pointer object.

Preprocessor Macro: int IK_POINTER_IS_NULL (ikptr_t X)

Evaluate to true if the pointer value is NULL; X must be a tagged pointer referencing a pointer object.

Operations on pointers

Function: int ik_is_pointer (ikptr_t X)

Return true if X is a pointer object.

Function: ikptr_t ikrt_is_pointer (ikptr_t X)

Return IK_TRUE_OBJECT if X is a pointer object, else return IK_FALSE_OBJECT.

Function: ikptr_t ika_pointer_alloc (ikpcb_t * pcb, ikuword_t memory)

Allocate a pointer object using ik_safe_alloc() and return a tagged reference to it. The pointer is initialised to memory.

Function: ikptr_t iku_pointer_alloc (ikpcb_t* pcb, ikuword_t memory)

Allocate a pointer object using ik_unsafe_alloc() and return a tagged reference to it. The pointer is initialised to memory.