HEADER - layout of a co-routine header.

This describes the header that appears at the beginning of each stack segment associated with a co-routine. The header begins at offset zero within the segment (which is an offset of -16 from the co-routine pointer). Below we list the fields of the co-routine header, what they are used for, and their offsets from the start of the stack segment. All offsets are given in decimal.

00 C_NEXT
Pointer to next co-routine in co-routine list. To simplify debugging, all co-routine stack segments are kept in a doubly linked list.
01 C_LAST
Pointer to previous co-routine in co-routine list.
02 C_FUNC
Pointer to starting function in this co-routine.
03 C_FALL
Pointer to fall-off routine. The default fall-off routine will delete the co-routine.
04 C_PROT
The amount of frame space that should be protected for the first set of arguments. In a normal function call, the caller has used its FRAMESIZE parameter to ensure that there is enough space on the stack to hold the arguments that will be passed. Upon entering a co-routine for the first time, no such checking has been done. The C_PROT value tells how much space in the new stack should be protected to begin with. The S_RET of the bottom frame points one past this word.
05 C_NARG
Is used when calling C_FUNC. It has the form
zero  ARGWORDS,0

The value of ARGWORDS will be filled in by the function calling the new co-routine.

06 C_RETN
Calls an operator that will invoke the fall-off routine. It has the form
tra   .fall+S_BIAS,,P.OPER

The return address in the bottom frame points at this word. With the preceding C_NARG word, this forms a return point for the co-routine package driver function (which is a loop that alternately calls the C_FUNC and C_FALL functions).

07 C_CALL
Pointer to parent co-routine.
08 C_PASS
Pointer to co-routine that passed control to this co-routine.
09 C_FRAM
This is used to save the current value of the stack pointer (P.FRAM) when the co-routine is not active.
10 C_HIGH | C_SIZE
The C_SIZE value occupies the lower 18 bits of the word and gives the current size of the co-routine's stack segment. The C_HIGH value occupies the upper 18 bits of the word and gives the current high water mark of stack use in the segment.
11 C_SPAC | C_TYPE
The C_TYPE value occupies the lower 18 bits of the word and describes the type of the most recent transfer to this co-routine. The C_SPAC value occupies the upper 18 bits of the word and gives the size of the co-routine user area in words.
12 C_MEM
This is a second pointer to the co-routine segment memory, but it is expressed as a pointer within the parent heap segment. This is needed so that the memory can be returned to the memory pool when the co-routine is deleted.
13 C_GROW
This is the start of three words of space that are currently unused. In later releases, these may be used when growing the stack.
16 C_USER
The co-routine user area starts here. This is actually where the co-routine pointer points. Use of this area is entirely up to the user program.

A program that is tracing its way back through several stack frames can recognize the last frame in the list either because the pointer to the previous stack frame is null, or because the function return address points at the C_RETN word in the template call in the co-routine header.

Copyright © 1996, Bull HN and Thinkage Ltd.