13.25.1 Introduction to continuations

Continuation objects are memory blocks referenced by machine words tagged as vectors, whose first word is tagged as continuation:

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

|----------------|----------| first word of continuation
 all set to zero  continuation tag

the layout of a continuation memory block is:

|-----|-----|-----|-----|
  tag   top  size  next

Continuation objects are collected in linked lists handled as stacks; all such linked lists share a common tail. The meaning of the fields is:

tag

A machine word containing only the secondary tag for continuation objects and all the other bits set to zero.

top

A machine word representing the memory address of the machine word at the top (lowest address) of the stack portion referenced by the continuation.

size

The size of the stack portion expressed in number of bytes.

next

A machine word being NULL or a reference (tagged pointer) to the next continuation object in the linked list.

Basic operations

To test if a value of type ikptr_t is a reference to a continuation object, we should do:

ikptr_t   X;

if (continuation_primary_tag == (continuation_primary_mask & X))
  {
    if (continuation_tag == IK_REF(X, 0))
      it_is_a_scheme_continuation();
    else if (system_continuation_tag == IK_REF(X, 0))
      it_is_a_system_continuation();
    it_is_not();
  }
else
  it_is_not();

A Scheme continuation object is usually allocated as follows:

ikpcb_t *  pcb = ...;
ikptr_t    s_kont;
ikcont *   kont;

kont   = (ikcont*)ik_unsafe_alloc(pcb,
                     IK_ALIGN(continuation_size));
s_rest = (ikptr_t)((long)kont) | continuation_primary_tag;

IK_REF(s_kont, off_continuation_tag)  = continuation_tag;
IK_REF(s_kont, off_continuation_top)  = pcb->frame_pointer;
IK_REF(s_kont, off_continuation_size) = \
   pcb->frame_base - pcb->frame_pointer - wordsize;
IK_REF(s_kont, off_continuation_next) = pcb->next_k;
IK_SIGNAL_DIRT(pcb, s_kont);
pcb->next_k = s_kont;

Preprocessor Symbol: continuation_primary_tag

The tag of an ikptr_t machine words referencing the memory block of a Scheme or system continuation object.

Preprocessor Symbol: continuation_primary_mask

A bit pattern used to isolate the tag bits in an ikptr_t machine words referencing the memory block of a Scheme or system continuation object.

Preprocessor Symbol: continuation_tag

Preprocessor Symbol: system_continuation_tag

Integer values used to tag and recognise the first word in continuation memory blocks.

Preprocessor Symbol: continuation_size

Preprocessor Symbol: system_continuation_size

The number of bytes needed to hold a continuation memory block.

Preprocessor Symbol: disp_continuation_tag

Preprocessor Symbol: disp_continuation_top

Preprocessor Symbol: disp_continuation_size

Preprocessor Symbol: disp_continuation_next

Scheme continuation field displacements. The number of bytes to add to an untagged pointer to Scheme continuation to get the pointer to the first byte in the word holding the specified field.

Preprocessor Symbol: disp_system_continuation_tag

Preprocessor Symbol: disp_system_continuation_top

Preprocessor Symbol: disp_system_continuation_size

Preprocessor Symbol: disp_system_continuation_next

System continuation field displacements. The number of bytes to add to an untagged pointer to system continuation to get the pointer to the first byte in the word holding the specified field.

Preprocessor Symbol: off_continuation_tag

Preprocessor Symbol: off_continuation_top

Preprocessor Symbol: off_continuation_size

Preprocessor Symbol: off_continuation_next

Scheme continuation field offsets. The number of bytes to add to a tagged pointer to Scheme continuation to get the pointer to the first byte in the word holding the specified field.

Preprocessor Symbol: off_system_continuation_tag

Preprocessor Symbol: off_system_continuation_top

Preprocessor Symbol: off_system_continuation_size

Preprocessor Symbol: off_system_continuation_next

System continuation field offsets. The number of bytes to add to a tagged pointer to system continuation to get the pointer to the first byte in the word holding the specified field.

Preprocessor Macro: int IK_IS_CONTINUATION (X)

Evaluate to true if X is a reference to Scheme continuation object.

Preprocessor Macro: int IK_IS_SYSTEM_CONTINUATION (X)

Evaluate to true if X is a reference to system continuation object.

Preprocessor Macro: int IK_IS_ANY_CONTINUATION (X)

Evaluate to true if X is a reference to Scheme or system continuation object.