worker.c File Reference

#include <stdio.h>
#include <threads.h>
#include <htils/arena.h>
#include <htils/worker.h>

Functions
static int	htils_worker_entry (void *arg)
	The worker entry point / thread lifecycle.
static b32	htils_worker_start (htils_worker_t *worker, const htils_worker_config_t *config)
	Starts and initializes a worker.
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.

Function Documentation

htils_worker_config_default()

htils_worker_config_t htils_worker_config_default

(

void

)

Default worker options (Detachable).

htils_worker_entry()

int htils_worker_entry ( void * arg )

static

The worker entry point / thread lifecycle.

Initializes and runs the worker or task, and clears the scratch arena when done.

Parameters

arg	The worker to run.

Returns

Always 0.

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.

htils_worker_start()

b32 htils_worker_start ( htils_worker_t * worker, const htils_worker_config_t * config )

static

Starts and initializes a worker.

Creates a new scratch arena, and starts the worker thread, making sure each required field is set.

Parameters

worker	The worker to start.
config	Worker options, or null for defaults.

Returns

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