NAME
    producer, consumer
    
SYNOPSIS	
    #include "pc-monitor.h"

    int produce(char * s, int len)
    int consume(char * s, int len)

DESCRIPTION

    Subroutines that are two entry points into a producer-consumer monitor.
    
    Produce enqueues on the ring buffer the sequence of len characters, taken from 
    the char array pointed to by s. 
    
    Consume dequeues from the ring buffer as sequence of up to len characters, and stores
    them in a char array pointed to by s.
    
    The character sequence need not be a string. The null character has no particular
    significance. 
    
    The ring buffer is queried for size. If len is larger than the size of the ring 
    buffer the additional produced characters are ignored, and the additional 
    consumed characters are discarded.
    
    Each call to produce contributes an atomic message to the ring buffer. All characters
    are enqueued together in the ring buffer, and a call to consume takes all characters
    from that message. That is, multiple consumers and producers working simultaneously
    do not confuse messages. 
    
    The procedures are thread-safe: each call enters and leaves the monitor as needed.
    Produce will wait until there is room in the ring buffer to enqueue the message;
    consume will wait until there is a message in the ring buffer to dequeue.

RETURN VALUE

    Returns the number of characters actually enqueued or dequeued, or -1 if error.


NOTES

    Although produce and consume can use any algorithm to transfer messages as a 
    unit, one method is to use the emptiness of the ring buffer to delimit messages.

BUGS

    Might not support zero length messages.
    
    Rebooting the operating system might be needed after an incomplete run of any 
    producer-consumer system using these calls.
    
    Messages produced in one mode and consumed in a different mode need not respect
    message boundaries. In fact, the behavior in such cases should not cause the 
    kernel or client programs to crash, but otherwise is undefined.
    

NAME
    producer, consumer
    
SYNOPSIS	
	
    producer [-vM] [-r _num_] [-n _num_] _message_
    consumer [-vM] [-r _num_] [-n _num_]
    
DESCRIPTION

    A thread-safe produce-consumer system, calling produce() and consume().
    
    The _message_ argument is a collection of messages that is sent by the producer and
    received by the consumer. 

    When not in Message Mode, the messages are the individual characters of _message_.
    Each character is sent and received independently.
    
    In Message Mode, _message_ is parsed on the "." character and each parsed component 
    is a single message and is sent in its entirety. In Message Mode  the "." is not sent.

    In Message Mode the consumer prints each message on its own line; else it prints
    the characters without new lines.
    
    The following options are available:
        -n     - producer repeats _num_ times the sending of all messages in _message_.
                 consumer consumes n messages before exiting. If _num_ is 0, producer and
                 consumer repeat forever. Default is _num_ is 1.
        -r     - sleep interval between productions/consumptions, in seconds. 
                 Default sleep time is 1 second.
        -v     - verbose output (useful for debugging)
        -M     - Message Mode. 
                 Interpret _message_ as a "." delimited sequence of "words".
                 Each word is sent and received completely.
    
 

HISTORY
    An in-kernel monitor to implement Producer-Consumer first appeared as project 3a
    in CSC521.111. Combining the monitor with the ring buffer appeared as project 3, 
    CSC421.151. Encapsulating the monitor into pc-monitor.c appeared first in 
    project 3, CSC421.171.

BUGS
    

This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.

author: burton rosenberg
created: 26 oct 2015
update: 7 nov 2016