task.h File Reference

Generic caller-scheduled work. More...

Go to the source code of this file.

Data Structures
struct	loomc_task_vtable_t
	Stateless callbacks for one task representation. More...
struct	loomc_task_t
	Base embedded at offset zero in one caller-defined work record. More...
struct	loomc_task_sink_t
	Borrowed destination for generic tasks. More...

Typedefs
typedef loomc_status_t(*	loomc_task_submit_fn_t) (void *user_data, loomc_task_t *task)
	Accepts ownership of one generic task.

Functions
void	loomc_task_initialize (const loomc_task_vtable_t *vtable, loomc_task_t *out_task)
	Initializes a caller-allocated task base.
void	loomc_task_execute (loomc_task_t *task, loomc_host_size_t worker_ordinal)
	Executes and then destroys an accepted task.
void	loomc_task_destroy (loomc_task_t *task)
	Destroys a task without executing it.
loomc_status_t	loomc_task_sink_submit (loomc_task_sink_t sink, loomc_task_t *task)
	Submits a task and transfers ownership on success.

Detailed Description

Generic caller-scheduled work.

A task is a queueable base embedded in application or LoomC work records. Task sinks provide the ownership boundary needed to compose LoomC with a caller's event loop, deterministic queue, custom scheduler, or the optional standard task queue attached to a shared pool. The protocol carries no compiler, product, cache, thread-pool, or IREE task state.

Typedef Documentation

loomc_task_submit_fn_t

typedef loomc_status_t(* loomc_task_submit_fn_t) (void *user_data, loomc_task_t *task)

Accepts ownership of one generic task.

Parameters

user_data	Sink-owned state.
task	Task offered for submission.

Returns

OK after accepting ownership, or a non-OK status without accepting ownership.

An accepted task is eventually executed exactly once and then destroyed exactly once, possibly before this callback returns. A rejected task is not executed or destroyed by the sink.

Function Documentation

loomc_task_destroy()

void loomc_task_destroy

(

loomc_task_t *

task

)

Destroys a task without executing it.

Parameters

task	Task ownership reference to consume.

Callers use this after a rejected submission they choose not to retry.

loomc_task_execute()

void loomc_task_execute	(	loomc_task_t *	task,
		loomc_host_size_t	worker_ordinal )

Executes and then destroys an accepted task.

Parameters

task	Task ownership reference to consume.
worker_ordinal	Dense mutually exclusive execution-lane ordinal.

Queue implementations call this exactly once for each task they accept. The vtable is captured before execution so the destroy callback may reclaim task storage.

loomc_task_initialize()

void loomc_task_initialize	(	const loomc_task_vtable_t *	vtable,
		loomc_task_t *	out_task )

Initializes a caller-allocated task base.

Parameters

vtable	Static callback table that outlives out_task.
out_task	Task base to initialize.

Both arguments and all vtable callbacks are required. The initialized task must be submitted or destroyed exactly once before its storage is reused.

loomc_task_sink_submit()

loomc_status_t loomc_task_sink_submit	(	loomc_task_sink_t	sink,
		loomc_task_t *	task )

Submits a task and transfers ownership on success.

Parameters

sink	Borrowed task destination.
task	Task ownership reference offered to sink.

Returns

The sink submission status.

This validates the public protocol before entering the sink callback and never accesses task after an OK return because an inline sink may already have destroyed it.