workspace.h File Reference

Per-worker scratch workspace. More...

Go to the source code of this file.

Data Structures
struct	loomc_workspace_options_t
	Workspace creation options. More...
struct	loomc_workspace_statistics_t
	Monotonic allocation statistics for a workspace block pool. More...

Typedefs
typedef struct loomc_workspace_t	loomc_workspace_t
	Mutable per-worker scratch workspace.

Functions
loomc_status_t	loomc_workspace_create (const loomc_workspace_options_t *options, loomc_allocator_t allocator, loomc_workspace_t **out_workspace)
	Creates a mutable workspace for one worker at a time.
void	loomc_workspace_query_statistics (const loomc_workspace_t *workspace, loomc_workspace_statistics_t *out_statistics)
	Queries a monotonic snapshot of workspace allocation statistics.
void	loomc_workspace_retain (loomc_workspace_t *workspace)
	Retains workspace for another owner.
void	loomc_workspace_trim (loomc_workspace_t *workspace)
	Trims idle arena blocks owned by workspace.
void	loomc_workspace_release (loomc_workspace_t *workspace)
	Releases workspace and all storage it owns.

Detailed Description

Per-worker scratch workspace.

A workspace owns the arena block pool used by parsing, indexing, linking, cloning, and compiling. High-throughput embedders normally create one workspace per worker thread or task-system worker and reuse it across operations.

Example

Keep a workspace thread-local and reuse it across independent operations:

loomc_workspace_t* workspace = NULL;
loomc_status_t status =
    loomc_workspace_create(NULL, loomc_allocator_system(), &workspace);
if (!loomc_status_is_ok(status)) {
  return status;
}
 
for (size_t i = 0; i < kernel_count; ++i) {
  // Pass workspace to deserialize, link, compile, or emit invocations for
  // this kernel. Releasing modules returns their arena blocks to the
  // workspace for reuse by later operations.
}
 
// Optionally return idle blocks to the host allocator under memory
// pressure or before entering a long idle period.
loomc_workspace_trim(workspace);
 
loomc_workspace_release(workspace);

Typedef Documentation

loomc_workspace_t

typedef struct loomc_workspace_t loomc_workspace_t

Mutable per-worker scratch workspace.

Thread safety

A workspace is not internally synchronized. Calls that mutate the same workspace require external synchronization. Distinct workspaces may be used concurrently by different threads.

Function Documentation

loomc_workspace_create()

loomc_status_t loomc_workspace_create	(	const loomc_workspace_options_t *	options,
		loomc_allocator_t	allocator,
		loomc_workspace_t **	out_workspace )

Creates a mutable workspace for one worker at a time.

Parameters

options	Workspace allocation options, or NULL for defaults.
allocator	Host allocator used for workspace-owned storage.
out_workspace	Receives the created workspace on success.

Returns

OK when the workspace was created.

Ownership

The caller owns the returned workspace and releases it with loomc_workspace_release.

Lifetime

Sources, retained results, frozen link indexes, prepared linkers, and prepared compilers do not use workspace arena storage unless an operation descriptor explicitly says so. Modules created, linked, cloned, or deserialized with a workspace retain that workspace and return their arena blocks when released.

Thread safety

The returned workspace is mutable scratch and is intended for one worker at a time.

loomc_workspace_query_statistics()

void loomc_workspace_query_statistics	(	const loomc_workspace_t *	workspace,
		loomc_workspace_statistics_t *	out_statistics )

Queries a monotonic snapshot of workspace allocation statistics.

Parameters

workspace	Workspace to inspect. Passing NULL returns zeroed statistics.
out_statistics	Receives the snapshot. Passing NULL is allowed.

Thread safety

This query is safe while other threads use the workspace. Fields may be sampled at adjacent instants and are exact when the workspace is quiescent. Allocation counters are zero when statistics are disabled at build time.

loomc_workspace_release()

void loomc_workspace_release

(

loomc_workspace_t *

workspace

)

Releases workspace and all storage it owns.

Parameters

workspace

Workspace to release. Passing NULL is allowed.

Thread safety

Retain/release operations are safe from multiple threads. The workspace is destroyed when the final reference is released; no thread may be mutating it at that moment.

loomc_workspace_retain()

void loomc_workspace_retain

(

loomc_workspace_t *

workspace

)

Retains workspace for another owner.

Parameters

workspace

Workspace to retain. Passing NULL is allowed.

Thread safety

Retain/release operations are safe from multiple threads.

loomc_workspace_trim()

void loomc_workspace_trim

(

loomc_workspace_t *

workspace

)

Trims idle arena blocks owned by workspace.

Parameters

workspace

Workspace to trim.

Lifetime

Trim returns blocks that are already idle in the workspace block pool to the host allocator. Retained modules created from this workspace remain valid across trim, but their active arena blocks cannot be reused until those modules are released. Results, sources, frozen indexes, and prepared tools remain valid.

Thread safety

External synchronization is required if another thread may be using the same workspace.