cwist_io.h File Reference

Platform Agnostic Async Job Queue Interface. More...

#include <stddef.h>
#include <stdbool.h>

Include dependency graph for cwist_io.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef struct cwist_io_queue	cwist_io_queue
	Opaque handle for the IO Queue. Backend implementation depends on OS (io_uring, kqueue, select).
typedef void(*	cwist_job_func) (void *arg)
	Job function signature.

Functions
cwist_io_queue *	cwist_io_queue_create (size_t capacity)
	Initialize the job queue.
bool	cwist_io_queue_submit (cwist_io_queue *q, cwist_job_func func, void *arg)
	Submit a job to be executed asynchronously.
void	cwist_io_queue_run (cwist_io_queue *q)
	Run the event loop. Blocks indefinitely, processing jobs as they complete/trigger.
void	cwist_io_queue_stop (cwist_io_queue *q)
	Request that all runners stop processing without freeing the queue.
void	cwist_io_queue_destroy (cwist_io_queue *q)
	Destroy the queue and free resources.

Detailed Description

Platform Agnostic Async Job Queue Interface.

Definition in file cwist_io.h.

Typedef Documentation

cwist_io_queue

typedef struct cwist_io_queue cwist_io_queue

Opaque handle for the IO Queue. Backend implementation depends on OS (io_uring, kqueue, select).

Definition at line 16 of file cwist_io.h.

cwist_job_func

typedef void(* cwist_job_func) (void *arg)

Job function signature.

Parameters

arg	User-provided argument.

Definition at line 22 of file cwist_io.h.

Function Documentation

cwist_io_queue_create()

cwist_io_queue * cwist_io_queue_create

(

size_t

capacity

)

Initialize the job queue.

Parameters

capacity

Maximum concurrent jobs/events.

Returns

Pointer to queue handle, or NULL on failure.

Initialize the job queue.

Parameters

capacity

Capacity hint accepted for interface parity and currently unused.

Returns

Queue handle, or NULL when initialization fails.

Initialize the job queue.

Parameters

capacity

Requested capacity hint. Currently unused by the select fallback.

Returns

Queue handle, or NULL when allocation or synchronization setup fails.

Initialize the job queue.

Parameters

capacity

Capacity hint accepted for interface parity and currently unused.

Returns

Queue handle, or NULL when kqueue setup fails.

Definition at line 228 of file io_queue.c.

References cap, cwist_alloc(), cwist_free(), cwist_full_gc_enabled(), cwist_gc_scope_disown(), and KQ_WAKE_IDENT.

Referenced by cwist_scheduler_create().

cwist_io_queue_destroy()

void cwist_io_queue_destroy

(

cwist_io_queue *

q

)

Destroy the queue and free resources.

Parameters

q	Queue handle.

Destroy the queue and free resources.

Parameters

q	Queue instance to destroy.

Destroy the queue and free resources.

All runners are gone by contract (stop, then join, then destroy).

Parameters

q	Queue handle to destroy.

Definition at line 343 of file io_queue.c.

References cap, cwist_free(), and KQ_WAKE_IDENT.

Referenced by cwist_scheduler_create(), and cwist_scheduler_destroy().

cwist_io_queue_run()

void cwist_io_queue_run

(

cwist_io_queue *

q

)

Run the event loop. Blocks indefinitely, processing jobs as they complete/trigger.

Parameters

q	Queue handle.

Run the event loop. Blocks indefinitely, processing jobs as they complete/trigger.

Parameters

q	Queue to run on the current thread.

Run the event loop. Blocks indefinitely, processing jobs as they complete/trigger.

Parameters

q	Kqueue-backed queue handle.

Definition at line 293 of file io_queue.c.

References cap, cwist_free(), cwist_full_gc_enabled(), cwist_gc_scope_flush(), and KQ_WAKE_IDENT.

cwist_io_queue_stop()

void cwist_io_queue_stop

(

cwist_io_queue *

q

)

Request that all runners stop processing without freeing the queue.

This is useful when the queue is shared by worker threads: callers can stop the runners, join the threads, and then destroy the queue safely.

Parameters

q	Queue handle.

Request that all runners stop processing without freeing the queue.

Parameters

q	Queue instance to stop.

Request that all runners stop processing without freeing the queue.

Runners finish the jobs already submitted, then return. The descriptor stays open until cwist_io_queue_destroy(), so a runner blocked in kevent() is woken by the wake event rather than by a close() that BSD kernels need not notice.

Parameters

q	Queue handle to stop.

Definition at line 331 of file io_queue.c.

References cap, and KQ_WAKE_IDENT.

Referenced by cwist_scheduler_destroy().

cwist_io_queue_submit()

bool cwist_io_queue_submit	(	cwist_io_queue *	q,
		cwist_job_func	func,
		void *	arg
	)

Submit a job to be executed asynchronously.

Parameters

q	Queue handle.
func	Function to execute.
arg	Argument to pass to function.

Returns

true on success, false on failure (queue full/error).

Submit a job to be executed asynchronously.

Parameters

q	Queue that should own the job.
func	Callback to execute.
arg	User payload forwarded to func.

Returns

true on success, or false when the queue is stopping or OOM.

Submit a job to be executed asynchronously.

Parameters

q	Queue that should own the job.
func	Callback to execute.
arg	User payload forwarded to func.

Returns

true on success, or false when the queue is shutting down or OOM.

Submit a job to be executed asynchronously.

Parameters

q	Kqueue-backed queue handle.
func	Callback to execute when the event is consumed.
arg	User payload forwarded to func.

Returns

true on success, false when the queue is stopping, OOM, or event registration fails.

Definition at line 277 of file io_queue.c.

References cap, cwist_alloc(), cwist_free(), cwist_full_gc_enabled(), and cwist_gc_scope_disown().

Referenced by cwist_scheduler_schedule(), and cwist_scheduler_submit().