Next: , Previous: objects transcoders, Up: objects

12.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 * pcb   = ik_the_pcb();
     ikptr   s_ptr;
     
     s_ptr = ik_safe_alloc(pcb, pointer_size) | vector_tag;
     IK_REF(s_ptr, off_pointer_tag) = pointer_tag;

to identify an object as pointer we do: 

     ikptr  X = the_object;
     
     if ((vector_tag  == IK_TAGOF(X)) &&
         (pointer_tag == IK_REF(X, -vector_tag)))
       it_is_a_pointer();
     else
       it_is_not();

to set or retrieve the pointer value we do: 

     ikptr  s_ptr = the_pointer;
     void * ptr;
     
     ptr = (void *)IK_REF((X), off_pointer_data);
     IK_REF((X), off_pointer_data) = (ikptr)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 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 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 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 X)

Evaluate to true if X is a pointer object.

— Preprocessor Macro: ikptr IK_POINTER_DATA (ikptr X)

Return the value of the pointer as ikptr.

— Preprocessor Macro: void * IK_POINTER_DATA_VOIDP (ikptr X)
— Preprocessor Macro: char * IK_POINTER_DATA_CHARP (ikptr X)
— Preprocessor Macro: uint8_t * IK_POINTER_DATA_UINT8P (ikptr X)
— Preprocessor Macro: long * IK_POINTER_DATA_LONG (ikptr X)
— Preprocessor Macro: ik_llong * IK_POINTER_DATA_LLONG (ikptr X)
— Preprocessor Macro: ik_ulong * IK_POINTER_DATA_ULONG (ikptr X)
— Preprocessor Macro: ik_ullong * IK_POINTER_DATA_ULLONG (ikptr X)

Return the value of the pointer cast to a specific type.

— Preprocessor Macro: ikptr IK_POINTER_SET (ikptr X, void * ptr)

Reset to ptr the value of the pointer X.

— Preprocessor Macro: ikptr IK_POINTER_SET_NULL (ikptr X)

Reset to NULL the value of the pointer.

— Preprocessor Macro: int IK_POINTER_IS_NULL (ikptr X)

Evaluate to true if the pointer value is NULL.

Operations on pointers
— Function: ikptr ika_pointer_alloc (ikpcb * pcb, ik_ulong memory)

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

— Function: ikptr iku_pointer_alloc (ikpcb* pcb, ik_ulong memory)

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

— Function: int ik_is_pointer (ikptr X)

Return true if X is a pointer object.

— Function: ikptr ikrt_is_pointer (ikptr X)

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