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.