completion.h File Reference

Go to the source code of this file.

Data Structures
struct	mln_completion_result
struct	mln_completion

Typedefs
typedef enum mln_command_disposition	mln_command_disposition
typedef struct mln_completion_result	mln_completion_result
typedef void(*)	mln_completion_callback(void *user_data, const mln_completion_result *result)
typedef struct mln_completion	mln_completion

Enumerations
enum	mln_command_disposition : uint32_t

Detailed Description

Public C API declarations for one-shot asynchronous completion.

Typedef Documentation

mln_command_disposition

typedef enum mln_command_disposition mln_command_disposition

Terminal dispositions reported by command completions.

mln_completion

typedef struct mln_completion mln_completion

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.

mln_completion_callback

typedef void(*) mln_completion_callback(void *user_data, const mln_completion_result *result)

Receives one terminal result for an accepted asynchronous submission.

mln_completion_result

typedef struct mln_completion_result mln_completion_result

Borrowed terminal result for one accepted asynchronous submission.

The submitting function defines the type behind value and the meaning of value_count. A function with no result completes with value null and value_count zero, as does any failed completion. Every pointer remains valid only for the completion callback.

disposition and generation are meaningful for commands. Other one-shot functions set disposition to MLN_COMMAND_DISPOSITION_COMMITTED and generation to zero.

A map command delivers the runtime events it raises before its completion runs: a callback handler has returned from them, or a queue handler's queue holds them. Those events carry the generation this result reports.

Enumeration Type Documentation

mln_command_disposition

enum mln_command_disposition : uint32_t

Terminal dispositions reported by command completions.