io_queue.c File Reference

Lock-free job queue backing cwist_io_queue. Despite the old file name (io_uring.c), this has nothing to do with Linux io_uring; the io_uring readiness multiplexer lives in reactor.c. More...

#include <cwist/sys/io/cwist_io.h>
#include <cwist/core/mem/alloc.h>
#include <cwist/core/mem/gc.h>
#include <ttak/mem/epoch.h>
#include <pthread.h>
#include <stdatomic.h>
#include <stdbool.h>

Include dependency graph for io_queue.c:

Go to the source code of this file.

Typedefs
typedef struct job_node	job_node_t

Functions
cwist_io_queue *	cwist_io_queue_create (size_t capacity)
	Allocate the queue object and install its sentinel node.
bool	cwist_io_queue_submit (cwist_io_queue *q, cwist_job_func func, void *arg)
	Submit a callback for asynchronous execution by the queue runner.
void	cwist_io_queue_run (cwist_io_queue *q)
	Process queued jobs until shutdown is requested and no work remains.
void	cwist_io_queue_stop (cwist_io_queue *q)
	Request that runners stop without freeing the queue.
void	cwist_io_queue_destroy (cwist_io_queue *q)
	Stop the queue, wake sleepers, and free all remaining nodes.

Detailed Description

Lock-free job queue backing cwist_io_queue. Despite the old file name (io_uring.c), this has nothing to do with Linux io_uring; the io_uring readiness multiplexer lives in reactor.c.

Definition in file io_queue.c.

Typedef Documentation

job_node_t

typedef struct job_node job_node_t

Lock-free job queue inspired by libttak's SPMC queue samples. We keep a single dummy node (Michael & Scott queue) so producers never contend on a mutex while enqueuing jobs.

Memory reclamation: popped sentinel nodes are never freed immediately. Both push and pop run inside ttak EBR critical sections, and an unlinked node crosses two stages (retire_new -> retire_old -> ttak_epoch_retire) gated on observed advances of the ttak global epoch. A node therefore reaches ttak_epoch_retire only after at least one full epoch boundary since its unlink, so a preempted thread still holding the pointer is guaranteed to be inside a stale-epoch critical section and blocks reclamation until it leaves.

Function Documentation

cwist_io_queue_create()

cwist_io_queue * cwist_io_queue_create

(

size_t

capacity

)

Allocate the queue object and install its sentinel node.

Initialize the job queue.

Parameters

capacity

Capacity hint accepted for interface parity and currently unused.

Returns

Queue handle, or NULL when initialization fails.

Definition at line 228 of file io_queue.c.

cwist_io_queue_destroy()

void cwist_io_queue_destroy

(

cwist_io_queue *

q

)

Stop the queue, wake sleepers, and free all remaining nodes.

Destroy the queue and free resources.

Parameters

q	Queue instance to destroy.

Definition at line 343 of file io_queue.c.

cwist_io_queue_run()

void cwist_io_queue_run

(

cwist_io_queue *

q

)

Process queued jobs until shutdown is requested and no work remains.

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

Parameters

q	Queue to run on the current thread.

Definition at line 293 of file io_queue.c.

cwist_io_queue_stop()

void cwist_io_queue_stop

(

cwist_io_queue *

q

)

Request that runners stop without freeing the queue.

Request that all runners stop processing without freeing the queue.

Parameters

q	Queue instance to stop.

Definition at line 331 of file io_queue.c.

cwist_io_queue_submit()

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

Submit a callback for asynchronous execution by the queue runner.

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.

Definition at line 277 of file io_queue.c.