task_queue.h File Reference

Generic Loom task queue attached to a standard task pool. More...

Go to the source code of this file.

Typedefs
typedef struct loomc_task_queue_t	loomc_task_queue_t
	Opaque generic task queue.

Functions
loomc_status_t	loomc_task_queue_allocate (const loomc_task_pool_t *pool, loomc_allocator_t allocator, loomc_task_queue_t **out_queue)
	Allocates a task queue attached to pool.
loomc_task_sink_t	loomc_task_queue_sink (loomc_task_queue_t *queue)
	Returns a borrowed generic task sink backed by queue.
loomc_status_t	loomc_task_queue_shutdown (loomc_task_queue_t *queue)
	Stops accepting new tasks and begins draining accepted work.
loomc_status_t	loomc_task_queue_await_shutdown (loomc_task_queue_t *queue)
	Waits until every accepted task has drained and the queue process releases.
void	loomc_task_queue_free (loomc_task_queue_t *queue)
	Drains, awaits, and frees queue.

Detailed Description

Generic Loom task queue attached to a standard task pool.

A queue is one scheduling and ownership domain backed by one cooperative process on the pool's shared worker executor. Multiple queues attached to one pool can make progress independently at process drain boundaries. This permits compiler, materialization, and application work to overlap while retaining one worker population.

Function Documentation

loomc_task_queue_allocate()

loomc_status_t loomc_task_queue_allocate	(	const loomc_task_pool_t *	pool,
		loomc_allocator_t	allocator,
		loomc_task_queue_t **	out_queue )

Allocates a task queue attached to pool.

Parameters

pool	Pool whose worker executor will drain the queue.
allocator	Host allocator used for queue storage.
out_queue	Receives the allocated queue on success.

Returns

OK after the queue is ready to accept tasks.

Ownership

The queue retains the pool's worker executor and may outlive the pool handle. The caller owns out_queue and frees it with loomc_task_queue_free after every object that may submit through its sink has completed.

loomc_task_queue_await_shutdown()

loomc_status_t loomc_task_queue_await_shutdown

(

loomc_task_queue_t *

queue

)

Waits until every accepted task has drained and the queue process releases.

Parameters

queue

Queue whose shutdown has already begun.

Returns

OK after the queue process has released its executor state.

Shutdown must have begun before this call. The calling thread must not be a task executing on queue, because a worker cannot wait for its own release.

loomc_task_queue_free()

void loomc_task_queue_free

(

loomc_task_queue_t *

queue

)

Drains, awaits, and frees queue.

Parameters

queue

Queue to free. Passing NULL is allowed.

The calling thread must not be a task executing on queue, and no owner may retain or submit through the queue sink after this call begins.

loomc_task_queue_shutdown()

loomc_status_t loomc_task_queue_shutdown

(

loomc_task_queue_t *

queue

)

Stops accepting new tasks and begins draining accepted work.

Parameters

queue

Queue to shut down.

Returns

OK after shutdown begins.

This operation is thread safe and idempotent. Tasks already executing finish normally. Their attempts to submit additional work are rejected, so owners of recursively expanding work await that work before shutting down its sink.

loomc_task_queue_sink()

loomc_task_sink_t loomc_task_queue_sink

(

loomc_task_queue_t *

queue

)

Returns a borrowed generic task sink backed by queue.

Parameters

queue

Queue accepting submitted work, or NULL.

Returns

Borrowed sink, or an empty sink for a NULL queue.

The sink remains valid until shutdown begins. Rejected submission leaves task ownership with the caller according to the generic sink contract.