callback_adapter.h File Reference

Go to the source code of this file.

Data Structures
struct	mln_adapter_resource_rewrite_rule
struct	mln_adapter_resource_rewrite_rules
struct	mln_adapter_resource_provider_rule
struct	mln_adapter_resource_provider_rules
struct	mln_adapter_queued_resource_provider_route
struct	mln_adapter_queued_resource_provider
struct	mln_adapter_queued_resource_request
struct	mln_adapter_log_callback_state
struct	mln_adapter_log_record

Macros
#define	MLN_ADAPTER_RESOURCE_KIND_ANY   UINT32_MAX

Typedefs
typedef void(*	mln_adapter_queued_resource_request_listener) (void *request)
typedef void(*	mln_adapter_log_record_listener) (void *record)

Functions
void *	mln_adapter_handle_leak_token_create (const char *type_name, void *handle)
void	mln_adapter_handle_leak_token_destroy (void *token)
void	mln_adapter_handle_leak_report (void *token)
uint32_t	mln_adapter_log_callback (void *user_data, uint32_t severity, uint32_t event, int64_t code, const char *message)
mln_status	mln_adapter_log_set_callback (mln_adapter_log_callback_state *state)
void	mln_adapter_log_record_destroy (void *record)
mln_status	mln_adapter_resource_transform_rewrite_callback (void *user_data, uint32_t kind, const char *url, mln_resource_transform_response *out_response)
uint32_t	mln_adapter_resource_provider_rules_callback (void *user_data, const mln_resource_request *request, mln_resource_request_handle *handle)
uint32_t	mln_adapter_queued_resource_provider_callback (void *user_data, const mln_resource_request *request, mln_resource_request_handle *handle)
void	mln_adapter_resource_provider_request_destroy (void *request)
void	mln_adapter_queued_resource_provider_retire (mln_adapter_queued_resource_provider *provider)
void	mln_adapter_custom_geometry_callbacks_retire (mln_custom_geometry_source_tile_callback fetch_tile, mln_custom_geometry_source_tile_callback cancel_tile, void *user_data)
uint64_t	mln_adapter_resource_request_token_create (mln_resource_request_handle *handle)
mln_status	mln_adapter_resource_request_token_cancelled (uint64_t token, bool *out_cancelled)
mln_status	mln_adapter_resource_request_token_complete (uint64_t token, const mln_resource_response *response)
mln_status	mln_adapter_resource_request_token_release (uint64_t token)
mln_status	mln_adapter_resource_request_token_wait (uint64_t token)

Detailed Description

Public C API declarations for adapting native callbacks to host runtimes that cannot run user code on a native callback thread.

MapLibre callback contracts are synchronous: logging and resource providers return an immediate decision, and borrowed request payloads expire when the callback returns. Some host runtimes cannot meet that contract. A host whose callbacks are delivered asynchronously and return void has no way to answer synchronously, and no way to read a payload that is already gone by the time its user code runs.

This layer answers on the host's behalf. It copies borrowed payloads into native-owned records the host releases explicitly, applies native-owned routing rules when a decision is needed immediately, and hands records to the host through void listener functions. Host user code therefore runs on its own execution context rather than on MapLibre worker, network, logging, or render threads.

A host that compiles its own native code writes this adaptation there instead, in whatever form its runtime prefers. This header serves hosts that consume the shared library through a pure foreign-function interface and have no native compilation unit of their own.

This header is not part of the maplibre_native_c.h umbrella. Include it directly when a binding needs it.

This header targets C23.

Macro Definition Documentation

MLN_ADAPTER_RESOURCE_KIND_ANY

#define MLN_ADAPTER_RESOURCE_KIND_ANY   UINT32_MAX

Rule kind that matches every resource kind.

Typedef Documentation

mln_adapter_log_record_listener

typedef void(* mln_adapter_log_record_listener) (void *record)

Receives a log record as a native-owned mln_adapter_log_record, or null when the callback retires.

The listener returns void and may be invoked from any MapLibre logging or worker thread. It takes ownership of the record and releases it with mln_adapter_log_record_destroy() once the host has read it.

mln_adapter_queued_resource_request_listener

typedef void(* mln_adapter_queued_resource_request_listener) (void *request)

Receives a queued request as a native-owned mln_adapter_queued_resource_request, or null when the provider retires.

The listener returns void and may be invoked from any MapLibre thread. It takes ownership of the record and releases it with mln_adapter_resource_provider_request_destroy() once the host has read it.

Function Documentation

mln_adapter_custom_geometry_callbacks_retire()

void mln_adapter_custom_geometry_callbacks_retire	(	mln_custom_geometry_source_tile_callback	fetch_tile,
		mln_custom_geometry_source_tile_callback	cancel_tile,
		void *	user_data )

Invokes custom geometry tile callbacks once with a retirement tile id.

The retirement tile id uses z = UINT8_MAX, which no real tile uses, so a host listener recognizes it and releases the state behind the callbacks.

mln_adapter_handle_leak_report()

void mln_adapter_handle_leak_report

(

void *

token

)

Reports a leaked handle on stderr and releases the token.

mln_adapter_handle_leak_token_create()

void * mln_adapter_handle_leak_token_create	(	const char *	type_name,
		void *	handle )

Creates a token describing a handle the host has not closed yet.

The token copies type_name and does not retain handle. Hosts attach the token to a finalizer so an unclosed handle can be reported from a context that can no longer touch the handle itself.

Returns null when the token cannot be allocated.

mln_adapter_handle_leak_token_destroy()

void mln_adapter_handle_leak_token_destroy

(

void *

token

)

Releases a leak token without reporting it.

mln_adapter_log_callback()

uint32_t mln_adapter_log_callback	(	void *	user_data,
		uint32_t	severity,
		uint32_t	event,
		int64_t	code,
		const char *	message )

The mln_log_callback implementation this layer registers.

Copies the record, hands it to the registered listener, and reports the registration's fixed consume value. The user_data pointer is the mln_adapter_log_callback_state passed to mln_adapter_log_set_callback().

mln_adapter_log_record_destroy()

void mln_adapter_log_record_destroy

(

void *

record

)

Releases a log record delivered to a listener.

mln_adapter_log_set_callback()

mln_status mln_adapter_log_set_callback

(

mln_adapter_log_callback_state *

state

)

Installs state as the process-global log callback, or clears the current callback when state is null.

A registration this call replaces receives one final null record through its listener once its in-flight dispatches finish.

Returns:

• MLN_STATUS_OK on success.
• The status reported by mln_log_set_callback() or mln_log_clear_callback().

mln_adapter_queued_resource_provider_callback()

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

The mln_resource_provider_callback implementation for queued providers.

The user_data pointer is an mln_adapter_queued_resource_provider. A request matching one of the provider's routes is copied and handed to the listener, and reports MLN_RESOURCE_PROVIDER_DECISION_HANDLE. Other requests pass through. A request that cannot be copied is completed with an error response rather than left outstanding.

mln_adapter_queued_resource_provider_retire()

void mln_adapter_queued_resource_provider_retire

(

mln_adapter_queued_resource_provider *

provider

)

Delivers one null record to a queued provider's listener.

Hosts call this after the provider is no longer registered so the listener can release the host-side state that backed it.

mln_adapter_resource_provider_request_destroy()

void mln_adapter_resource_provider_request_destroy

(

void *

request

)

Releases a queued request record delivered to a listener.

mln_adapter_resource_provider_rules_callback()

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

The mln_resource_provider_callback implementation for provider rules.

The user_data pointer is an mln_adapter_resource_provider_rules table. A matching request is completed inline with the rule's response and reports MLN_RESOURCE_PROVIDER_DECISION_HANDLE. Other requests pass through.

mln_adapter_resource_request_token_cancelled()

mln_status mln_adapter_resource_request_token_cancelled	(	uint64_t	token,
		bool *	out_cancelled )

Reports whether the request behind token was cancelled.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when the token is unknown or out_cancelled is null.
• The status reported by mln_resource_request_cancelled().

mln_adapter_resource_request_token_complete()

mln_status mln_adapter_resource_request_token_complete	(	uint64_t	token,
		const mln_resource_response *	response )

Completes the request behind token and retires the token.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when the token is unknown or response is null.
• The status reported by mln_resource_request_complete().

mln_adapter_resource_request_token_create()

uint64_t mln_adapter_resource_request_token_create

(

mln_resource_request_handle *

handle

)

Registers handle under an integer token the host carries across execution contexts.

The token owns the handle from this point: complete it with mln_adapter_resource_request_token_complete() or drop it with mln_adapter_resource_request_token_release(), and leave the handle itself alone.

Returns 0 when handle is null or the token cannot be recorded.

mln_adapter_resource_request_token_release()

mln_status mln_adapter_resource_request_token_release

(

uint64_t

token

)

Releases the request behind token without completing it, and retires the token.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when the token is unknown.

mln_adapter_resource_request_token_wait()

mln_status mln_adapter_resource_request_token_wait

(

uint64_t

token

)

Blocks until token is completed or released.

Hosts use this to drain outstanding requests during teardown. Call it from a context that is not responsible for completing the token.

Returns:

• MLN_STATUS_OK once the token is retired.
• MLN_STATUS_INVALID_ARGUMENT when token is 0.

mln_adapter_resource_transform_rewrite_callback()

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

The mln_resource_transform_callback implementation for rewrite rules.

The user_data pointer is an mln_adapter_resource_rewrite_rules table. The first matching rule replaces the URL, and a request that matches no rule passes through unchanged.