.TH Q_WAIT 3 2023-07-25 "LIBRECAST" "Librecast Programmer's Manual"
.SH NAME
q_wait \- return the next job from the queue, when available
.SH LIBRARY
Librecast library
.RI ( liblibrecast ", " \-llibrecast )
.SH SYNOPSIS
.nf
.B #include <librecast/q.h>
.PP
.BI "int q_wait(q_t " *q ", q_job_t " *job ");"
.BI "int q_trywait(q_t " *q ", q_job_t " *job ");"
.fi
.PP
Compile and link with \fI\-llibrecast\fP.
.SH DESCRIPTION
.BR q_wait ()
atomically fetches the next
.IR job
in
.IR q
and sets the
.IR job
pointer to it. The call blocks until a job is available.
.PP
.BR q_trywait ()
is the same as
.BR q_wait ()
except that if the queue read lock cannot be immediately obtained, then the
call returns an error
.RI ( errno
set to
.BR EAGAIN )
instead of blocking.
.PP
.SH RETURN VALUE
The
.BR q_push ()
function returns zero on success. On error, -1 is returned and
.IR errno
is set to indicate the error.
.PP
.SH ERRORS
The function can also fail with the errors for
.BR sem_post (3)
or
.BR sem_wait (3).
.PP
.SH SEE ALSO
.BR q_job_seek (3),
.BR q_pool_create (3),
.BR q_pool_destroy (3),
.BR q_init (3),
.BR q_free (3),
.BR q_push (3),
.BR sem_post (3),
.BR sem_wait (3)