CR(VII) 1/4/75 CR(VII) NAME crfork, crexit, crread, crwrite, crexch, crprior - coroutine scheme SYNOPSIS int crfork( [ stack, nwords ] ) int stack; int nwords; crexit() int crread(connector, buffer, nbytes) int *connector; char *buffer; int nbytes; crwrite(connector, buffer, nbytes) int *connector; char *buffer; int nbytes; crexch(conn1, conn2, i) int *conn1, *conn2; int i; #define logical char * crprior(p) logical p; DESCRIPTION These functions are named by analogy to fork, exit, read, write (II). They establish and synchronize `coroutines', which behave in many respects like a set of processes working in the same address space. The functions live in /usr/lib/cr.a. Coroutines are placed on queues to indicate their state of readiness. One coroutine is always distinguished as `running'. Coroutines that are runnable but not running are registered on a `ready queue'. The head member of the ready queue is started whenever no other coroutine is specifically caused to be running. Each connector heads two queues: Connector is the queue of unsatisfied crreads outstanding on the connector. Connector is the queue of crwrites. All queues must start empty, i.e. with heads set to zero. Crfork is normally called with no arguments. It places the running coroutine at the head of the ready queue, creates a new coroutine, and starts the new one running. Crfork returns immediately in the new coroutine with value 0, and upon restarting of the old coroutine with value 1. Crexit stops the running coroutine and does not place it in any queue. Crread copies characters from the buffer of the crwrite at the head of the connector's write queue to the buffer of crread. If the write queue is empty, copying is delayed and the running coroutine is placed on the read queue. The number of characters copied is the minimum of nbytes and the number of characters remaining in the write buffer, and is returned as the value of crread. After copying, the location of the write buffer and the corresponding nbytes are updated appropriately. If zero characters remain, the coroutine of the crwrite is moved to the head of the ready queue. If the write queue remains nonempty, the head member of the read queue is moved to the head of the ready queue. Crwrite queues the running coroutine on the connector's write queue, and records the fact that nbytes (zero or more) characters in the string buffer are available to crreads. If the read queue is not empty, its head member is started running. Crexch exchanges the read queues of connectors conn1 and conn2 if i=0; and it exchanges the write queues if i=1. If a nonempty read queue that had been paired with an empty write queue becomes paired with a nonempty write queue, crexch moves the head member of that read queue to the head of the ready queue. Crprior sets a priority on the running coroutine to control the queuing of crreads and crwrites. When queued, the running coroutine will take its place before coroutines whose priorities exceed its own priority and after others. Priorities are compared as logical, i.e. unsigned, quantities. Initially each coroutine's priority is set as large as possible, so default queuing is FIFO. Storage allocation. The old and new coroutine share the same activation record in the function that invoked crfork, so only one may return from the invoking function, and then only when the other has completed execution in that func- tion. The activation record for each function execution is dynami- cally allocated rather than stacked; a factor of 3 in run- ning time overhead can result if function calls are very frequent. The overhead may be overcome by providing a sepa- rate stack for each coroutine and dispensing with dynamic allocation. The base (lowest) address and size of the new coroutine's stack are supplied to crfork as optional argu- ments stack and nwords. Stacked allocation and dynamic al- location cannot be mixed in one run. For stacked operation, obtain the coroutine functions from /usr/lib/scr.a instead of /usr/lib/cr.a. FILES /usr/lib/cr.a /usr/lib/scr.a DIAGNOSTICS `rsave doesn't work' - an old C compilation has called `rsave'. It must be recompiled to work with the coroutine scheme. BUGS Under /usr/lib/cr.a each function has just 12 words of anonymous stack for hard expressions and arguments of fur- ther calls, regardless of actual need. There is no checking for stack overflow. Under /usr/lib/scr.a stack overflow checking is not rigor- ous.