worker.h File Reference

#include <stdatomic.h>
#include <threads.h>
#include <htils/arena.h>
#include <htils/atomic_types.h>
#include <htils/basictypes.h>

Go to the source code of this file.

Data Structures
struct	htils_worker_config
	Worker options. More...
struct	htils_worker
	A reusable worker slot. More...

Typedefs
typedef void(*	htils_worker_fn_t) (void *userdata, arena_t *scratch)
	Single-shot worker body.
typedef htils_worker_step_t(*	htils_worker_task_t) (void *userdata, arena_t *scratch)
	Sliced task body.
typedef struct htils_worker_config	htils_worker_config_t
	Worker options.
typedef struct htils_worker	htils_worker_t
	A reusable worker slot.

Enumerations
enum	htils_worker_step_t { HTILS_WORKER_CONTINUE , HTILS_WORKER_DONE }
	Result of one task slice. More...

Functions
htils_worker_config_t	htils_worker_config_default (void)
	Default worker options (Detachable).
b32	htils_worker_spawn (htils_worker_t *worker, const htils_worker_config_t *config, htils_worker_fn_t fn, void *userdata)
	Spawns a single-shot worker.
b32	htils_worker_spawn_task (htils_worker_t *worker, const htils_worker_config_t *config, htils_worker_task_t task, void *userdata)
	Spawns a sliced worker task.
void	htils_worker_request_stop (htils_worker_t *worker)
	Ask a worker to stop.
void	htils_worker_set_paused (htils_worker_t *worker, b32 paused)
	Pause or resume a sliced worker.
b32	htils_worker_running (const htils_worker_t *worker)
	Check if a worker is running a task.
b32	htils_worker_paused (const htils_worker_t *worker)
	Check if a sliced worker is paused.
b32	htils_worker_should_stop (const htils_worker_t *worker)
	Checks whether a stop was requested (Polled by single-shot workers).
void	htils_worker_join (htils_worker_t *worker)
	Waits for the task to finish.

Typedef Documentation

htils_worker_config_t

typedef struct htils_worker_config htils_worker_config_t

Worker options.

Parameters

detach

Fire-and-forget; skip join, poll running 'til false.

htils_worker_fn_t

typedef void(* htils_worker_fn_t) (void *userdata, arena_t *scratch)

Single-shot worker body.

Runs once on its own thread. userdata carries the task's inputs and result (the caller pre-allocates result storage and points a field at it). scratch is private working memory, cleared when the task returns. For a long task, poll htils_worker_should_stop and return early.

Parameters

userdata	The caller's task context (input + result).
scratch	Worker's scratch arena (cleared at task end).

Precondition

• userdata must be pre-allocated for both writing and reading, unless the worker single-shot is just being used for something context-less.
• scratch must be valid and cannot be null.

htils_worker_t

typedef struct htils_worker htils_worker_t

A reusable worker slot.

Caller-owned, one per concurrent task. Each slot owns one scratch arena, created lazily and cleared at the end of every task. A slot must not be respawned while still running. It runs either a single-shot fn or a sliced task (exactly one is set).

Parameters

thread	The worker thread.
scratch	Private temp arena; cleared each task, reused on respawn.
running	Cleared when the task finishes or is stopped.
pause	Pauses a sliced task between slices.
detached	Whether the worker is fire-and-forget.
fn	The active single-shot body, or null.
task	The active sliced body, or null.
userdata	The active task context.
pause_mtx	Guards the pause wait.
pause_cnd	Signalled on resume/stop.
primitives_init	Whether the primitives have been initialized.

htils_worker_task_t

typedef htils_worker_step_t(* htils_worker_task_t) (void *userdata, arena_t *scratch)

Sliced task body.

Run by a library-owned loop that calls this repeatedly and checks stop/pause between slices, so the body never polls. Do one bounded unit of work per call and return. scratch persists across slices and is cleared only when the task ends.

Parameters

userdata	The caller's task context (input + result).
scratch	Worker's scratch arena, kept between slices.

Precondition

• userdata must be pre-allocated for both writing and reading, unless the task is context-less.
• scratch must be valid and cannot be null.

Returns

HTILS_WORKER_CONTINUE for another slice, HTILS_WORKER_DONE to finish.

Enumeration Type Documentation

htils_worker_step_t

enum htils_worker_step_t

Result of one task slice.

Enumerator
HTILS_WORKER_CONTINUE	Run another slice.
HTILS_WORKER_DONE	Finished; end the task.

Function Documentation

htils_worker_config_default()

htils_worker_config_t htils_worker_config_default

(

void

)

Default worker options (Detachable).

htils_worker_join()

void htils_worker_join

(

htils_worker_t *

worker

)

Waits for the task to finish.

Joins the thread. Call exactly once for a non-detached worker; a no-op for detached workers (poll running instead).

Parameters

worker

The worker to join.

htils_worker_paused()

b32 htils_worker_paused

(

const htils_worker_t *

worker

)

Check if a sliced worker is paused.

Parameters

worker

The worker to check.

Returns

true if the worker is paused, false if not.

htils_worker_request_stop()

void htils_worker_request_stop

(

htils_worker_t *

worker

)

Ask a worker to stop.

Clears the running flag. A sliced task stops at the next slice boundary; a single-shot body observes it via htils_worker_should_stop. Non-blocking.

Parameters

worker

The worker to signal.

htils_worker_running()

b32 htils_worker_running

(

const htils_worker_t *

worker

)

Check if a worker is running a task.

Parameters

worker

The worker to check.

Returns

true if the worker is running a task, false if not.

htils_worker_set_paused()

void htils_worker_set_paused	(	htils_worker_t *	worker,
		b32	paused )

Pause or resume a sliced worker.

While paused, the worker loop parks between slices 'til resumed or stopped. No effect on single-shot workers.

Parameters

worker	The worker to pause.
paused	Whether to pause (true) or resume (false).

Precondition

worker is a valid, running slot.

htils_worker_should_stop()

b32 htils_worker_should_stop

(

const htils_worker_t *

worker

)

Checks whether a stop was requested (Polled by single-shot workers).

Parameters

worker

The worker to check.

Returns

true if the worker was requested to stop, false if not.

See also

htils_worker_request_stop()

htils_worker_spawn()

b32 htils_worker_spawn	(	htils_worker_t *	worker,
		const htils_worker_config_t *	config,
		htils_worker_fn_t	fn,
		void *	userdata )

Spawns a single-shot worker.

Runs fn once on a new thread. The slot must not already be running.

Parameters

worker	The slot to initialize.
config	Options, or null for defaults.
fn	The single-shot function to run.
userdata	The task context passed to fn.

Precondition

• worker is a valid, non-running slot.
• fn is not null.

Returns

true on success, false if the thread couldn't be created.

htils_worker_spawn_task()

b32 htils_worker_spawn_task	(	htils_worker_t *	worker,
		const htils_worker_config_t *	config,
		htils_worker_task_t	task,
		void *	userdata )

Spawns a sliced worker task.

Runs task in a library-owned loop that checks stop/pause between slices, so the body never polls. task returns HTILS_WORKER_CONTINUE to keep going or HTILS_WORKER_DONE to finish.

Parameters

worker	The slot to initialize.
config	Options, or null for defaults.
task	The sliced task to run.
userdata	The task context passed to task.

Precondition

• worker is a valid, non-running slot.
• task is not null.

Returns

true on success, false if the thread couldn't be created.