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: 5 nov 2017