#include <completion.h>

Data Fields
mln_completion_callback	callback
void *	user_data
mln_user_data_release	release_user_data
mln_delivery_queue	queue

Detailed Description

Callback or queue state for one asynchronous submission.

The struct itself is borrowed for the submission call. A non-null completion sets exactly one of callback and queue. MLN_STATUS_OK transfers callback, user_data, and release_user_data to the C API. The completion runs exactly once and may run before the submission returns. The release callback runs after the completion returns. A non-OK submission invokes neither callback and leaves user_data owned by the caller.

A command, which the header marks MLN_BINDING("execution=command"), also accepts a null completion, which discards its outcome and runs no callback. The command otherwise behaves as it would with a completion. It returns the same status and diagnostic, runs in acceptance order, publishes its snapshot generation, and queues its events. A discarded command that fails logs its status and diagnostic as a warning through the log handler. Queries, operations, and lifecycle functions require a completion.

A later completion fences discarded commands. The completion of a later command or query on the same map follows every earlier discarded command, and a map snapshot read after it observes them. A render session barrier fences only the session's applied extent after a discarded resize; the resize completion fences both the session and the map. A snapshot generation alone does not, because other work also publishes generations.

The completion thread is unspecified and may be the submitting thread. It can differ from the thread that ran the command. The completion may call any-thread C APIs, but must return promptly and must not wait for runtime or graphics-driver work that can only progress on its current thread.

In queue mode, no callback runs. The terminal result reaches queue exactly once as an MLN_DELIVERY_TYPE_COMPLETION delivery, unless the host releases the queue before the result arrives, which discards it. See delivery.h. Where another function waits for a completion and its release to return, a queue-mode completion has returned once native has pushed its result and woken the queue, or has discarded the result because the queue was released or the process is exiting. Draining the queue is the host's step.

Field Documentation

◆ callback

mln_completion_callback mln_completion::callback

Receives the terminal result.

Required in callback mode; null in queue mode.

◆ queue

mln_delivery_queue mln_completion::queue

Optional. Queue delivery: the terminal result is copied into one MLN_DELIVERY_TYPE_COMPLETION delivery carrying user_data, and no callback runs. Requires callback and release_user_data null. The delivery may be queued before the submission returns. A rejected submission queues nothing and needs no cleanup. A submission rejects an invalid queue handle with MLN_STATUS_INVALID_ARGUMENT and a released queue with MLN_STATUS_INVALID_STATE.

◆ release_user_data

mln_user_data_release mln_completion::release_user_data

Optional. Releases user_data on the completing thread after the completion returns.

Null in queue mode.

◆ user_data

void* mln_completion::user_data

Opaque host token in queue mode; native code never dereferences or releases it. Keep token state until delivery is handled or the queue is abandoned.

The documentation for this struct was generated from the following file: