PTHREAD_WORKQUEUE(3)

💖 PTHREAD_WORKQUEUE(3) 💖

okay bestie, sit DOWN, because today we're learning about thread workqueues — and yes this is a Library Functions Manual situation, so you know it's gonna be giving real system-programming energy. 🧚✨

---

✨ NAME ✨

So there's basically two girlboss squads of functions here:

• pthread_workqueue_init_np, pthread_workqueue_create_np, pthread_workqueue_additem_np — these are the thread workqueue operations. the main characters.
• pthread_workqueue_attr_init_np, pthread_workqueue_attr_destroy_np, pthread_workqueue_attr_getovercommit_np, pthread_workqueue_attr_setovercommit_np, pthread_workqueue_attr_getqueuepriority_np, pthread_workqueue_attr_setqueuepriority_np — and these are the thread workqueue attribute operations. the supporting cast, but honestly they eat. 💅

---

🌸 SYNOPSIS 🌸

like, the whole vibe is right here, no notes:

#include <pthread_workqueue.h>

int
pthread_workqueue_init_np(void);

int
pthread_workqueue_create_np(pthread_workqueue_t *workqp,
    const pthread_workqueue_attr_t * attr);

int
pthread_workqueue_additem_np(pthread_workqueue_t workq,
    void ( *workitem_func)(void *), void * workitem_arg,
    pthread_workitem_handle_t * itemhandlep, unsigned int *gencountp);

int
pthread_workqueue_attr_init_np(pthread_workqueue_attr_t *attr);

int
pthread_workqueue_attr_destroy_np(pthread_workqueue_attr_t *attr);

int
pthread_workqueue_attr_getovercommit_np(pthread_workqueue_attr_t *attr,
    int *ocommp);

int
pthread_workqueue_attr_setovercommit_np(pthread_workqueue_attr_t *attr,
    int ocomm);

int
pthread_workqueue_attr_getqueuepriority_np(pthread_workqueue_attr_t *attr,
    int *qpriop);

int
pthread_workqueue_attr_setqueuepriority_np(pthread_workqueue_attr_t *attr,
    int qprio);

---

🦋 DESCRIPTION 🦋

so the pthread_workqueue_*_np() functions are how you create work queues and submit work items to a thread pool. that's the whole plot. 🫶

and here's the fun part — you, the user, can spin up multiple work queues of different priority AND manually overcommit the available resources. slay, but also, respectfully, careful. 😭

• pthread_workqueue_init_np() — allocates and initializes the whole thread workqueue subsystem. the origin story. ⭐
• pthread_workqueue_create_np() — makes a brand new thread workqueue with the attributes you pass in attr. if attr is NULL, then the default attributes get used instead (no thoughts, head empty, defaults). and you get a workqueue handle back in the workqp parameter. 👑
• thread workqueue attributes are literally just there to specify parameters to pthread_workqueue_create_np(). and the bestie behaviour here? one attribute object can be reused across multiple calls to pthread_workqueue_create_np() — with or without modifications between calls. recycle, reuse, iconic. 🌈
• pthread_workqueue_additem_np() — this is the one that actually submits work items to the thread pool you named in the workq parameter. the work item function and its argument go in workitem_func and workitem_arg. and the work item handle comes back to you in itemhandlep. 🎀
• pthread_workqueue_attr_init_np() — initializes attr with all the default thread workqueue attributes. fresh start energy.
• pthread_workqueue_attr_destroy_np() — destroys attr. rip bozo 💀
• the pthread_workqueue_attr_set*_np() functions set the attribute that matches whatever the function name says. yes it's that straightforward, the naming ate.
  • pthread_workqueue_attr_setovercommit_np() sets the overcommit flag. and lowkey important: if the overcommit flag is set, then more threads will be started, if needed — which may overcommit the physical resources of the system. > bestie. that is a real warning. that is your machine's actual physical resources. 🚨
  • pthread_workqueue_attr_setqueuepriority_np() sets the queue priority attribute of the thread work queue, and it must be set to one of the following values:
• WORKQ_HIGH_PRIOQUEUE — work items in the queue with this attribute will be given higher priority by the thread scheduler. main character queue fr. 🔥
• WORKQ_DEFAULT_PRIOQUEUE — work items in the queue with this attribute are given the default priority. neutral. chill. no drama.
• WORKQ_LOW_PRIOQUEUE — work items in the queue with this attribute will be given lower priority by the thread scheduler. they're in the back of the group chat, and that's just their truth.

and the pthread_workqueue_attr_get*_np() functions? they copy the value of the attribute matching the function name to the location pointed to by the second function parameter. get = grab the value and put it over there. iykyk. ✨

---

💜 RETURN VALUES 💜

if it works? these functions return 0. periodt. 🎉

if it doesn't work? they return an error number to indicate the error. not a vibe, but at least it's informative. 💀

---

😭 ERRORS 😭

okay buckle up, here's the whole list, and yes we're going through all of it:

the pthread_workqueue_init_np() function will fail if:

• [ENOMEM] — Out of memory.

the pthread_workqueue_create_np() function will fail if:

• [ENOMEM] — Out of memory.

the pthread_workqueue_additem_np() function will fail if:

• [EINVAL] — Invalid workqueue handle.
• [ENOMEM] — Out of memory.
• [ESRCH] — Can not find workqueue.

the pthread_workqueue_attr_init_np() function will fail if:

• [ENOMEM] — Out of memory.

the pthread_workqueue_attr_destroy_np() function will fail if:

• [EINVAL] — Invalid value for attr.

the pthread_workqueue_attr_setqueuepriority_np() function will fail if:

• [EINVAL] — Invalid value for attr or for qprio.

and the pthread_workqueue_attr_setovercommit_np(), pthread_workqueue_attr_getovercommit_np() and pthread_workqueue_attr_getqueuepriority_np() functions will fail if:

• [EINVAL] — Invalid value for attr.

---

🍓 SEE ALSO 🍓

• pthread(3)
• sysctl(3)

go read those next bestie, we love a little homework. 📚

---

💀 BUGS 💀

okay so there are two things you genuinely need to know, and I'm saying them with my whole chest:

• there is no way, currently, to remove or destory work queues and pending work items other than exiting the process. like. that's it. that's the escape hatch. exiting the process. 💀
• all worker threads run at the same thread priority — however, items placed on high-priority workqueues will be executed before those on lower-priority workqueues. so the queue priority still matters, it's just not coming from the thread priority itself. noted, remembered, never forgotten. 🫡

---

👑 HISTORY 👑

this thread workqueues code was created to support Grand Central Dispatch (GCD or libdispatch), and it first appeared in FreeBSD 8.0. she's got lore. she's got a whole origin arc. 🌟

---

🌈 AUTHORS 🌈

• Mark Heily <mark@heily.com>. 🫶

and, based on earlier work by:

• Stacey Son <sson@FreeBSD.org>
• Apple, Inc.

collab of the century, honestly. 🤝

---

so yeah, that's the whole page bestie. and before I go — this one's stamped Debian, dated December 12, 2009, and it lives in the PTHREAD_WORKQUEUE(3) section of your manual. go forth and workqueue responsibly, mwah 💅💖✨