.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ici::doc::pod3::llcv 3"
.TH ici::doc::pod3::llcv 3 "2016-07-07" "perl v5.24.1" "ICI library functions"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
llcv \- library for manipulating linked\-list condition variable objects
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    #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]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A \*(L"linked-list condition variable\*(R" object (\s-1LLCV\s0) 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 \s-1ION\s0 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
\&\*(L"deadly embrace\*(R".  Traffic spikes are handled without impact on
processing rate, provided sufficient memory is provided to
accommodate the peak backlog.
.PP
An \s-1LLCV\s0 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 \s-1API\s0 functions are used to populate and drain the linked
list.  In order to protect linked list integrity, each thread must call
\&\fIllcv_lock()\fR before operating on the Lyst and \fIllcv_unlock()\fR 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.
.IP "Llcv llcv_open(Lyst list, Llcv llcv)" 4
.IX Item "Llcv llcv_open(Lyst list, Llcv llcv)"
Opens an \s-1LLCV,\s0 initializing as necessary.  The \fIlist\fR argument must point
to an existing Lyst, which may reside in either private or shared dynamic
memory.  \fIllcv\fR must point to an existing llcv_str management object, which
may reside in either static or dynamic (private or shared) memory \*(-- but
\&\fI\s-1NOT\s0\fR in stack space.  Returns \fIllcv\fR on success, \s-1NULL\s0 on any error.
.IP "void llcv_lock(Llcv llcv)" 4
.IX Item "void llcv_lock(Llcv llcv)"
Locks the \s-1LLCV\s0's Lyst so that it may be updated or examined safely by the
calling thread.  Fails silently on any error.
.IP "void llcv_unlock(Llcv llcv)" 4
.IX Item "void llcv_unlock(Llcv llcv)"
Unlocks the \s-1LLCV\s0's Lyst so that another thread may lock and update or examine
it.  Fails silently on any error.
.IP "int llcv_wait(Llcv llcv, LlcvPredicate cond, int microseconds)" 4
.IX Item "int llcv_wait(Llcv llcv, LlcvPredicate cond, int microseconds)"
Returns when the Lyst encapsulated within the \s-1LLCV\s0 meets the indicated
condition.  If \fImicroseconds\fR is non-negative, will return \-1 and set
\&\fIerrno\fR to \s-1ETIMEDOUT\s0 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 \s-1LLCV_BLOCKING
\&\s0(defined as \-1) are illegal.  Returns \-1 on any error.
.IP "void llcv_signal(Llcv llcv, LlcvPredicate cond)" 4
.IX Item "void llcv_signal(Llcv llcv, LlcvPredicate cond)"
Locks the indicated \s-1LLCV\s0's Lyst; tests (evaluates) the indicated condition
with regard to that \s-1LLCV\s0; if the condition is true, signals to the waiting
reader on this \s-1LLCV \s0(if any) that the Lyst encapsulated in the indicated
\&\s-1LLCV\s0 now meets the indicated condition; and unlocks the Lyst.
.IP "void llcv_signal_while_locked(Llcv llcv, LlcvPredicate cond)" 4
.IX Item "void llcv_signal_while_locked(Llcv llcv, LlcvPredicate cond)"
Same as \fIllcv_signal()\fR except does not lock the Llcv's mutex before
signalling or unlock afterwards.  For use when the Llcv is already
locked; prevents deadlock.
.IP "void llcv_close(Llcv llcv)" 4
.IX Item "void llcv_close(Llcv llcv)"
Destroys the indicated \s-1LLCV\s0's mutex and condition variable.  Fails silently
(and has no effect) if a reader is currently waiting on the Llcv.
.IP "int llcv_lyst_is_empty(Llcv Llcv)" 4
.IX Item "int llcv_lyst_is_empty(Llcv Llcv)"
A built-in \*(L"convenience\*(R" predicate, for use when calling \fIllcv_wait()\fR,
\&\fIllcv_signal()\fR, or \fIllcv_signal_while_locked()\fR.  Returns true if the length
of the indicated \s-1LLCV\s0's encapsulated Lyst is zero, false otherwise.
.IP "int llcv_lyst_not_empty(Llcv Llcv)" 4
.IX Item "int llcv_lyst_not_empty(Llcv Llcv)"
A built-in \*(L"convenience\*(R" predicate, for use when calling \fIllcv_wait()\fR,
\&\fIllcv_signal()\fR, or \fIllcv_signal_while_locked()\fR.  Returns true if the length
of the \s-1LLCV\s0's encapsulated Lyst is non-zero, false otherwise.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIlyst\fR\|(3)