.TH Q_POOL_CREATE 3 2023-07-23 "LIBRECAST" "Librecast Programmer's Manual"
.SH NAME
q_pool_create, q_pool_destroy \- initialize and destroy thread pools
.SH LIBRARY
Librecast library
.RI ( liblibrecast ", " \-llibrecast )
.SH SYNOPSIS
.nf
.B #include <librecast/q.h>
.PP
.BI "int q_pool_create(pthread_t " tid[] ", int " nthreads ", void *(*" f ")(void *), void *restrict " arg ");"
.BI "int q_pool_destroy(pthread_t " tid[] ", int " nthreads ");"
.fi
.PP
Compile and link with \fI\-llibrecast\fP.
.SH DESCRIPTION
The
.BR q_pool_create ()
function creates a thread pool of
.IR nthreads
threads, using
.IR f
and
.IR arg
as the start_routine and argument for each thread.
.PP
.BR q_pool_create ()
is designed for use with
.BR q_job_seek (3)
to start a thread pool of workers to process jobs from a smolq queue.
.PP
The
.BR q_pool_destroy ()
function is called to cancel and reap the threads created with
.BR q_pool_create (3).
.PP
.IR tid
must be an array of pthread_t of size
.IR nthreads .
.PP
.SH RETURN VALUE
These
functions return zero on success. On error, the number of threads that failed
to start or stop is returned and
.IR errno
is set to indicate the error.
.PP
If
.BR q_pool_create ()
successfully starts any threads, these are not cancelled if there is a failure
starting a later thread. Call
.BR q_pool_destroy (3)
to destroy the created threads when done, passing
.IR nthreads
minus the return value from the failed call to
.BR q_pool_create ()
to stop the running threads.
.PP
.SH ERRORS
.BR q_pool_create ()
may fail with any of the errors for
.BR pthread_create (3).
.PP
.SH SEE ALSO
.BR q_job_seek (3),
.BR q_push (3),
.BR q_wait (3),
.BR sem_init (3),
.BR sem_destroy (3),
.BR pthread_create (3)