lib/thread.x

Context-backed native worker threads.

Primary API

Thread

Thread.free

void Thread.free(Thread thread)

Frees a Thread handle after its consuming join has completed.

Raises: <bad-state> for NULL, running, or joining handles.

Source: lib/thread.x:250

Thread.join

Var Thread.join(Thread t)

Joins one worker and exports its result into the joining Scope and pools. A failure during export still consumes the sealed worker storage. A native join failure leaves the Thread joinable for a retry. Concurrent joins are rejected while one is active; once native join succeeds, export cannot be retried.

Raises: <bad-arg> for a NULL handle, <bad-state> when another join is active or the worker was already joined, <io-fail> when the native join fails, any cause from result or error export, and <join-fail> carrying the worker’s exported errors. None of them return here. A callback that returns void joins as void; a handled worker failure transfers instead of returning a sentinel.

Source: lib/thread.x:222

Thread.start

Thread Thread.start(ThreadFn function, const void *input, size_t input_size)

Starts one worker and returns its heap-owned handle. input_size bytes are copied before native start and passed once to the callback. Pointees within those bytes remain shared and must outlive the worker. Copied storage has max_align_t alignment, so over-aligned input types are unsupported. An attempt that reaches pthread_create permanently enables canonical-pool locking; the first successful start also freezes Var descriptor registration.

Raises: <bad-arg> for a NULL function or missing nonempty input, <size-limit> when the handle size or shutdown-hook registry overflows, <alloc-fail> when the handle or shutdown hook cannot be allocated, or <io-fail> when pthread_create fails. Failure during native once initialization or mutex setup aborts the process.

Source: lib/thread.x:176

Public types

Thread

typedef struct Thread *Thread

A heap-owned native worker handle with one consuming join. A started Thread must be joined, including after its callback finishes, and then released with Thread.free.

Source: lib/thread.x:26

ThreadFn

typedef Var (*ThreadFn)(const void *input, size_t input_size)

Computes one Thread result from a borrowed copy of the start input bytes. The input is valid only during the call. The returned value is exported by Thread.join; an Error escaping the callback is reported as <join-fail>.

Source: lib/thread.x:20

Design notes

A Thread copies its fixed-size input with max_align_t alignment, runs one callback in an isolated Context, and seals the exported result or error snapshot until join. Over-aligned input types are not supported. Shared objects require their own coordination.

Tests and examples

make verify (unittest/test-thread.x).