The Coroutine Library

2

Introduction

A coroutine program is made up of routines that run in parallel with other routines instead of carrying out their actions and terminating like ordinary functions. These special routines, called coroutines or tasks, can communicate with one another and can give rise to other coroutines. The coroutine library provides a set of classes that enable you to write programs in this style.

Tasks do not actually execute concurrently. A single task continues to execute until it suspends or terminates itself; usually, another task then resumes execution. You can use the coroutine library to simulate concurrent execution, and use simulated time to make the execution of the coroutines actually appear parallel.

Note - If your application is compiled with -O4 or O5, you will not be able to use the coroutine library. You must use an -O3 or lower level of optimization in order to use the coroutine library.

Note - As of the time of this printing, the coroutine library will not be supported beyond the current version.

Using the Coroutine Library

To use the task library, include the header file task.h in your program, and link with the -ltask option.

Structure of the Coroutine Classes

The coroutine library provides basic types. These types are described in Table 2-1.

Table 2-1 Basic Types in a Coroutine Library
Type	Description
Task	A coroutine is created as an instance of any class immediately derived from class `task`. The body of the coroutine is the constructor of the derived class.
Queue	A data structure that makes ordered collections of objects. Classes `qhead`, `qtail.`
Timer	A class that implements time-outs and other time-dependent functions. Class `timer.`
Histogram	A data structure provided to help gather data.
Interrupt handler	A class that represents external events. Class `Interrupt_handler`.

In addition, two important base classes are described in Table 2-2.

Table 2-2 Two Base Classes in a Coroutine Library

Base Class
Definition

Class object

Provides the root of class hierarchy.

Class sched

Provides the basic definition for an object that knows about time. Used as a base class for classes timer and task, and implements task scheduling.

Table 2-2 Two Base Classes in a Coroutine Library
Base Class	Definition
Class `object`	Provides the root of class hierarchy.
Class `sched`	Provides the basic definition for an object that knows about time. Used as a base class for classes `timer` and `task`, and implements task scheduling.

Objects

The coroutine library defines class object as a base class for other classes in the library. For example, messages passed between tasks are instances of classes derived from class object. You can derive your own special-purpose classes from class object.

The public members of interest in class object are described in Table 2-3:

Table 2-3 Public Members of Classobject

Class member
Description

enum objtype

OBJECT, TIMER, TASK, QHEAD, QTAIL, INTHANDLER

objtype o_type();

(virtual) Returns the type of the current object.

int pending();

(virtual) Returns non-zero (true) if not ready.

void print(int how, int =0);

(virtual) Primarily for debugging. Prints out all state information for a task and its base classes. Parameter how takes any combination of CHAIN (data on all tasks in chain) and VERBOSE (extra information) bits. The second parameter affects indentation of printed information and is for internal use.

void alert();

Makes remembered tasks eligible for execution.

void forget(task*);

Forgets a previously remembered task.

void remember(task*);

Remembers a task for alert.

static task* this_task();

Returns the currently running task.

Table 2-3 Public Members of Class`object`
Class member	Description
`enum objtype`	`OBJECT`, `TIMER`, `TASK`, `QHEAD`, `QTAIL`, `INTHANDLER`
`objtype o_type();`	(virtual) Returns the type of the current object.
`int pending();`	(virtual) Returns non-zero (true) if not ready.
`void print(int how, int =0);`	(virtual) Primarily for debugging. Prints out all state information for a task and its base classes. Parameter `how` takes any combination of `CHAIN` (data on all tasks in chain) and `VERBOSE` (extra information) bits. The second parameter affects indentation of printed information and is for internal use.
`void alert();`	Makes remembered tasks eligible for execution.
`void forget(task*);`	Forgets a previously remembered task.
`void remember(task*);`	Remembers a task for `alert`.
`static task* this_task();`	Returns the currently running task.

Tasks

Tasks are the basic features of coroutine-style programming. A task runs until it explicitly allows another task to run. When one task suspends or terminates itself, the task system chooses the next task on the list of ready-to-run tasks and runs it.

A task can give up control of the processor by suspending or terminating itself, but nothing can force it to do so. The currently active task is always in control. No task can preempt another task.

When a task suspends, the task system saves the state of the task so the task can get its environment back when it resumes. This behavior generally means saving the stack and hardware registers. The task system then restores the environment of another task and that task resumes execution.

A task system is like the operating system: each task is a process that carries on its individual action and communicates with other processes. There are important differences, however:

A task system is a single operating system process. The task system relies on the operating system for I/O, memory management, and other functions that every real operating system must perform.
Every task in a task system shares the same address space. Processes under the operating system have their own address spaces. Sharing address space has an advantage in that tasks can share information simply by passing pointers, but a disadvantage in that a badly behaved task can interfere with other tasks.
A task system can support hundreds or thousands of times as many concurrent tasks as an operating system can support processes. Simulations written with the task library often have thousands of tasks.

Figure 2-1 shows the organization of the classes in the coroutine library.

Figure 2-1 Coroutine Library Structure.

Class `task`

A task is an object of a class derived from class task. The action of a task is contained in the constructor of the task's class. Before returning, the constructor of a task terminates it by a call to resultis. A task is always in one of three states, as shown in Table 2-4.

Table 2-4 Class `task` States
State	Definition
`RUNNING`	Executing instructions or on scheduler's ready-to-run list.
`IDLE`	Waiting for something to happen before returning to running state (suspended).
`TERMINATED`	Completely finished running. Cannot return to a running or idle state. Another task can still access its result if it has not been destroyed.

This example shows a portion of the public interface of class task. Part of it is inherited from class sched:

class task : public sched {

public:

enum modetype { DEDICATED, SHARED };

protected:

task(char* =0, modetype =DEFAULT_MODE, int =SIZE);

public:

~task();

task* t_next;

unsigned char* t_name;

void wait(object*);

int waitlist(object*...);

int waitvec(object**);

void delay(int);

int preempt();

void sleep(object* =0);

void resultis(int);

void cancel(int);

void print(int, int =0);

// Flags for first parameter of print
#define CHAIN ...

#define VERBOSE ...

//These are inherited from class sched

enum statetype {IDLE, RUNNING, TERMINATED };

statetype rdstate();

long rdtime();

int result();

};

class task : public sched { public: enum modetype { DEDICATED, SHARED }; protected: task(char* =0, modetype =DEFAULT_MODE, int =SIZE); public: ~task(); task* t_next; unsigned char* t_name; void wait(object); int waitlist(object...); int waitvec(object*); void delay(int); int preempt(); void sleep(object =0); void resultis(int); void cancel(int); void print(int, int =0); // Flags for first parameter of print #define CHAIN ... #define VERBOSE ... //These are inherited from class sched enum statetype {IDLE, RUNNING, TERMINATED }; statetype rdstate(); long rdtime(); int result(); };

Parts of a Task

Table 2-5 describes the public part of class task:

Table 2-5 Public Parts of Class `task`
Class `task` Public Part	Description
`enum modetype`	The task stack may be `DEDICATED` or `SHARED`. The default mode is dedicated (see coroutine library man pages).
`task(char* name=0, mode typemode=DEDICATED, int stacksize=3000)`	Constructor for class `task`. Protected to prevent creation of objects type `task`. You must derive your own class from `task`.
`~task()`	Destructor for class `task`. Takes care of cleanup.
`task* t_next`	Points to the next task in the task list.
`unsigned char* t_name`	Optional name of a task. You can give each task object a name, which is printed as a debugging aid.
`wait(), waitlist(), waitvec(), delay(), preempt(), sleep()`	Functions that deal with suspending a task (see "Waiting States for Tasks" on page 19).
`void resultis(int)`	Sets the return value of task and terminates it. Use this function instead of `return` from a task. (You cannot use `return`.) `resultis` also invokes the task scheduling mechanism.
`void cancel(int)`	Like `resultis`, sets return value of task and terminates it. Does not invoke task scheduling, so is a useful way to terminate another task without interrupting the current task.
`enum statetype`	The states that a task may be in: `IDLE`, `RUNNING`, `TERMINATED`.
`statetype rdstate()`	Returns the state of a task.
`long rdtime()`	Returns the current time. A simulated time is kept, which provides the illusion of passing time and simultaneous task execution.
`int result()`	Returns the result value of another task. That value is provided by `resultis` or `cancel`. A task cannot call `result` for itself. If the queried task has not terminated, calling task is suspended until queried task terminates and thus has a result to return.

A Simple Task Example

A simple example of a task is one where the function main creates two tasks, one of which needs to get information from the other. Appendix A, "Coroutine Examples" shows this example.

In the following example, one task gets a string from the user while the second counts the number of '0' characters in the string.

The task classes are getLine and countZero.

Code Example 2-1 Classes

class getLine : public task {

public:

getLine();

};

class countZero : public task {

public:

countZero(getLine*);

};

The implementation of the constructor for getLine is simple. Code Example 2-2 assumes type int and char* are the same size and can be freely cast back and forth. This may not be the case with other C++ implementations:

Code Example 2-2 getline Constructor

getLine::getLine()

{

char* tmpbuf = new char[512];

cout << "Enter string: ";

cin >> tmpbuf;

resultis((int)tmpbuf);

}

Code Example 2-3 shows the constructor for countZero.

Code Example 2-3 countZero Constructor

countZero::countZero(getLine *g)

{

char *s, c;

int i = 0;

s = (char*)g->result();

while( c = *s++)

if( c == '0' )

i++;

resultis(i);

}

The main program looks like this:

Code Example 2-4 Zero-char Counter Main Program

// Simple zero-char counter program

int main()

{

getLine g;

countZero c(&g);

cout << "Count result = "

<< c.result() << "\n";

thistask->resultis(0);

return 0;

}


// within someTask() secondClass secondObject(); int i = secondObject.result();

If secondObject has not terminated when someTask calls member function result, someTask is suspended (becomes IDLE) until secondObject does terminate. At that point, someTask resumes (becomes RUNNING) with the result from secondObject available.

Suspending when Dealing with Queues

When you try to get a message from an empty queue (see "FIFO Queues" on page 25) or try to put a message in a full queue, the queue function suspends your task if the mode of the queue is WMODE. When the condition passes, your task becomes RUNNING again.

Putting Your Task to Sleep

You can put a task to sleep until a pending task is no longer pending. If the task you want to wait for is not a pending task and you use sleep, the calling task suspends itself indefinitely. If you want to wait for a task that may be nonpending, and have your task continue execution, use wait. You can put a task to sleep by calling:


void sleep(object* t = 0);

The calling task goes to sleep until the object pointed to by the parameter is no longer pending. If the task is not pending when you execute this call, the calling task goes to sleep indefinitely. If you give a null pointer--as in sleep(0)--your task goes to sleep indefinitely.

Waiting for an Object

You can make a task can wait for another task to become ready (nonpending) by using the wait task member function. Make a task wait by calling:


void wait(object* ob);

The calling task waits until the object pointed to by the parameter is no longer pending. If the task is not pending when you execute this call, or the object pointer is null, the calling task is not suspended.

Waiting for a List of Tasks

Tasks have two member functions that make them wait for any one of a list of pending objects to become no longer pending. The two functions are:


int waitlist(object, ...); int waitvec(object*);

You give waitlist a null-terminated list of objects to wait for. These objects can be queues, tasks, or other objects as shown in the following example,

qhead* firstQ;

qtail* secondQ;

taskType* aTask;

. . .

int which = waitlist(firstQ, secondQ, aTask, (object*)0);

qhead* firstQ; qtail* secondQ; taskType* aTask; . . . int which = waitlist(firstQ, secondQ, aTask, (object*)0);

If all of the items are pending, the calling task is suspended (becomes IDLE). When any one of the items in the list becomes ready (no longer pending), waitlist returns and the calling task resumes its RUNNING state. If one of the items is ready when it is called, waitlist returns immediately. The return value of waitlist is the position in the list of a ready task, counting from 0. There may be more than one ready task, in which case one is arbitrarily identified as the task that caused waitlist to return.

waitvec works exactly like waitlist, except that it takes a null-terminated vector (array) of objects. The following example is equivalent to the example using waitlist:

object* vec[] = {firstQ, secondQ, aTask, 0};

int which = waitvec(vec);

object* vec[] = {firstQ, secondQ, aTask, 0}; int which = waitvec(vec);

Waiting for a Predetermined Time

You can set a specific timed delay. With this kind of delay, the task remains in a RUNNING state, thus simulating the passage of time. (See "System Time" on page 22.) For example:


// ... do something delay(6); // wait // ... do s ome more

In this example, after the call to delay has returned, six units of simulated time will have passed. Other tasks may or may not have run in the meantime, depending on their own scheduling requests.

System Time

The task system maintains a simulated time, which need not be (and usually is not) related to real time. The static member function sched::get_clock returns the current simulated time, which is by default initialized to zero. The static member function sched::setclock can be used to initialize the system clock to a starting time, but cannot be called once the time has advanced.

Function task::delay is the only way for a task to cause the system time to advance. The current task is set to run again when the specified number of time units have passed. The scheduler checks the scheduled runtime for the next task on the task list and advances the system time to that value. Eventually, the task requesting the delay reaches the front of the task list, and simulated time will have advanced by the requested amount.

A task can also create a timer, an object which exists for a predetermined amount of simulated time and which can be waited on, as described in the next section.

Timers

A timer behaves like a mini-task whose only function is to execute a delay; it has no result. Like any object, it can be waited on. One difference from a task is that a timer can be reset; it does not have to be destroyed first and reconstructed. Table 2-6 describes the public parts of class timer:

Table 2-6 Public Parts of Class `timer`
Public Part of Class `timer`	Description
`timer(int delay)`	Constructor for a timer of specified lifetime.
`~timer()`	Destructor that takes care of cleanup.
`void reset(int delay)`	Sets a new delay value for a `timer`, so that it can be reused.

One use for a timer is for implementing a time-out. Suppose you want to wait for some task, get_input, but for not more than five time units. You can use a timer like this:

Code Example 2-5 Using the timer Class

input_task *get_input = new input_task(...);

timer timeout(5); // expires in 5 units

switch( waitlist(get_input, &timeout, 0) ) {

case 0: // input completed

timeout.reset(0); // cancel the timer

... // do something with input

break;

case 1: // timer expired

... // do something without input

break;

default: // impossible!

...

}

// timer can be reset and used again if desired

Queues

In "A Simple Task Example" on page 17, the two tasks act like ordinary functions: the first one completes its action before the second one begins execution. This is because information is passed using the resultis and result functions; the information is not passed until the task has terminated.

A more concurrent way to write these tasks is to give them a different way of passing information and let each routine loop indefinitely. For example, you could write countZero as shown in this example:

countZero::countZero(qhead *lineQ, qtail *countQ)

{

char c;

lineHolder *inmessage;

while( 1 ) {

inmessage = (lineHolder*)lineQ->get();

char *s = inmessage->line;

int i = 0;

while( c = *s++ )

if( c == '0' )

i++;

numZero *num = new numZero(i);

countQ->put(num);

}

resultis(1); // never gets here

}

countZero::countZero(qhead lineQ, qtail countQ)
{
char c;
lineHolder *inmessage;
while( 1 ) {
inmessage = (lineHolder*)lineQ->get();
char *s = inmessage->line;
int i = 0;
while( c = *s++ )
if( c == '0' )
i++;
numZero *num = new numZero(i);
countQ->put(num);
}
resultis(1); // never gets here
}

Appendix A, "Coroutine Examples", Code Example A-2 gives the full text of a program written this way.

Queues provide such intertask communication. A queue is a data structure made up of a series of linked objects. Queues can hold only descendants of type object. You may use a queue as a first-in, first-out (FIFO) queue, or as a first-in, last-out queue (stack), by appropriate selection of access functions.

FIFO Queues

A FIFO queue is made of two objects: a qhead and a qtail. You create a queue by creating a qhead object for it. You then create a tail by calling the member function of qhead:


qtail* qhead::tail();

You can place objects on the queue with the member function of qtail. The return value is 1 if the action is successful:

int qtail::put(object*)

int qtail::put(object*)

then take objects from the queue with the member function of qhead:

object* qhead::get()

You can also put an object back at the head of the queue with a qhead member function. Thus you treat a queue head like a stack:

int qhead::putback(object*)

A problem with the putback function is that if you try to use it on a full queue, you produce a runtime error in queue mode WMODE as well as EMODE. See "Queue Modes" on page 28 for an explanation of these modes.

To expand the task sample program so it uses queues, you must first create classes for objects that hold the information you want to pass.

Code Example 2-6 Zero-counter Program Using FIFO Queue

FIFO.h

#include <task.h>

#include <iostream.h>

class getLine : public task {

public:

getLine(qhead*, qtail*);

};

class countZero : public task {

public:

countZero(qhead*, qtail*);

};

class lineHolder : public object {

public:

char *line;

lineHolder(char* s) : line(s) { }

};

class numZero : public object {

public:

int zero;

numZero(int count) : zero(count) { }

};

Now, you can rewrite the main function as shown below:

Code Example 2-7 Zero-counter Main Program

main.cc

// Zero-counter program using queues

#include <task.h>

#include "FIFO.h"

#include "countZero.h"

#include "getLine.h"

int main()

{

qhead *stringQhead = new qhead;

qtail *stringQtail = stringQhead->tail();

qhead *countQhead = new qhead;

qtail *countQtail = countQhead->tail();

countZero counter(stringQhead, countQtail);

getLine g(countQhead, stringQtail);

thistask->resultis(0);

return 0;

}

Code Example 2-8 is the implementation for countZero:

Code Example 2-8 countZero Constructor

countZero.h

countZero::countZero(qhead *lineQ, qtail *countQ)

{

char c;

lineHolder *inmessage;

while( 1 ) {

inmessage = (lineHolder*)lineQ->get();

char *s = inmessage->line;

int i = 0;

while( c = *s++ )

if( c == '0' )

i++;

numZero *num = new numZero(i);

countQ->put(num);

}

resultis(1); // never gets here

}

In this version, countZero is created first in the main program, after establishing queues for communication. When countZero tries to get a message from the queue there is none. countZero suspends, because this is the default waiting-type queue. At that point, the main program creates the line getter. Code Example 2-9 is the implementation of getline:

Code Example 2-9 getLine Constructor

getLine.h

getLine::getLine(qhead* countQ, qtail* lineQ)

{

numZero *qdata;

while( 1 ) {

cout << "Enter a string, ^C to end session: ";

char tmpbuf[512];

cin >> tmpbuf;

lineQ->put(new lineHolder(tmpbuf));

qdata = (numZero*) countQ->get();

cout << "Count of zeroes = " << qdata->zero << "\n";

};

resultis(1); // never gets here

}

When this routine begins execution, it first gets a line from standard input, places that on the line queue, and then asks the count queue for the count. That action makes it suspend itself until the zero counter places its message on the queue.

As a real program, this example has a number of glaring problems. For one thing, there is no clear way to terminate it; it will loop indefinitely. For another, it continually creates objects without destroying them as it loops. Those details were left out for simplicity.

Queue Modes

Three queue modes govern what happens when a task asks for a message from an empty queue or tries to put a message into a full queue:

: 1. WMODE--The calling task is suspended until condition of queue changes (default).
: 2. ZMODE--The queue returns a null pointer.
: 3. EMODE--A run-time error is produced.

Each qhead and qtail has its own mode; the head and tail for a queue can have different modes.

You can find out the current mode using the head and tail member function:

qmodetype rdmode();

and set the mode using the head and tail member function:

void setmode(qmodetype m);

Queue Size

By default, a queue is limited to 10,000 objects, although space for that number of objects is not actually allocated. Table 2-7 describes queue functions related to queue size.

Table 2-7 Queue Functions
Function	Description
`int rdmax()`	Maximum number of objects allowed in queue.
`void setmax(int)`	Sets new maximum number of objects allowed. You can set the maximum to a number less than the number currently in the queue. In that case, the queue is considered full until the number falls to the new maximum.
`int rdcount()`	Number of objects in queue.
`int rdspace()`	Number of additional objects which can be inserted in queue.

Cutting and Splicing

Since a queue is made up of a separate head and tail, you can cut and splice queues. The main use for this feature is to insert a filter, a special task which outputs a transformed version of its input. By cutting an existing queue and splicing in a filter, you can perform transformations without changing or affecting any existing code using the original queue.

Suppose you have a Generator task which creates lines of text, perhaps prose, poetry, or computer program source text. You also have a Printer task which displays this text on some device. The two tasks communicate by means of a FIFO queue called Buffer. Generator just writes text into the Buffer queue, one line at a time, until it is done. Printer just picks up lines from Buffer and displays them. You would like to do some formatting on the lines, such as justifying, indenting, splitting and merging lines. By cutting Buffer in two and splicing in a filter task called Format you can do this without modifying or even recompiling the Generator or Printer tasks.

First look at Code Example 2-10, where the Generator and Printer communicate via the buffer:

Code Example 2-10 Buffer Class

#include <task.h>

class Generator : public task {

public:

Generator(qtail *target);

...

};

class Printer : public task {

public:

Printer(qhead *source);

...

};

int main() {

...

// buffer up to 100 lines, using Wait mode

qhead *Buffer = new qhead(WMODE, 100);

// generator writes to the tail of the buffer

Generator *gen = new Generator(Buffer->qtail());

// printer reads from the head of the buffer

Printer *prt = new Printer(Buffer);

...

};

You can now cut the Buffer queue, and insert our filter between the head and the tail. You need a declaration for the filter Format, and you splice it into the cut Buffer queue:

Code Example 2-11 Cutting and Splicing a Queue

#include <task.h>

class Format : public task {

public:

Format(qhead *source, qtail *target);

...

};

Format::Format(qhead *source, qtail *target)

{

...

};

int main ()

{

qhead *Buffer = new qhead(WMODE, 100);

...

// insert formatter into Buffer

qhead *formhead = Buffer->cut();

qtail *formtail = Buffer->tail();

Format form(formhead, formtail);

...

// finished with formatting, restore original Buffer

formhead->splice(formtail);

return 1;

}

You can do this cutting and splicing anytime, inserting and removing filters as needed. As explained in the manual page queue(3C++), Generator continues to write to the same qtail as before, but there is a new qhead associated with it, formhead. Similarly, Printer continues to extract from the same qhead as before, but it is attached to a new qtail, formtail. The formatter, form, reads from the old qhead, and writes to the qtail of the queue that Printer reads.

When you have finished with this filter, you can use the splice function to restore the original queue. splice deletes the extra qhead and qtail which are created by cut.

Scheduling

Scheduling is a cooperative effort among all tasks. Although you don't work directly with scheduling, you may need to know what it can and cannot do. Scheduling does the following:

Maintains the run chain. The run chain is the list of tasks having state RUNNING and therefore ready to run. This is the main activity of scheduling.
Maintains the simulated time. The time is set to the scheduled time of the next task which is run.
Executes between tasks. It consists of what must be done after a task has given up execution and before the next task on the run chain continues execution.
When a task changes its state from IDLE to RUNNING, scheduling adds it to the run chain.
When a task gives up execution but does not change its state (still has the state RUNNING), scheduling puts it on the run chain according to the next simulated time it is scheduled to run. Tasks run in a round-robin fashion.
If the run chain is empty but there are active interrupt handlers (see "Real-Time and Interrupts" on page 35), the entire task system becomes dormant until an interrupt occurs.
If the run chain is empty and there are no interrupt handlers, scheduling exits because no task can become RUNNING. An error is reported if any tasks have not terminated.

Scheduling cannot preempt a task, and vice versa. The currently running task stops execution by explicitly invoking a wait, sleep, or resultis function, or by calling on a pending task.

Random Numbers

Simulations commonly need random numbers for time delays, arrival times or rates, and for other purposes. The coroutine library provides several simple random (actually pseudo-random) number generators which are useful for most purposes. They are all based on the C library rand function. If you need better quality pseudo-random numbers, you can use these classes as a model for your own versions.

Three classes of random-number generators are provided, as shown in Table 2-8.

Table 2-8 Random-Number Classes

Class
Description

randint

Uniformly-distributed random numbers, int or floating-point.

urand

Uniformly-distributed random ints in a given range.

erand

Exponentially-distributed ints about a given mean.

Class randint has the members described in Table 2-9.

Table 2-9 Class randint

Member
Description

randint(long seed=0)

Constructor, providing initial seed for function rand.

int draw()

Returns uniformly-distributed ints in the range 0 to INT_MAX.

float fdraw()

Returns uniformly-distributed floats in the range 0.0 to 1.0.

double ddraw()

Returns uniformly-distributed doubles in the range 0.0 to 1.0.

void seed(long)

Sets a new seed and reinitializes the generator.

Class urand has the members described in Table 2-10.

Table 2-10 Class urand

Member
Description

urand(int low, int high)

Constructor, providing lower and upper bounds of the range.

int draw()

Returns uniformly-distributed ints in the range low through high.

Class erand has the members described in Table 2-11.

Table 2-11 Class erand

Member
Description

erand(int mean);

Constructor, providing the mean value.

int draw()

Returns exponentially-distributed ints about the mean.

Histograms

The coroutine library provides class histogram for data gathering. A histogram consists of a set of bins, each containing a count of the number of items within the range of the bin. When you construct an object of class histogram, you specify the initial range and number of bins. If values outside the current range must be counted, the range is automatically extended by doubling the range of each individual bin. The number of bins cannot be changed. The add function increments the count of the bin associated with the given value. The print function displays the contents of the histogram in the form of a table. Other data is maintained, as described in Table 2-12.

Table 2-12 Class `histogram`
Member	Description
`histogram(int nbins=16, int l=0, int r=16)`	Constructor; sets the number of bins and initial range
`void add(int value)`	Increment count of the histogram bin for `value.`
`void print()`	Prints the current histogram.
`int l, r`	Denotes the left and right boundaries of the current range.
`int binsize`	Denotes the current size of each bin.
`int nbin`	Denotes the number of bins (fixed).
`int* h`	Denotes the pointer to storage for bins.
`long sum`	Denotes the sum of all bins.
`long sqsum`	Denotes the sum of squares of all bins.

Real-Time and Interrupts

As noted in "System Time" on page 22, the coroutine library normally runs independently of realtime, and uses only a simulated passage of time in arbitrary units. A class which handles interrupts is available to allow real-time response to external events. You can define an interrupt handler for any UNIX signal using class Interrupt_handler:


class Interrupt_handler : public object {
public:
virtual int pending(); // False once after each interrupt
Interrupt_handler(int sig); // Create handler for signal sig
~Interrupt_handler();

private:
virtual void interrupt(); // the interrupt handler function
int signo; // signal number
int gotint; // got an interrupt but alert not done
Interrupt_handler *prev; // previous handler for this signal
};

When the signal occurs, the virtual member function interrupt gets control, interrupting whatever task is currently running. When interrupt returns, the original task resumes where it left off. This seems to violate the non-preemptive nature of the task system, but function interrupt is not a task. For this reason, function interrupt should just establish whatever data is necessary for a normal task to process. The base-class version of interrupt does nothing but return. You derive your own handler class from Interrupt_handler to do whatever you need.

The next time the scheduler is invoked, a special predefined task called the interrupt alerter is run ahead of other waiting tasks. Its job is to alert all handlers whose signals have occurred since the last time it ran. Any tasks that were waiting on an Interrupt_handler are thus alerted, and become ready to run. This is how you schedule a task T to run when an interrupt occurs:

: 1. Create an object IH derived from Interrupt_handler for the signal.
: 2. Write the interrupt member function for it.
: 3. Have task T wait on handler IH.

Code Example 2-12 uses the keyboard interrupt, normally the Delete key, as a signal to process data kept in a queue. A discussion follows the sample program.

Code Example 2-12 Handling Interrupts

#include <task.h>

#include <signal.h>

#include <stdlib.h>

#include <stdio.h>

static char **gargv;    // next command-line argument

static char **oargv;    // first command-line argument

static int gcount = 0;  // number of args gotten

int get_data() {        // return the next command-line argument

    ++gcount;

    if( *gargv == 0 )   // recycle if not enough

        gargv = oargv;

    return atoi(*(gargv++));

// KB interrupt handler

class KBhandler : public Interrupt_handler {

    void interrupt();

    int *simQ, *simQ_end, *simQ_h, *simQ_t; // simulated queue

public:

    int getNext(int&);          // get the next item from the queue

    KBhandler(int size = 5);

    ~KBhandler() { delete [] simQ; }

};

KBhandler::KBhandler(int size) : Interrupt_handler(SIGINT) {

    // set up simulated queue

    simQ_t = simQ_h = simQ = new int[size];

    simQ_end = &simQ[size];

void KBhandler::interrupt() {

    // put the next command-line arg into the simulated queue

    int *p = simQ_t;

    *p = get_data();

    if( ++p == simQ_end) p = simQ;

    if( p != simQ_h)

        simQ_t = p;

    else {

        puts("interrupt queue overflow");

        task_error(0, 0);

int KBhandler::getNext(int& val) {

    int *p = simQ_h;

    if( p == simQ_t )

        return 0;    // queue empty

    val = *p;

    if( ++p == simQ_end ) p = simQ;

    simQ_h = p;

    return 1;        // data available

// our user task which will wait for interrupts

class KBprinter : public task {

    KBhandler *handler;

public:

    KBprinter();

};

KBprinter::KBprinter() :

        task("KBprinter"),

        handler(new KBhandler) {

    while( gcount < 5 ) {    // first 5 values only

        wait(handler);       // wait for KB interrupt

        int i;

        while( handler->getNext(i) ) // get any available values

            printf("found %d\n", i);

    resultis(0);             // task is finished

int main(int argc, char **argv) {

    if( argc < 2 ) {

        printf("Usage: %s <list of integers>\n", argv[0]);

        return 1;             // error exit

    oargv = gargv = &argv[1]; // make command-line data available

    KBprinter theTask;        // print data on each KB interrupt

    theTask.result();         // wait for theTask to finish

    thistask->resultis(0);    // terminate main task

    return 0;

The previous sample program is a simulation of a simulation. Imagine that you have a queue of data to be processed, and that an external interrupt (UNIX signal) should trigger a round of processing. In the example, you expect a list of integer values on the program command line, and you use these to simulate a source of integer data. Function get_data returns the next command-line integer, cycling back to the beginning if there are not enough of them.

Class KBhandler, derived from Interrupt_handler, provides the handling of the keyboard interrupt SIGINT (usually the Delete key). Rather than work with an actual queue for this example, the constructor sets up a simulated queue as an array of integers. Whenever a keyboard interrupt occurs, member function interrupt gets the next piece of input data and puts it in the queue. Member function getNext retrieves the value at the front of the queue, if any, and returns a status value indicating whether the data is available.

Class KBprinter is the task which waits for a keyboard interrupt and prints all available data. Its constructor sets up a KBhandler and waits on it. When a keyboard interrupt occurs, any tasks waiting on the handler are alerted automatically. In this case, KBprinter is the waiting task. It resumes execution, prints anything in the queue, then returns to waiting. As a simple way to stop this example, we terminate after getting five integers.

The main program creates a KBprinter task, then waits for it to finish by calling result on it.

Note - The main program is an anonymous task, and should terminate by calling resultis on itself.

Coroutine Library Limitations

The coroutine library is flat because a class derived from task may not have derived classes. Only one level of derivation is allowed. This is the way the library was designed and reflects the way the tasks are manipulated on the stack. The enhancement of allowing multiple levels would require a rewrite of the design. For example, the following is not allowed:


class base : public task { ... }; class task1 : public base { ... }; // compiles, but will not work class task2 : public base { ... }; // compiles, but will not work

If you must have certain sets of tasks share a hierarchy, you may adopt a multiple inheritance scheme. For example, you could define a class with shared information. Each task would have class task as its first immediate base class and the shared-data class as another immediate base class:

class base { ... }; // shared portion

class task1 : public task, public base { ... }; // OK

class task2 : public task, public base { ... }; // OK

A pointer to task does not allow access to anything in the base portion of task1 or task2 with the multiple inheritance approach.

Class	Description
`randint`	Uniformly-distributed random numbers, int or floating-point.
`urand`	Uniformly-distributed random ints in a given range.
`erand`	Exponentially-distributed ints about a given mean.

Member	Description
`randint(long seed=0)`	Constructor, providing initial seed for function `rand`.
`int` `draw()`	Returns uniformly-distributed `int`s in the range `0` to `INT_MAX`.
`float fdraw()`	Returns uniformly-distributed `float`s in the range `0.0` to `1.0`.
`double ddraw()`	Returns uniformly-distributed `double`s in the range `0.0` to `1.0`.
`void seed(long)`	Sets a new seed and reinitializes the generator.

Member	Description
`urand(int low, int high)`	Constructor, providing lower and upper bounds of the range.
`int draw()`	Returns uniformly-distributed `int`s in the range `low` through `high`.

Member	Description
`erand(int mean);`	Constructor, providing the mean value.
`int draw()`	Returns exponentially-distributed `int`s about the mean.

The Coroutine Library

2

Introduction

Using the Coroutine Library

Structure of the Coroutine Classes

Table 2-1 Basic Types in a Coroutine Library

Table 2-2 Two Base Classes in a Coroutine Library

Objects

Table 2-3 Public Members of Class object

Tasks

Class task

Table 2-4 Class task States

Table 2-5 Public Parts of Class task

System Time

Timers

Table 2-6 Public Parts of Class timer

Queues

Table 2-7 Queue Functions

Scheduling

Random Numbers

Table 2-8 Random-Number Classes

Table 2-9 Class randint

Table 2-10 Class urand

Table 2-11 Class erand

Histograms

Table 2-12 Class histogram

Real-Time and Interrupts

Coroutine Library Limitations

Table 2-3 Public Members of Class`object`

Class `task`

Table 2-4 Class `task` States

Table 2-5 Public Parts of Class `task`

Table 2-6 Public Parts of Class `timer`

Table 2-9 Class `randint`

Table 2-10 Class `urand`

Table 2-11 Class `erand`

Table 2-12 Class `histogram`