.TH Q_PUSH 3 2023-07-25 "LIBRECAST" "Librecast Programmer's Manual"
.SH NAME
q_push \- push a job onto a smolq queue
.SH LIBRARY
Librecast library
.RI ( liblibrecast ", " \-llibrecast )
.SH SYNOPSIS
.nf
.B #include <librecast/q.h>
.PP
.BI "int  q_push(q_t " *q ", void *(*" f ")(void *), void *restrict " arg ");"
.BI "int  q_trypush(q_t " *q ", void *(*" f ")(void *), void *restrict " arg ");"
.fi
.PP
Compile and link with \fI\-llibrecast\fP.
.SH DESCRIPTION
.BR q_push ()
pushes
.IR f
onto the queue
.IR q
with argument
.IR arg.
.PP
.BR q_trypush ()
is the same as
.BR q_push ()
except that if the queue writer 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
.TP
.BR EAGAIN
(
.BR q_trypush ())
The operation could not be performed without blocking. (i.e., the queue was
full).
.PP
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_wait (3),
.BR sem_post (3),
.BR sem_wait (3)