NAME

       llcv - library for manipulating linked-list condition variable objects

SYNOPSIS

           #include "llcv.h"

           typedef struct llcv_str
           {
               Lyst            list;
               pthread_mutex_t mutex;
               pthread_cond_t  cv;
           } *Llcv;

           typedef int (*LlcvPredicate)(Llcv);

           [see description for available functions]

DESCRIPTION

       A "linked-list condition variable" object (LLCV) is an inter-thread communication
       mechanism that pairs a process-private linked list in memory with a condition variable as
       provided by the pthreads library.  LLCVs echo in thread programming the standard ION
       inter-process or inter-task communication model that pairs shared-memory semaphores with
       linked lists in shared memory or shared non-volatile storage.  As in the semaphore/list
       model, variable-length messages may be transmitted; the resources allocated to the
       communication mechanism grow and shrink to accommodate changes in data rate; the rate at
       which messages are issued is completely decoupled from the rate at which messages are
       received and processed.  That is, there is no flow control, no blocking, and therefore no
       possibility of deadlock or "deadly embrace".  Traffic spikes are handled without impact on
       processing rate, provided sufficient memory is provided to accommodate the peak backlog.

       An LLCV comprises a Lyst, a mutex, and a condition variable.  The Lyst may be in either
       private or shared memory, but the Lyst itself is not shared with other processes.  The
       reader thread waits on the condition variable until signaled by a writer that some
       condition is now true.  The standard Lyst API functions are used to populate and drain the
       linked list.  In order to protect linked list integrity, each thread must call llcv_lock()
       before operating on the Lyst and llcv_unlock() afterwards.  The other llcv functions
       merely effect flow signaling in a way that makes it unnecessary for the reader to poll or
       busy-wait on the Lyst.

       Llcv llcv_open(Lyst list, Llcv llcv)
           Opens an LLCV, initializing as necessary.  The list argument must point to an existing
           Lyst, which may reside in either private or shared dynamic memory.  llcv must point to
           an existing llcv_str management object, which may reside in either static or dynamic
           (private or shared) memory -- but NOT in stack space.  Returns llcv on success, NULL
           on any error.

       void llcv_lock(Llcv llcv)
           Locks the LLCV's Lyst so that it may be updated or examined safely by the calling
           thread.  Fails silently on any error.

       void llcv_unlock(Llcv llcv)
           Unlocks the LLCV's Lyst so that another thread may lock and update or examine it.
           Fails silently on any error.

       int llcv_wait(Llcv llcv, LlcvPredicate cond, int microseconds)
           Returns when the Lyst encapsulated within the LLCV meets the indicated condition.  If
           microseconds is non-negative, will return -1 and set errno to ETIMEDOUT when the
           indicated number of microseconds has passed, if and only if the indicated condition
           has not been met by that time.  Negative values of the microseconds argument other
           than LLCV_BLOCKING (defined as -1) are illegal.  Returns -1 on any error.

       void llcv_signal(Llcv llcv, LlcvPredicate cond)
           Locks the indicated LLCV's Lyst; tests (evaluates) the indicated condition with regard
           to that LLCV; if the condition is true, signals to the waiting reader on this LLCV (if
           any) that the Lyst encapsulated in the indicated LLCV now meets the indicated
           condition; and unlocks the Lyst.

       void llcv_signal_while_locked(Llcv llcv, LlcvPredicate cond)
           Same as llcv_signal() except does not lock the Llcv's mutex before signalling or
           unlock afterwards.  For use when the Llcv is already locked; prevents deadlock.

       void llcv_close(Llcv llcv)
           Destroys the indicated LLCV's mutex and condition variable.  Fails silently (and has
           no effect) if a reader is currently waiting on the Llcv.

       int llcv_lyst_is_empty(Llcv Llcv)
           A built-in "convenience" predicate, for use when calling llcv_wait(), llcv_signal(),
           or llcv_signal_while_locked().  Returns true if the length of the indicated LLCV's
           encapsulated Lyst is zero, false otherwise.

       int llcv_lyst_not_empty(Llcv Llcv)
           A built-in "convenience" predicate, for use when calling llcv_wait(), llcv_signal(),
           or llcv_signal_while_locked().  Returns true if the length of the LLCV's encapsulated
           Lyst is non-zero, false otherwise.

SEE ALSO

       lyst(3)