.\" 
.\" 	Copyright 2004 Michael B. Allen <mba2000 ioplex.com>
.\" 
.TH svcond 3m "Apr 29, 2005" "libmba-0.9.1" "MBA Library Functions"
.SH NAME
svcond \- POSIX-like condition variables implemented using SysV semaphores.
.SH SYNOPSIS
.nf
.B #include <mba/svcond.h>
.sp
.BI "int svcond_create(svcond_t *" cond ", struct pool *" sempool ");
.br
.BI "int svcond_destroy(svcond_t *" cond ");
.br
.sp
.BI "int svcond_wait(svcond_t *" cond ", svsem_t *" lock ");
.br
.BI "int svcond_signal(svcond_t *" cond ");
.br
.BI "int svcond_broadcast(svcond_t *" cond ");
.br

.fi
.SH DESCRIPTION
Condition variables are similar to semaphores however a lock can be specified with the wait function that will be unlocked just before blocking. When the blocked process or thread is subsequently signalled the lock will be reaquired. In practice this is frequently a superior coordination mechanism to semaphores alone. The
.BR "svcond" (3m)
module provides a POSIX-like condition variables interface implemented using only System V semaphores.
.sp
The
.BR "svcond" (3m)
module is not available in the Win32 environment.
.PP
.TP
.B create
The
.B svcond_create
function initializes the condition variable
.IR "cond" .
The
.I sempool
parameter is an
.BR "svsem" (3m)
pool created with the
.B svsem_pool_create
function as illustrated below. The
.I value
parameter must be 1 and the
.I max_size
parameter must be 3 times the number of condition variables that will be in use at any moment. If semaphores for the condition variable cannot be aquired from the pool,
.I errno
will be set to
.I EAGAIN
and -1 will be returned.
.PP
.RS
.nf
.ta 4n 19n 31n

void
foo(void)
{
    struct pool sempool;
	svcond_t condvar;

    svsem_pool_create(&sempool, 250, 1, 0, NULL); /* create semaphore array */
    svcond_create(&condvar, &sempool); /* initialize one condition variable */

	svcond_wait(&convar);
    ...

.ta
.fi
.RE
.PP

.TP
.B destroy
The
.B svcond_destroy
function releases the semaphores used by the condition variable
.IR "cond" .
It is not an error to call this function with a
.B NULL
parameter, on memory that is zero'd or repeatedly on the same
.I cond
object -- it will be ignored or destroyed only once.
.TP
.B wait
The
.B svcond_wait
function will unlock the semaphore
.I lock
and then sleep until one of the following occurs;
.sp
.br
the thread or process is interrupted by a signal (e.g.
.IR "SIGQUIT" ),
.br
the
.B svcond_broadcast
function is called with the condition variable,
.br
or the
.B svcond_signal
function is called with the condition variable and that process or thread is the next in the wait queue.
.sp
If a
.I SIGINT
is recieved the function will set
.B errno
to
.I EINTR
and return but not before reaquiring
.IR "lock" .
.TP
.B signal
The
.B svcond_signal
function wakes up one process or thread blocked on the condition variable
.I cond
and return from the
.B svsem_wait
call but not before reaquiring the
.IR "lock" .
.TP
.B broadcast
The
.B svcond_broadcast
function wakes up all processes and threads blocked on the condition variable
.I cond
and return from the
.B svsem_wait
call but not before reaquiring the
.IR "lock" .
.SH RETURNS
.TP
.B create
The
.B svcond_create
function returns 0 if the condition variable was successfully initialized or -1 if the operation failed in which case
.I errno
will be set to an appropriate value (e.g.
.I EAGAIN
if 3 semaphores cannot be obtained from the pool).
.TP
.B destroy
If the operation is successful 0 is returned. Otherwise -1 is returned and
.I errno
is set appropriately.
.TP
.B wait
If the operation is successful 0 is returned. Otherwise -1 is returned and
.I errno
is set appropriately.
.TP
.B signal
If the operation is successful 0 is returned. Otherwise -1 is returned and
.I errno
is set appropriately.
.TP
.B broadcast
If the operation is successful 0 is returned. Otherwise -1 is returned and
.I errno
is set appropriately.