Future API

Awaitable results for task completion.

Types

typedef struct fq_future_t fq_future_t;

Functions

Creation

fq_status_t fq_future_create(fq_future_t **future, const fq_allocator_t *allocator);
void fq_future_destroy(fq_future_t *future);

Waiting

fq_status_t fq_future_wait(fq_future_t *future);

Block until the future is ready. Returns the status of the completed operation.

fq_status_t fq_future_wait_timeout(fq_future_t *future, unsigned timeout_ms, fq_status_t *status);

Block with timeout. The status pointer receives the result status (may be NULL). Returns FQ_OK on success, FQ_ERR_TIMEOUT on timeout.

fq_bool_t fq_future_is_ready(const fq_future_t *future);

Non-blocking check if ready.

fq_bool_t fq_future_is_canceled(const fq_future_t *future);

Check whether the future was canceled.

Status

fq_status_t fq_future_status(const fq_future_t *future);

Get the task's execution status. Returns FQ_ERR_BUSY if still pending.

Callbacks

fq_status_t fq_future_on_complete(fq_future_t *future, fq_completion_fn callback, void *user_data);

Attach a completion callback. If the future is already fulfilled, the callback is invoked immediately on the calling thread.

Cancellation

fq_status_t fq_future_cancel(fq_future_t *future);

Cancel a pending future. The completion callback (if any) is invoked with FQ_ERR_CANCELED. Returns FQ_OK on success, FQ_ERR_CLOSED if already fulfilled.

Promise (Internal)

void fq_future_set_result(fq_future_t *future, fq_status_t status);

Fulfill a future with a result status. Called internally by the scheduler.