SAMPLE SYSTEM DOCUMENTATION
===========================

DESCRIPTION

This application is used to implement the full coroutine Producer-Consumer
problem.

PIECES AND ALGORITHMS

Cons.h - contains the full coroutine definition for a Consumer and depends on
         Prod.h

Cons.cc - contains the full coroutine implementation for a Consumer who
          consumes two values received by the Producer.  It obtains a "receipt"
          in return for "paying" for the items.  It stops upon receiving a
          signal from the Consumer.

Prod.h - contains the full coroutine definition for a Producer and depends on
         Cons.h

Prod.cc - contains the full coroutine implementation for a Producer who creates
          2 random integers in the range 0 to 99 to be passed to the Consumer
          on each iteration of the loop (# of loop iterations was set by the
          constructor).  These values are passed to the Consumer and the
          Producer receives a "payment".

ProdConsDriver.cc - creates an instance of each of the Producer and Consumer
           coroutines and starts the Producer off with 5 sets of items to be
           produced.  It depends on both Cons.h and Prod.h

Makefile - makefile used to create the executable "prodcons"

DATA STRUCTURES

    _Coroutine Cons {				// consumer coroutine
        Prod &p;				// address of partner coroutine
        int p1, p2;				// items to be consumed
        int status;				// marks a successful delivery
        int done;				// termination flag

        void main();				// main body of the coroutine
      public:
        Cons( Prod &p ) : p(p), done(0) {}	// constructor
        int delivery( int p1, int p2 );		// delivers the two items to be consumed
        void stop();				// used to terminate the coroutine
    }; // Cons

    _Coroutine Prod {				// producer coroutine
        Cons *c;				// address of partner coroutine
        int N;					// number of items to produce
        int money;				// payment received
        int receipt;				// number of returned receipt

        void  main();				// coroutine main
      public:
        int payment( int money );		// transfers payment in and returns receipt
        void start( int N, Cons *c );		// initializes the coroutine
    }; // Prod

CREATING AND RUNNING

The executable is created by issuing the command:
    make prodcons

The application is run by entering the command:
    ./prodcons

No input is accepted from the user, and all command-line arguments are ignored.
The output shows the transfer of information between the Producer and Consumer,
in both directions.

ERRORS AND LIMITATIONS

There are no error messages produced by this program, and it is limited to
having the Producer produce 2*5 random items in the range 0 to 100 while the
consumer consumes them, 2 at a time.