.TH Q_SEARCH 3 2023-07-27 "LIBRECAST" "Librecast Programmer's Manual"
.SH NAME
q_search \- search for an entry in a smolq queue
.SH LIBRARY
Librecast library
.RI ( liblibrecast ", " \-llibrecast )
.SH SYNOPSIS
.nf
.B #include <librecast/q.h>
.PP
.BI "int  q_search(q_t " *q ", void *(*" f ")(void *), void *restrict " arg ");"
.fi
.PP
Compile and link with \fI\-llibrecast\fP.
.SH DESCRIPTION
.BR q_search ()
searches
the queue
.IR q
to find an entry that matches both
.IR f
and
.IR arg .
.PP
No locks, so readers may read while we're searching, and writers may write.  If
something is read while we search, we will still return a positive match for
that item, even though it is no longer in the queue.  If a writer writes we will
not notice that write. If this is a problem, for a particular use-case, an
external lock will be required.
.PP
.SH RETURN VALUE
The
.BR q_push ()
function returns 1 if found, zero if not found. On error, -1 is returned and
.IR errno
is set to indicate the error.
.PP
.SH ERRORS
.PP
The function can fail with any of the errors for
.BR sem_getvalue (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 q_wait (3),
.BR sem_getvalue (3).