logging.h File Reference

Go to the source code of this file.

Data Structures
struct	mln_log_handler

Typedefs
typedef enum mln_log_severity	mln_log_severity
typedef enum mln_log_severity_mask	mln_log_severity_mask
typedef enum mln_log_event	mln_log_event
typedef uint32_t(*)	mln_log_callback(void *user_data, uint32_t severity, uint32_t event, int64_t code, const char *message)
typedef struct mln_log_handler	mln_log_handler

Enumerations
enum	mln_log_severity : uint32_t
enum	mln_log_severity_mask : uint32_t
enum	mln_log_event : uint32_t

Functions
mln_status	mln_log_set_callback (const mln_log_handler *handler, mln_diagnostic *out_diagnostic)
mln_status	mln_log_clear_callback (mln_diagnostic *out_diagnostic)
mln_status	mln_log_set_async_severity_mask (uint32_t mask, mln_diagnostic *out_diagnostic)

Detailed Description

Public C API declarations for logging.

Typedef Documentation

mln_log_callback

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

Receives a MapLibre Native log record.

The message pointer is borrowed for the callback duration. Returning non-zero consumes the record. Returning zero lets MapLibre Native's platform logger handle it.

A handler in queue mode consumes each record without a callback and queues a copy as an mln_log_delivery.

mln_log_event

typedef enum mln_log_event mln_log_event

Log event categories emitted by MapLibre Native.

mln_log_handler

typedef struct mln_log_handler mln_log_handler

Process-global log callback or queue state.

The struct itself is borrowed for mln_log_set_callback(). Exactly one of callback and queue is set.

mln_log_severity

typedef enum mln_log_severity mln_log_severity

Log severity values emitted by MapLibre Native.

mln_log_severity_mask

typedef enum mln_log_severity_mask mln_log_severity_mask

Bitmask values for log severities dispatched asynchronously.

Enumeration Type Documentation

mln_log_event

enum mln_log_event : uint32_t

Log event categories emitted by MapLibre Native.

mln_log_severity

enum mln_log_severity : uint32_t

Log severity values emitted by MapLibre Native.

mln_log_severity_mask

enum mln_log_severity_mask : uint32_t

Bitmask values for log severities dispatched asynchronously.

Function Documentation

mln_log_clear_callback()

mln_status mln_log_clear_callback

(

mln_diagnostic *

out_diagnostic

)

Clears the process-global log callback.

The C API invokes the cleared handler's release_user_data, if any, or queues its MLN_DELIVERY_TYPE_RETIRED delivery, before returning.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_NATIVE_ERROR when native code fails.

mln_log_set_async_severity_mask()

mln_status mln_log_set_async_severity_mask	(	uint32_t	mask,
		mln_diagnostic *	out_diagnostic )

Controls which log severities MapLibre Native may dispatch asynchronously.

MLN_LOG_SEVERITY_MASK_DEFAULT lets info and warning records dispatch asynchronously and keeps error records synchronous.

A severity outside the mask invokes the log callback synchronously on the thread that emits the record, before the logging call returns.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when mask contains unknown bits.
• MLN_STATUS_NATIVE_ERROR when native code fails.

mln_log_set_callback()

mln_status mln_log_set_callback	(	const mln_log_handler *	handler,
		mln_diagnostic *	out_diagnostic )

Installs a process-global MapLibre Native log callback.

MLN_STATUS_OK replaces the current handler and transfers the handler's callback, user_data, and release_user_data to the C API. The handler struct itself is borrowed for the call. With a null release_user_data, the caller keeps responsibility for user_data and must keep it valid until the handler is replaced or cleared. A rejected call leaves the current handler in place and invokes no release. mln_log_clear_callback() clears the handler.

The callback may run on any thread, according to the async severity mask. It must be thread-safe, return promptly, and not call this C API: each status-returning function returns MLN_STATUS_INVALID_STATE when the callback calls it.

In queue mode the handler's records reach the queue and its wake runs inline on the logging thread. The wake follows the same restrictions.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when handler is null, handler->size is too small, neither or both of callback and queue are set, release_user_data is set in queue mode, or queue is an invalid handle.
• MLN_STATUS_INVALID_STATE when queue has been released.
• MLN_STATUS_NATIVE_ERROR when native code fails.