qthread_spawn(3)

📦 version 1.22^20251007gitcedb1fc, in fedora 43, fedora 44

✨ qthread_spawn(3) — the libqthread page bestie 💖

okay so. welcome to the manual page for qthread_spawn(3), which lives in libqthread, and which is genuinely the moment. sit down, grab a strawberry 🍓, and let's get into it.

🎀 NAME 🎀

qthread_spawn — spawn a qthread (task). that's it, that's the whole vibe. you're making a task and you're putting it out into the world 💅

🌸 SYNOPSIS 🌸

#include <qthread.h>

int
qthread_spawn (qthread_f             f,
               const void           *arg,
               size_t                arg_size,
               void                 *ret,
               size_t                npreconds,
               void                 *preconds,
               qthread_shepherd_id_t target_shep,
               unsigned int          feature_flags);

look at her. eight whole arguments. she's an icon, she's a legend, and she IS the moment 👑

💜 DESCRIPTION 💜

okay so this is the master function for generating and scheduling new tasks. like, the mother of all spawners. every other function that spawns tasks — especially the ones whose names start with the string "qthread_fork" — is fundamentally just a convenience wrapper function around this one. they're all her little sisters. no cap 🫶

f (the first argument) is a function that will be run to completion as the created task. the qthread_f function must have a prototype like this:

aligned_t function(void *arg);

arg (second argument) is an argument for the function. the way this pointer gets treated depends entirely on the value of the third argument, arg_size:

  • if arg_size is zero, the pointer is passed to the function f unchanged. no notes, just the raw pointer, walking in as-is.
  • if arg_size is non-zero, then arg_size bytes will be copied from arg and stored in task-specific memory. this memory is usually pre-allocated (unless arg_size is very large), so the performance is limited primarily by the speed of memcpy(). and when f gets called, a pointer to the copy is passed as the argument to f instead of the original value of arg. it's giving "i made you a copy, bestie, you're safe" 😌

ret (fourth argument) is a pointer indicating where to store the return value of f. this location may be an aligned_t, a syncvar_t, or a qt_sinc_t, and the type is indicated with flags passed in the feature_flags argument. the location may also be NULL. here's the tea:

  • if the type is an aligned_t, the return value location is emptied by qthread_spawn() and is stored by calling qthread_writeF() when the task returns.
  • if the type is a syncvar_t, the return value location is emptied by qthread_spawn() and is stored by calling qthread_syncvar_writeF() when the task returns.
  • if the type is a qt_sinc_t, when the task returns, the function qt_sinc_submit() is called on the sinc. and if it's so configured (by passing the flag QTHREAD_SPAWN_RET_SINC_VOID to the feature_flag argument), the return value is submitted to the sinc.

npreconds and preconds (fifth and sixth arguments) are for creating "preconditioned" tasks, also sometimes referred to as "data-dependent" tasks or "triggered" tasks. so fancy of them. ✨

  • preconds is expected to be an array of npreconds pointers either to aligned_t's or syncvar_t's (depending on the flags passed to the feature_flag argument).
  • the task will be scheduled only when all of the preconditions have been in the relevant "full" state at least once.
  • the preconditions are queried in an undefined order, so preconditions that can return to the empty state before the task is spawned create undefined behavior.
🚨 bestie, seriously, that last one. undefined behavior is not a cute look. if your precondition can go back to empty before the spawn happens, all bets are off. periodt.

target_shep (seventh argument) specifies a destination shepherd for the task. the task will only ever execute on the specified shepherd unless that shepherd is disabled. if you want the task to be able to execute anywhere, use the pre-defined constant NO_SHEPHERD to specify the lack of preference. she's flexible like that 🌈

feature_flag (eighth argument) is a way of passing additional flags to control task behavior. the available flags are as follows:

  • QTHREAD_SPAWN_SIMPLE — this flag specifies that the task spawned will not block. violations of this promise will cause the program to abort. 😭 in exchange for making this promise, the runtime can avoid a great deal of context-swap overhead and can provide the task with much more stack space "for free" (it uses the worker thread's stack). high risk, high reward, honestly.
  • QTHREAD_SPAWN_NEW_TEAM — tasks are, by default, spawned into their parent's team. this flag specifies that the spawned task will be the founding member of a new task team and not a member of the calling task's team. task teams are collections of tasks. any task that performs a readFF() operation on the return value location of a task that is the founding member of a task team will not be unblocked until all of the tasks in that team also return. it's giving group project, but make it synchronized 👑
  • QTHREAD_SPAWN_NEW_SUBTEAM — this flag specifies that the spawned task will be the founding member of a new task team that is dependent upon the calling task's team, but not a member of the calling task's team. adjacent, but independent. we love boundaries 🦋
  • QTHREAD_SPAWN_RET_SYNCVAR_T — this flag specifies that the return value location, ret, points to a syncvar_t. this flag conflicts with other QTHREAD_SPAWN_RET_* flags. if no QTHREAD_SPAWN_RET_* flags are specified, the return value location is assumed to point to an aligned_t. choose one, bestie, don't be messy 🙈
  • QTHREAD_SPAWN_RET_SINC — this flag specifies that the return value location, ret, points to a qt_sinc_t, and that the return value itself should be submitted to the sinc. this flag conflicts with other QTHREAD_SPAWN_RET_* flags. if no QTHREAD_SPAWN_RET_* flags are specified, the return value location is assumed to point to an aligned_t.
  • QTHREAD_SPAWN_RET_SINC_VOID — this flag specifies that the return value location, ret, points to a qt_sinc_t, and that the return value itself should be ignored. this flag conflicts with other QTHREAD_SPAWN_RET_* flags. if no QTHREAD_SPAWN_RET_* flags are specified, the return value location is assumed to point to an aligned_t. return value said "not my problem" 💀
  • QTHREAD_SPAWN_PC_SYNCVAR_T — this flag specifies that the precondition array, preconds, is an array of pointers to syncvar_t's, rather than aligned_t's. flip the switch, change the type, that's the whole flag 🎀

🧚 SPAWN CACHE 🧚

okay so here's the lore. tasks are normally spawned into a thread-local cache of tasks. the contents of this cache are not visible to other tasks until the next scheduling event, at which point the cache is flushed into the local shepherd's globally visible scheduling queue. scheduling events are times when the scheduling queue must be checked — namely, when the current task either blocks or yields. iykyk 🔥

this cache can be disabled at configure time, in which case tasks are pushed into the globally visible scheduling queue as they are spawned. no waiting, no holding, just immediate main character energy ✨

🌈 ENVIRONMENT 🌈

the operation of these functions is modified by the following environment variables:

  • QTHREAD_STACK_SIZE — this variable specifies, in bytes, the size of the stacks that will be created for each thread. changes to this value during the course of the program run are ignored; the value is only evaluated when qthread_initialize() is run. so set it early or don't bother, bestie ⭐

💖 RETURN VALUE 💖

on success, the thread is spawned and 0 is returned. on error, a non-zero error code is returned. slay when it's zero, cry when it's not 😭

🩷 ERRORS 🩷

  • ENOMEM — not enough memory was available to spawn a task. the runtime is broke, respectfully. 💀

👑 SEE ALSO 👑

qthread_fork(3), qthread_migrate_to(3)

go read those too, they're the supporting cast and they ate 🫶

and that's the page!! 💅 this was libqthread, and the page itself is dated AUGUST 2012 — yes, she's been iconic for that long and she's still serving. bye bestie, go spawn something responsibly 🌸🦋✨

📦 where this page comes from