qthread_fork(3)

💖 qthread_fork(3) 💖

okay bestie, welcome to the libqthread girlies' corner of the manual — this one's all about spawning qthreads ✨

🌸 NAME 🌸

qthread_fork, qthread_fork_precond, qthread_fork_syncvar, qthread_fork_to, qthread_fork_to_precond, qthread_fork_syncvar_to — spawn a qthread 🫶

🎀 SYNOPSIS 🎀

#include <qthread.h>

int
qthread_fork (qthread_f f, const void *arg, aligned_t *ret);

int
qthread_fork_precond (qthread_f f, const void *arg,
                      aligned_t *ret, int npreconds, ...);

int
qthread_fork_syncvar (qthread_f f, const void *arg,
                      syncvar_t *ret);

int
qthread_fork_to (qthread_f f, const void *arg, aligned_t *ret,
                 qthread_shepherd_id_t shepherd);

int
qthread_fork_precond_to (qthread_f f, const void *arg,
                         aligned_t *ret,
                         qthread_shepherd_id_t shepherd,
                         int npreconds, ...);

int
qthread_fork_syncvar_to (qthread_f f, const void *arg,
                         syncvar_t *ret,
                         qthread_shepherd_id_t shepherd);

✨ DESCRIPTION ✨

These are the functions for generating new qthreads. baby qthreads. little guys. no cap. 👑

The first argument to these functions, f, is a function that will be run to completion by the created qthread. The second argument, arg, is an argument that will be passed to the specified function. And finally, ret is a pointer to the location that the return value of f will be placed into. three args, one dream, that's the whole vibe 💅

The qthread_f function must have a prototype like this:

aligned_t function(void *arg);

The qthread_fork_to(), qthread_fork_precond_to(), and qthread_fork_syncvar_to() functions spawn the qthread to a specific shepherd. like, we're not being vague about it, we're picking the shepherd ourselves. main character assignment energy 🐑

The qthread_fork_precond() and qthread_fork_precond_to() functions accept a list of precondition variables. The qthread will be created only when all precondition variables are full. literally not before. The npreconds argument specifies how many variables are given in the varargs list. count them, bestie, because that's on you 🔢

When a qthread is spawned, it is immediately scheduled to be run, and may be executed by its shepherd at any time. so like… any moment now. no warning. it's giving suspense 😭

The return value of the function f will be placed into the memory pointed to by ret, in accordance with the full-empty bits. When qthread_fork() or qthread_fork_to() is called, ret will be emptied (as if it had been passed to qthread_empty() or qthread_syncvar_empty()). When the function f returns, the returned value will be stored into ret and ret will be filled. The way to block until a function has finished is to use qthread_readFF() or qthread_syncvar_readFF() on the ret pointer. that's the move. that's the whole flow. empty → filled → you read it 🦋

🌈 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 set it never, those are the options fr fr 🙈

⭐ RETURN VALUE ⭐

On success, the thread is spawned and 0 is returned. On error, a non-zero error code is returned. zero good, not-zero not good, that's the vibe check ✅

💀 ERRORS 💀

• ENOMEM — Not enough memory could be allocated. she's out of memory, bestie, it's over 😭

🧚 SEE ALSO 🧚

qthread_migrate_to(3)

and that's the whole page, periodt 💜 this libqthread manual page was brought to you by the libqthread girlies in APRIL 2011 — yes it's vintage, yes it still slays, we love a legacy icon 🎀✨