runtime.h File Reference

Go to the source code of this file.

Data Structures
struct	mln_offline_region_status
struct	mln_rendering_stats
struct	mln_runtime_event_render_frame
struct	mln_runtime_event_render_map
struct	mln_runtime_event_style_image_missing
struct	mln_tile_id
struct	mln_runtime_event_tile_action
struct	mln_runtime_event_camera_transition_finished
struct	mln_runtime_event_offline_region_status
struct	mln_runtime_event_offline_region_response_error
struct	mln_runtime_event_offline_region_tile_count_limit
struct	mln_runtime_event_offline_operation_completed
struct	mln_runtime_event

Typedefs
typedef uint64_t	mln_offline_operation_id
typedef mln_status(*	mln_resource_transform_callback) (void *user_data, uint32_t kind, const char *url, mln_resource_transform_response *out_response)
typedef uint32_t(*	mln_resource_provider_callback) (void *user_data, const mln_resource_request *request, mln_resource_request_handle *handle)

Enumerations
enum	mln_offline_operation_kind : uint32_t
enum	mln_offline_operation_result_kind : uint32_t
enum	mln_runtime_event_type : uint32_t
enum	mln_runtime_event_source_type : uint32_t
enum	mln_runtime_event_payload_type : uint32_t
enum	mln_camera_change_mode : uint32_t { MLN_CAMERA_CHANGE_MODE_IMMEDIATE = 0 , MLN_CAMERA_CHANGE_MODE_ANIMATED = 1 }
enum	mln_render_mode : uint32_t
enum	mln_tile_operation : uint32_t

Functions
mln_status	mln_network_status_get (uint32_t *out_status)
mln_status	mln_network_status_set (uint32_t status)
mln_status	mln_resource_transform_response_set_url (mln_resource_transform_response *response, const char *url, size_t url_size)
mln_runtime_options	mln_runtime_options_default (void)
mln_status	mln_runtime_create (const mln_runtime_options *options, mln_runtime **out_runtime)
mln_status	mln_runtime_set_resource_provider (mln_runtime *runtime, const mln_resource_provider *provider)
mln_status	mln_runtime_clear_resource_provider (mln_runtime *runtime)
mln_status	mln_resource_request_complete (mln_resource_request_handle *handle, const mln_resource_response *response)
mln_status	mln_resource_request_cancelled (const mln_resource_request_handle *handle, bool *out_cancelled)
void	mln_resource_request_release (mln_resource_request_handle *handle)
mln_status	mln_runtime_set_resource_transform (mln_runtime *runtime, const mln_resource_transform *transform)
mln_status	mln_runtime_clear_resource_transform (mln_runtime *runtime)
mln_status	mln_runtime_run_ambient_cache_operation_start (mln_runtime *runtime, uint32_t operation, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_operation_discard (mln_runtime *runtime, mln_offline_operation_id operation_id)
mln_status	mln_runtime_destroy (mln_runtime *runtime)
mln_status	mln_runtime_pump (mln_runtime *runtime, int64_t timeout_ms)
mln_status	mln_runtime_wake_source_acquire (mln_runtime *runtime, mln_wake_source **out_source)
mln_status	mln_wake_source_signal (mln_wake_source *source)
void	mln_wake_source_destroy (mln_wake_source *source)
mln_status	mln_runtime_poll_event (mln_runtime *runtime, mln_runtime_event *out_event, bool *out_has_event)

Detailed Description

Public C API declarations for runtime, resources, and events.

Typedef Documentation

mln_offline_operation_id

typedef uint64_t mln_offline_operation_id

Offline database operation token. Zero is never a valid operation ID.

mln_resource_provider_callback

typedef uint32_t(* mln_resource_provider_callback) (void *user_data, const mln_resource_request *request, mln_resource_request_handle *handle)

Intercepts a network resource request.

The callback runs synchronously on the thread that reaches the C API network file source. That thread may be a MapLibre worker or network thread instead of the runtime owner thread.

Request handling follows these rules:

• request and its pointed-to fields are borrowed for the callback duration.
• MLN_RESOURCE_PROVIDER_DECISION_PASS_THROUGH lets native OnlineFileSource handle the request.
• After returning PASS_THROUGH, the provider must not retain, complete, or release the handle.
• MLN_RESOURCE_PROVIDER_DECISION_HANDLE lets the provider complete the request through the handle inline or later.
• A callback that returns HANDLE may release the handle during the callback. The C API defers that release until the callback returns.
• Unknown decision values produce a provider error response. The C API releases the provided handle and does not pass the request through.
• The C API copies completion data, and mln_resource_request_complete() may be called from any thread.
• Providers must release handled request handles after they no longer need to complete or observe cancellation.
• The callback must be thread-safe, return quickly, and must not call map or runtime C API functions.
• The callback may call resource request handle functions for the provided handle.

mln_resource_transform_callback

typedef mln_status(* mln_resource_transform_callback) (void *user_data, uint32_t kind, const char *url, mln_resource_transform_response *out_response)

Rewrites a network resource URL.

This callback can only replace the request URL. It cannot mutate headers, bodies, cache policy, or convert a request into an error.

Callback invocations follow these rules:

• MapLibre may invoke the callback on a worker or network thread instead of the runtime owner thread.
• The callback must be thread-safe, return quickly, and must not call C API functions other than mln_resource_transform_response_set_url().
• url and out_response are borrowed for the callback duration.
• Use mln_resource_transform_response_set_url() to set a replacement URL from temporary host-language storage. The helper copies the URL into C API-managed storage for the current transform invocation.
• A non-OK return status is treated as no rewrite and does not fail the resource request.
• The callback and user_data must remain valid until the transform is replaced, cleared, or the runtime is destroyed. Those calls wait for in-flight transform callbacks before returning.

Enumeration Type Documentation

mln_camera_change_mode

enum mln_camera_change_mode : uint32_t

Camera change kinds reported by camera will-change and did-change events.

Enumerator
MLN_CAMERA_CHANGE_MODE_IMMEDIATE	The camera reached its new value without an animated transition.
MLN_CAMERA_CHANGE_MODE_ANIMATED	The camera moved as part of an animated transition.

mln_offline_operation_kind

enum mln_offline_operation_kind : uint32_t

Offline database operation kinds reported by completion events.

mln_offline_operation_result_kind

enum mln_offline_operation_result_kind : uint32_t

Offline database operation result kinds reported by completion events.

mln_render_mode

enum mln_render_mode : uint32_t

Render modes reported by render observer events.

mln_runtime_event_payload_type

enum mln_runtime_event_payload_type : uint32_t

Payload kinds used by mln_runtime_event.payload_type.

mln_runtime_event_source_type

enum mln_runtime_event_source_type : uint32_t

Source kinds used by mln_runtime_event.source_type.

mln_runtime_event_type

enum mln_runtime_event_type : uint32_t

Runtime event types returned by mln_runtime_poll_event().

The event type selects the meaning of mln_runtime_event.code and the struct behind mln_runtime_event.payload. Event type names below omit their MLN_RUNTIME_EVENT_ prefix and payload type names omit their MLN_RUNTIME_EVENT_PAYLOAD_ prefix.

• MAP_CAMERA_WILL_CHANGE: code is an mln_camera_change_mode; payload NONE.
• MAP_CAMERA_IS_CHANGING: code is 0; payload NONE.
• MAP_CAMERA_DID_CHANGE: code is an mln_camera_change_mode; payload NONE.
• MAP_CAMERA_TRANSITION_FINISHED: code is 0; payload CAMERA_TRANSITION_FINISHED.
• MAP_STYLE_LOADED: code is 0; payload NONE.
• MAP_LOADING_STARTED: code is 0; payload NONE.
• MAP_LOADING_FINISHED: code is 0; payload NONE.
• MAP_LOADING_FAILED: code is the ordinal of MapLibre Native's internal map load error kind, which this API does not name as an enum, and is 0 when the failure came from a style-loading exception raised inside a C API call. Read message for the failure text in both cases; payload NONE.
• MAP_IDLE: code is 0; payload NONE.
• MAP_RENDER_UPDATE_AVAILABLE: code is 0; payload NONE.
• MAP_RENDER_ERROR: code is 0; message carries the error text; payload NONE.
• MAP_STILL_IMAGE_FINISHED: code is 0; payload NONE.
• MAP_STILL_IMAGE_FAILED: code is 0; message carries the error text; payload NONE.
• MAP_RENDER_FRAME_STARTED: code is 0; payload NONE.
• MAP_RENDER_FRAME_FINISHED: code is 0; payload RENDER_FRAME.
• MAP_RENDER_MAP_STARTED: code is 0; payload NONE.
• MAP_RENDER_MAP_FINISHED: code is 0; payload RENDER_MAP.
• MAP_STYLE_IMAGE_MISSING: code is 0; payload STYLE_IMAGE_MISSING.
• MAP_TILE_ACTION: code is 0; payload TILE_ACTION.
• OFFLINE_REGION_STATUS_CHANGED: code is 0; payload OFFLINE_REGION_STATUS.
• OFFLINE_REGION_RESPONSE_ERROR: code is 0; payload OFFLINE_REGION_RESPONSE_ERROR.
• OFFLINE_REGION_TILE_COUNT_LIMIT_EXCEEDED: code is 0; payload OFFLINE_REGION_TILE_COUNT_LIMIT.
• OFFLINE_OPERATION_COMPLETED: code is the operation result as an mln_status value, the same value the payload reports in result_status; payload OFFLINE_OPERATION_COMPLETED.

mln_tile_operation

enum mln_tile_operation : uint32_t

Tile operations reported by tile observer events.

Function Documentation

mln_network_status_get()

mln_status mln_network_status_get

(

uint32_t *

out_status

)

Reads MapLibre Native's process-global network status.

On success, out_status receives a mln_network_status value.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when out_status is null.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_network_status_set()

mln_status mln_network_status_set

(

uint32_t

status

)

Sets MapLibre Native's process-global network status.

MLN_NETWORK_STATUS_ONLINE allows HTTP and HTTPS requests and wakes native subscribers when transitioning from offline. MLN_NETWORK_STATUS_OFFLINE makes MapLibre's online source stop starting network requests until reachability returns. Runtime-scoped resource configuration is unchanged.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when status is not a mln_network_status value.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_resource_request_cancelled()

mln_status mln_resource_request_cancelled	(	const mln_resource_request_handle *	handle,
		bool *	out_cancelled )

Reports whether MapLibre has cancelled a C API resource provider request.

This function may be called from any thread while the provider still owns the handle. A cancelled request no longer wants a response; later completion is ignored with MLN_STATUS_INVALID_STATE.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when handle or out_cancelled is null.

mln_resource_request_complete()

mln_status mln_resource_request_complete	(	mln_resource_request_handle *	handle,
		const mln_resource_response *	response )

Completes a C API resource provider request.

This function may be called inline from the provider callback or later from any thread. The C API copies all response bytes and strings before returning.

Completion is one-shot. A second completion, completion after cancellation, or completion with null arguments returns a non-OK status and does not invoke MapLibre's resource callback. Malformed response contents are converted to provider error responses and still consume the completion.

Returns:

• MLN_STATUS_OK when the response was accepted for asynchronous delivery.
• MLN_STATUS_INVALID_ARGUMENT when handle or response is null.
• MLN_STATUS_INVALID_STATE when the request was cancelled, already completed, or can no longer accept a response.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_resource_request_release()

void mln_resource_request_release

(

mln_resource_request_handle *

handle

)

Releases the provider's reference to a resource request handle.

Release the handle exactly once after completing the request or deciding not to complete it. A provider callback that returns MLN_RESOURCE_PROVIDER_DECISION_HANDLE may release the handle inline; the C API defers reclamation until the callback returns. Passing null is a no-op. A released handle must not be used again.

mln_resource_transform_response_set_url()

mln_status mln_resource_transform_response_set_url	(	mln_resource_transform_response *	response,
		const char *	url,
		size_t	url_size )

Copies a replacement URL into C API-managed storage for the current callback.

Use this helper inside mln_resource_transform_callback implementations to set out_response->url from temporary host-language storage. The copied URL stays valid until the current resource transform invocation finishes. Empty input clears the replacement URL.

Returns MLN_STATUS_INVALID_ARGUMENT when response is null, response->size is too small, url is null with a non-zero size, or url contains embedded NUL. Returns MLN_STATUS_INVALID_STATE when called outside a resource transform callback.

mln_runtime_clear_resource_provider()

mln_status mln_runtime_clear_resource_provider

(

mln_runtime *

runtime

)

Clears the runtime-scoped network resource provider.

After this call succeeds, requests that reach the C API network file source go to MapLibre's online file source. When it returns, no in-flight request can still invoke the previous provider, and the C API holds no further reference to its callback or user_data. Requests the previous provider already took a handle for keep that handle: complete and release each one as usual.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_clear_resource_transform()

mln_status mln_runtime_clear_resource_transform

(

mln_runtime *

runtime

)

Clears the runtime-scoped URL transform for network resources.

After this call succeeds, network resource URLs pass through unchanged. When it returns, no in-flight request can still invoke the previous transform.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_create()

mln_status mln_runtime_create	(	const mln_runtime_options *	options,
		mln_runtime **	out_runtime )

Creates a runtime handle.

The creating thread becomes the runtime owner thread. Each owner thread may hold one live runtime.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when out_runtime is null, *out_runtime is not null, or options has an unsupported size or flags.
• MLN_STATUS_INVALID_STATE when the current thread already owns a live runtime.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_destroy()

mln_status mln_runtime_destroy

(

mln_runtime *

runtime

)

Destroys a runtime handle.

The runtime must no longer own live maps.

When a resource transform is registered, this call waits for in-flight transform callbacks before returning, the same way mln_runtime_set_resource_transform() and mln_runtime_clear_resource_transform() do. The callback contract documented on mln_resource_transform_callback keeps that wait short: the callback returns quickly and calls no C API function other than mln_resource_transform_response_set_url().

A registered resource provider is waited on the same way: this call blocks until every in-flight mln_resource_provider_callback invocation returns, matching mln_runtime_set_resource_provider() and mln_runtime_clear_resource_provider(). The callback and its user_data stay valid until that point and are unreferenced once this call returns, so a host frees provider-owned state only after it does.

Both waits run with no runtime-internal lock that other runtimes need, so a slow callback delays only this runtime. Do not call this while holding a host lock that a provider or transform callback also acquires; the callback cannot finish, and this call cannot return.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not a live runtime handle.
• MLN_STATUS_INVALID_STATE when runtime still owns live maps.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the creating thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_offline_operation_discard()

mln_status mln_runtime_offline_operation_discard	(	mln_runtime *	runtime,
		mln_offline_operation_id	operation_id )

Discards runtime-owned state for an offline database operation.

Discarding does not cancel native database work. It drops stored results, removes queued completion events for the operation, and suppresses later completion delivery when the native operation is still pending.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, or operation_id is zero or unknown.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_options_default()

mln_runtime_options mln_runtime_options_default

(

void

)

Returns runtime options initialized for this C API version.

mln_runtime_poll_event()

mln_status mln_runtime_poll_event	(	mln_runtime *	runtime,
		mln_runtime_event *	out_event,
		bool *	out_has_event )

Pops the next queued runtime event.

On success, *out_event is reset and *out_has_event indicates whether an event was available. When an event is available, *out_event receives it. Map-originated events set out_event->source_type to MLN_RUNTIME_EVENT_SOURCE_MAP and out_event->source to the source map. Runtime-originated events set out_event->source_type to MLN_RUNTIME_EVENT_SOURCE_RUNTIME.

When an event is available, out_event->payload points to runtime-owned storage containing a struct selected by out_event->payload_type, or null when the payload type is MLN_RUNTIME_EVENT_PAYLOAD_NONE. String pointers inside typed payloads and out_event->message remain valid until the next mln_runtime_poll_event() call for the same runtime or until the runtime is destroyed. Copy those bytes before then when they must outlive that window. For style-image-missing and tile-action events, out_event->message contains the same ID string exposed by the typed payload.

out_event->code carries a secondary detail whose meaning out_event->type selects. mln_runtime_event_type lists the meaning for every event type.

Destroying a map discards that map's queued events, so this function returns events only for maps that are still live. Read the state a host mirrors from events before destroying the map that produces them.

Returns:

• MLN_STATUS_OK when the poll completed; out_has_event indicates whether an event was written to out_event.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, out_event is null, out_has_event is null, or out_event->size is too small.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_pump()

mln_status mln_runtime_pump	(	mln_runtime *	runtime,
		int64_t	timeout_ms )

Advances this runtime.

The call parks the owner thread when timeout_ms allows it, then drains the owner-thread task queues. Drain the queued runtime events with mln_runtime_poll_event() afterwards.

timeout_ms sets the park bound:

• Zero drains and returns. Hosts pumping from a frame callback pass zero and take their cadence from that callback.
• A positive value parks for up to that many milliseconds, then drains. Hosts that own their pump thread pass a positive value and take their cadence from the runtime's own work.
• A negative value parks until a wake arrives, then drains.

The drain runs every task queued when it begins plus every task those tasks enqueue, and services expired timers and ready file descriptors for the runtime's own network and database work. Its duration follows the work it finds and can span a full style parse, so treat it as work that runs to completion rather than as a fixed-cost per-frame slice.

The runtime holds a wake flag. These set it:

• the owner-thread run loop receiving queued work from any thread, which covers style, tile, offline database, and resource responses;
• the runtime queueing a runtime event;
• mln_wake_source_signal() from any thread.

A parking call returns as soon as the flag is set, and clears the flag before it returns. Work that arrives during the drain sets the flag again, so the next call returns right away and may find that work already done.

A call also returns without parking while unread runtime events are queued.

Timers and file descriptors set the flag only when they queue owner-thread work, and the runtime registers none of its own on the owner-thread run loop. Pass a positive timeout_ms so a call returns even when nothing sets the flag.

A non-zero timeout_ms makes this a blocking query. Call it outside any host lock that a thread signalling a wake source acquires, and outside C API callbacks. Acquire a wake source with mln_runtime_wake_source_acquire() to release the owner thread for host-driven work such as submitted tasks or shutdown.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not a live runtime handle.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_run_ambient_cache_operation_start()

mln_status mln_runtime_run_ambient_cache_operation_start	(	mln_runtime *	runtime,
		uint32_t	operation,
		mln_offline_operation_id *	out_operation_id )

Starts a MapLibre ambient cache maintenance operation for this runtime.

When runtime options omit cache_path, this operates on MapLibre's default in-memory database and its effects are not durable beyond the native database lifetime. Completion is reported through MLN_RUNTIME_EVENT_OFFLINE_OPERATION_COMPLETED.

Returns:

• MLN_STATUS_OK when the operation was accepted and out_operation_id was set.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, or operation is not a mln_ambient_cache_operation value, or out_operation_id is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_set_resource_provider()

mln_status mln_runtime_set_resource_provider	(	mln_runtime *	runtime,
		const mln_resource_provider *	provider )

Registers or replaces a runtime-scoped network resource provider.

It is invoked for requests that reach the C API network file source. Built-in non-network schemes such as file, asset, mbtiles, and pmtiles are handled by native MainResourceLoader before this extension point.

This call may replace an existing provider while maps exist. The callback and user_data are stored by reference and must remain valid until this call returns having replaced them, mln_runtime_clear_resource_provider() returns, or the runtime is destroyed. When this call returns, no in-flight request can still invoke the previous provider. Requests the previous provider already took a handle for keep that handle: complete and release each one as usual. Native OnlineFileSource claims every remaining scheme, so a URL with a scheme MapLibre does not recognize, such as jar:file:, is treated as a network request, reaches this callback, and completes as an HTTP error when the provider passes it through. Hosts use this extension point to serve those schemes from host storage.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, provider is null, provider->size is too small, or callback is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_set_resource_transform()

mln_status mln_runtime_set_resource_transform	(	mln_runtime *	runtime,
		const mln_resource_transform *	transform )

Registers or updates a runtime-scoped URL transform for network resources.

It is forwarded to MapLibre's OnlineFileSource, so it applies wherever native OnlineFileSource applies transforms, including nested PMTiles network range requests. It does not apply to file, asset, database, MBTiles, or registered C API provider responses intercepted before OnlineFileSource.

This call may replace an existing transform while maps exist. When it returns, no in-flight request can still invoke the previous transform.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, transform is null, transform->size is too small, or callback is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_wake_source_acquire()

mln_status mln_runtime_wake_source_acquire	(	mln_runtime *	runtime,
		mln_wake_source **	out_source )

Acquires a wake source that releases this runtime's parked owner thread.

Each call returns a distinct handle the host destroys with mln_wake_source_destroy(). A wake source holds its own reference to the runtime's wake state, so it stays valid after the runtime is destroyed and hosts tear the two down in either order.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not a live runtime handle, out_source is null, or *out_source is not null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_wake_source_destroy()

void mln_wake_source_destroy

(

mln_wake_source *

source

)

Destroys a wake source.

This function may be called from any thread. Null is a no-op. Destroy each handle exactly once, once every thread that signals it has finished.

mln_wake_source_signal()

mln_status mln_wake_source_signal

(

mln_wake_source *

source

)

Sets the runtime's wake flag and releases the parked owner thread.

This function may be called from any thread. It takes one small lock and returns, so a host calls it from its task submission path.

A signal raised while the owner thread is running sets the wake flag, so the next mln_runtime_pump() call returns without parking. Signalling a wake source whose runtime is destroyed succeeds and does nothing, so hosts shut the two down in either order.

Returns:

• MLN_STATUS_OK on success, including after the runtime is destroyed.
• MLN_STATUS_INVALID_ARGUMENT when source is null.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.