Q_POOL_CREATE(3)

💖 Q_POOL_CREATE 💖

okay bestie, we're in the Librecast Programmer's Manual today, and the vibe is: thread pools. two functions, one job — q_pool_create and q_pool_destroy, aka initialize and destroy thread pools. that's the whole name section, and honestly? it ate. ✨

---

📚 LIBRARY

it's the Librecast library, fr fr — that's liblibrecast, and you link it with -llibrecast. 🫶

---

✨ SYNOPSIS ✨

first, the include, no cap:

#include <librecast/q.h>

then the two icons themselves:

int q_pool_create(pthread_t tid[], int nthreads, void *(*f)(void *), void *restrict arg);
int q_pool_destroy(pthread_t tid[], int nthreads);

and when you build it, you compile and link with -llibrecast. that's it, that's the whole ritual 💅

---

🧚 DESCRIPTION 🧚

so. q_pool_create() spins up a thread pool of nthreads threads, and it uses f and arg as the start_routine and the argument for each thread. every single one. equal opportunity threads. 👑

and like — the whole point of q_pool_create() is that it's designed to be used with q_job_seek(3), so you can start a thread pool of workers that process jobs from a smolq queue. it's giving worker bee energy 🐝

then when you're done and you want those threads gone, you call q_pool_destroy(). that's the one that cancels and reaps the threads you made with q_pool_create(3). closure, bestie. it's important.

and a lil detail that matters: tid must be an array of pthread_t of size nthreads. don't be out here passing whatever, okay? the size has to match. 🌸

---

🎀 RETURN VALUE 🎀

these functions return zero on success. iconic. we love a zero.

but on error? they return the number of threads that failed to start or stop, and errno gets set to indicate the error. so it's not just "oops" — it's "oops, and here's how many oopses". 💀

now listen, this part is important: if q_pool_create() successfully starts any threads, those are not cancelled if there's a failure starting a later thread. they just keep going. so you gotta call q_pool_destroy(3) to destroy the created threads when you're done — and you pass nthreads minus the return value from the failed call to q_pool_create() to stop the running threads. do the math, bestie. 🧮

---

💜 ERRORS 💜

q_pool_create() may fail with any of the errors for pthread_create(3). that's the whole list. go check pthread_create(3), iykyk.

---

🌈 SEE ALSO 🌈

the whole friend group, go say hi:

• q_job_seek(3)
• q_push(3)
• q_wait(3)
• sem_init(3)
• sem_destroy(3)
• pthread_create(3)

---

and that's the page, bestie!! 🦋 this one's from the LIBRECAST crew, dated 2023-07-23, and you can find it filed under Q_POOL_CREATE(3). go forth and pool your threads responsibly 💖✨🎀