delivery.h File Reference

Go to the source code of this file.

Data Structures
struct	mln_runtime_event_delivery
struct	mln_log_delivery
struct	mln_resource_request_delivery
struct	mln_resource_request_cancel_delivery
struct	mln_resource_transform_delivery
struct	mln_camera_transition_end_delivery
struct	mln_custom_source_tile_delivery
union	mln_delivery_payload
struct	mln_delivery
struct	mln_delivery_batch_view
struct	mln_delivery_queue_options

Typedefs
typedef enum mln_delivery_type	mln_delivery_type
typedef struct mln_runtime_event_delivery	mln_runtime_event_delivery
typedef struct mln_log_delivery	mln_log_delivery
typedef struct mln_resource_request_delivery	mln_resource_request_delivery
typedef struct mln_resource_request_cancel_delivery	mln_resource_request_cancel_delivery
typedef struct mln_resource_transform_delivery	mln_resource_transform_delivery
typedef struct mln_camera_transition_end_delivery	mln_camera_transition_end_delivery
typedef struct mln_custom_source_tile_delivery	mln_custom_source_tile_delivery
typedef union mln_delivery_payload	mln_delivery_payload
typedef struct mln_delivery	mln_delivery
typedef struct mln_delivery_batch_view	mln_delivery_batch_view
typedef struct mln_delivery_queue_options	mln_delivery_queue_options

Enumerations

enum

mln_delivery_type : uint32_t {   MLN_DELIVERY_TYPE_COMPLETION = 1 , MLN_DELIVERY_TYPE_LOG_RECORD = 2 , MLN_DELIVERY_TYPE_RESOURCE_REQUEST = 3 , MLN_DELIVERY_TYPE_RETIRED = 4 ,   MLN_DELIVERY_TYPE_RESOURCE_REQUEST_CANCEL = 5 , MLN_DELIVERY_TYPE_CAMERA_TRANSITION_END = 6 , MLN_DELIVERY_TYPE_CUSTOM_SOURCE_FETCH_TILE = 7 , MLN_DELIVERY_TYPE_CUSTOM_SOURCE_CANCEL_TILE = 8 ,   MLN_DELIVERY_TYPE_RUNTIME_EVENTS = 9 , MLN_DELIVERY_TYPE_RESOURCE_TRANSFORM = 10 }

Functions
mln_status	mln_delivery_queue_create (const mln_delivery_queue_options *options, mln_delivery_queue *out_queue, mln_diagnostic *out_diagnostic)
void	mln_delivery_queue_release (mln_delivery_queue queue)
mln_status	mln_delivery_queue_drain (mln_delivery_queue queue, mln_delivery_batch *out_batch, mln_delivery_batch_view *out_view, mln_diagnostic *out_diagnostic)
mln_status	mln_delivery_batch_take (mln_delivery_batch batch, size_t index, mln_diagnostic *out_diagnostic)
void	mln_delivery_batch_release (mln_delivery_batch batch)

Detailed Description

Public C API declarations for queue delivery of completions and host callbacks.

A host that cannot run code on a native thread, such as a Dart isolate or a JavaScript engine, sets a delivery queue on a registration in place of its callback. Native code then answers any synchronous decision itself, copies the payload into an item that the queue owns, and wakes the queue when it goes from empty to nonempty. The host drains owned batches on its own thread, takes the handles it keeps, and releases each batch.

Every registration whose callbacks a host need not answer on a native thread accepts a queue: mln_completion, mln_runtime_event_handler, mln_log_handler, mln_resource_provider, mln_resource_request_cancel_handler, mln_resource_transform, mln_camera_transition_handler, and the custom geometry and custom MVT vector source options.

A queue is FIFO in push order. A map command queues the runtime events it raises before pushing its completion. Events and completions that select the same queue arrive in that order. Adjacent events share one delivery.

A queue has no bound. A host that stops draining keeps every pushed item in memory until it drains or releases the queue.

Once process exit begins, pushes drop their items without disposing owned values, and wakes stop.

This header targets C23.

Typedef Documentation

mln_camera_transition_end_delivery

typedef struct mln_camera_transition_end_delivery mln_camera_transition_end_delivery

Copied mln_camera_transition_end_callback arguments.

mln_custom_source_tile_delivery

typedef struct mln_custom_source_tile_delivery mln_custom_source_tile_delivery

Copied mln_custom_source_fetch_tile_callback or mln_custom_source_cancel_tile_callback arguments.

mln_delivery

typedef struct mln_delivery mln_delivery

One drained delivery.

Step through deliveries by mln_delivery_batch_view.delivery_size.

mln_delivery_batch_view

typedef struct mln_delivery_batch_view mln_delivery_batch_view

A borrowed view of one owned delivery batch, which mln_delivery_queue_drain() writes.

Every pointer in the view, including those inside each delivery's payload, stays valid until the batch is released, independent of the queue, the runtime, and any map.

mln_delivery_payload

typedef union mln_delivery_payload mln_delivery_payload

Payload of one delivery, selected by mln_delivery.type.

mln_delivery_queue_options

typedef struct mln_delivery_queue_options mln_delivery_queue_options

Options for mln_delivery_queue_create(). All-zero members are defaults.

mln_delivery_type

typedef enum mln_delivery_type mln_delivery_type

The kind of one drained delivery.

mln_log_delivery

typedef struct mln_log_delivery mln_log_delivery

Copied mln_log_callback arguments; fields mirror the callback parameters.

mln_resource_request_cancel_delivery

typedef struct mln_resource_request_cancel_delivery mln_resource_request_cancel_delivery

Copied mln_resource_request_cancel_callback arguments.

mln_resource_request_delivery

typedef struct mln_resource_request_delivery mln_resource_request_delivery

Copied mln_resource_provider_callback arguments.

mln_resource_transform_delivery

typedef struct mln_resource_transform_delivery mln_resource_transform_delivery

Copied mln_resource_transform_callback arguments.

mln_runtime_event_delivery

typedef struct mln_runtime_event_delivery mln_runtime_event_delivery

Copied mln_runtime_event_callback arguments.

Enumeration Type Documentation

mln_delivery_type

enum mln_delivery_type : uint32_t

The kind of one drained delivery.

Enumerator
MLN_DELIVERY_TYPE_COMPLETION	The terminal result of a queue-mode mln_completion.
MLN_DELIVERY_TYPE_LOG_RECORD	One record for a queue-mode mln_log_handler.
MLN_DELIVERY_TYPE_RESOURCE_REQUEST	One request for a queue-mode mln_resource_provider.
MLN_DELIVERY_TYPE_RETIRED	Last delivery of a callback registration in queue mode; replaces release_user_data. No payload.
MLN_DELIVERY_TYPE_RESOURCE_REQUEST_CANCEL	One cancel for a queue-mode mln_resource_request_cancel_handler.
MLN_DELIVERY_TYPE_CAMERA_TRANSITION_END	The end for a queue-mode mln_camera_transition_handler.
MLN_DELIVERY_TYPE_CUSTOM_SOURCE_FETCH_TILE	One tile fetch for a queue-mode custom source.
MLN_DELIVERY_TYPE_CUSTOM_SOURCE_CANCEL_TILE	One tile cancel for a queue-mode custom source.
MLN_DELIVERY_TYPE_RUNTIME_EVENTS	Selected runtime and map events, in publication order.
MLN_DELIVERY_TYPE_RESOURCE_TRANSFORM	One request for a queue-mode mln_resource_transform.

Function Documentation

mln_delivery_batch_release()

void mln_delivery_batch_release

(

mln_delivery_batch

batch

)

Releases an owned delivery batch. A null handle is a no-op.

Owned values that the host did not take are disposed: a map without blocking, as mln_map_dispose() does, and a request handle through its release function: a provider request fails, and a transform request keeps its URL.

mln_delivery_batch_take()

mln_status mln_delivery_batch_take	(	mln_delivery_batch	batch,
		size_t	index,
		mln_diagnostic *	out_diagnostic )

Transfers the owned handles of one delivery to the caller.

An owned completion value, such as the mln_map from mln_runtime_create_map(), or a resource or transform request's handle becomes the caller's to release. A delivery that owns nothing is unchanged. The delivery's view stays readable.

Returns:

• MLN_STATUS_OK when the delivery's handles now belong to the caller, or the delivery owns none.
• MLN_STATUS_INVALID_ARGUMENT when batch is an invalid handle, or index is not less than the batch's delivery count.
• MLN_STATUS_INVALID_STATE when batch has been released, or the delivery was already taken.

mln_delivery_queue_create()

mln_status mln_delivery_queue_create	(	const mln_delivery_queue_options *	options,
		mln_delivery_queue *	out_queue,
		mln_diagnostic *	out_diagnostic )

Creates a delivery queue.

MLN_STATUS_OK transfers the wake's callback, user_data, and release_user_data to the queue. A rejected call leaves the wake's user_data with the caller. The output must point to the null handle and receives ownership of the queue on success.

Returns:

• MLN_STATUS_OK when out_queue receives an owned queue.
• MLN_STATUS_INVALID_ARGUMENT when options is null, options->size is too small, the wake descriptor is invalid, or out_queue is null or does not point to the null handle.
• MLN_STATUS_NATIVE_ERROR when the queue could not be allocated.

mln_delivery_queue_drain()

mln_status mln_delivery_queue_drain	(	mln_delivery_queue	queue,
		mln_delivery_batch *	out_batch,
		mln_delivery_batch_view *	out_view,
		mln_diagnostic *	out_diagnostic )

Moves every queued delivery into a new owned batch and borrows its view.

Deliveries that arrive later enter the next batch, and the wake fires again when the first of them arrives. This function may be called from any thread. Concurrent drains are serialized, and each delivery enters exactly one returned batch. Release each batch with mln_delivery_batch_release().

Returns:

• MLN_STATUS_OK when a batch holding at least one delivery is published in *out_batch and its view in *out_view.
• MLN_STATUS_NOT_READY when no delivery is queued. This is not an error: *out_batch and *out_view are left unchanged, and the caller drains again after the next wake.
• MLN_STATUS_INVALID_ARGUMENT when queue is an invalid handle, out_batch is null or does not point to the null handle, or out_view is null or out_view->size is too small.
• MLN_STATUS_INVALID_STATE when queue has been released.
• MLN_STATUS_NATIVE_ERROR when the batch could not be allocated. The deliveries stay queued in order, and the next push wakes the queue even though it is not empty. A host that cannot wait for that push drains again on its own schedule.

mln_delivery_queue_release()

void mln_delivery_queue_release

(

mln_delivery_queue

queue

)

Releases a delivery queue. A null handle is a no-op.

The call consumes the handle, closes the queue, and returns without blocking. It discards pending items: an untaken owned completion value is disposed, an untaken provider request is released, which fails it, and an untaken transform request is released, which keeps its URL.

Registrations that still name the queue keep working, but the queue refuses their later pushes: a completion is discarded and its owned value disposed, a log record goes to the platform logger, a provider request fails, a transform request keeps its URL, and other queued callbacks are dropped.

No wake call starts after release. The wake's release_user_data runs once in-flight wake calls return, on whichever thread finishes last. The host may release the queue from inside its own wake and from a finalizer. Batches already drained stay readable.