base.h File Reference

Go to the source code of this file.

Data Structures
struct	mln_diagnostic
struct	mln_buffer_view

Macros
#define	MLN_DIAGNOSTIC_MESSAGE_CAPACITY   4096
#define	MLN_HANDLE_NULL   ((uint64_t)0)

Typedefs
typedef enum mln_status	mln_status
typedef struct mln_diagnostic	mln_diagnostic
typedef enum mln_render_backend_flag	mln_render_backend_flag
typedef uint64_t	mln_runtime
typedef uint64_t	mln_map
typedef uint64_t	mln_geojson_source_data
typedef uint64_t	mln_style_expression
typedef uint64_t	mln_map_projection
typedef uint64_t	mln_resource_request
typedef uint64_t	mln_resource_transform_request
typedef uint64_t	mln_render_session
typedef uint64_t	mln_acquired_frame
typedef uint64_t	mln_render_frame_batch
typedef uint64_t	mln_delivery_queue
typedef uint64_t	mln_delivery_batch
typedef struct mln_buffer_view	mln_buffer_view
typedef void(*)	mln_user_data_release(void *user_data)

Enumerations
enum	mln_status : int32_t { }
enum	mln_render_backend_flag : uint32_t

Functions
uint32_t	mln_c_version (void)
uint32_t	mln_supported_render_backend_mask (void)

Detailed Description

Public C API declarations for base ABI types, status values, and handles.

Handles are opaque 64-bit ids. Each handle remains distinguishable from every later handle after release. A release or disposal ends a handle once the call accepts it. Passing a released handle reports MLN_STATUS_INVALID_STATE. Passing an invalid handle, which is the null handle, a handle of another type, or a value this library never issued, reports MLN_STATUS_INVALID_ARGUMENT. Either way the call has no effect, and its diagnostic names the case. Handle values are safe to copy, compare, hash, and move between threads, and carry no ownership on their own.

Hosts pass handles back as issued, without decoding or synthesizing them.

Macro Definition Documentation

MLN_DIAGNOSTIC_MESSAGE_CAPACITY

#define MLN_DIAGNOSTIC_MESSAGE_CAPACITY   4096

Capacity of mln_diagnostic.message, including the terminating null byte.

MLN_HANDLE_NULL

#define MLN_HANDLE_NULL   ((uint64_t)0)

The null handle, for every handle type.

This value names no object of any type. Status-returning functions reject it. Void release functions accept it as a no-op. Output handle parameters that create or acquire ownership require *out_handle to equal it on entry.

Typedef Documentation

mln_acquired_frame

typedef uint64_t mln_acquired_frame

A rendered frame that a render session lends until its release.

mln_buffer_view

typedef struct mln_buffer_view mln_buffer_view

Borrowed data. The data pointer may be null only when size is zero.

Each parameter documents whether its view contains UTF-8 text, serialized data, or arbitrary bytes. The view carries no ownership and requires no trailing null byte.

mln_delivery_batch

typedef uint64_t mln_delivery_batch

An owned batch of deliveries from one drain.

mln_delivery_queue

typedef uint64_t mln_delivery_queue

A host-owned queue that holds deliveries until its host drains them.

mln_diagnostic

typedef struct mln_diagnostic mln_diagnostic

The diagnostic message of one status-returning call.

Every status-returning function takes a nullable mln_diagnostic* as its last parameter, out_diagnostic. The caller sets size to sizeof(mln_diagnostic). The function writes message as null-terminated UTF-8, truncated to fit. The message is empty when the function returns MLN_STATUS_OK or MLN_STATUS_NOT_READY, and describes the failure otherwise. It writes no more than size bytes of the struct. A null out_diagnostic discards the message.

Asynchronous failures carry their diagnostic in the completion instead.

mln_geojson_source_data

typedef uint64_t mln_geojson_source_data

Prepared GeoJSON data that sources retain independently of its handle.

mln_map

typedef uint64_t mln_map

A map, which holds map state independent of any render target.

mln_map_projection

typedef uint64_t mln_map_projection

A standalone projection of one map view.

mln_render_backend_flag

typedef enum mln_render_backend_flag mln_render_backend_flag

Render backend support flags reported by this native library build.

mln_render_frame_batch

typedef uint64_t mln_render_frame_batch

An owned batch of frame results from one drain.

mln_render_session

typedef uint64_t mln_render_session

A render session, which renders one map to one render target.

mln_resource_request

typedef uint64_t mln_resource_request

A resource request that a resource provider handles.

mln_resource_transform_request

typedef uint64_t mln_resource_transform_request

A resource URL transform that waits for its host's answer.

mln_runtime

typedef uint64_t mln_runtime

A runtime: the native scheduler thread and event store for its maps.

mln_status

typedef enum mln_status mln_status

Status values returned by status-returning functions.

A few host callbacks run while native code holds a lock that a call into this API can take again: the log handler's callback, queue wake, and release_user_data, and the callbacks of an mln_queue_lock. Inside those callbacks, every status-returning function returns MLN_STATUS_INVALID_STATE without running, and its diagnostic names the callback. Each other callback states which calls it may make.

mln_style_expression

typedef uint64_t mln_style_expression

A parsed style expression, immutable and independent of any map.

mln_user_data_release

typedef void(*) mln_user_data_release(void *user_data)

Releases the user_data of a callback registration.

Each registration struct's release_user_data member states when native code calls it and on which thread. A null release_user_data leaves user_data with the caller. Every callback the C API invokes returns normally, and must not throw, panic, longjmp, or otherwise unwind through the C API.

Enumeration Type Documentation

mln_render_backend_flag

enum mln_render_backend_flag : uint32_t

Render backend support flags reported by this native library build.

mln_status

enum mln_status : int32_t

Status values returned by status-returning functions.

A few host callbacks run while native code holds a lock that a call into this API can take again: the log handler's callback, queue wake, and release_user_data, and the callbacks of an mln_queue_lock. Inside those callbacks, every status-returning function returns MLN_STATUS_INVALID_STATE without running, and its diagnostic names the callback. Each other callback states which calls it may make.

Enumerator
MLN_STATUS_INVALID_ARGUMENT	A pointer, size field, mask, or handle argument was invalid.
MLN_STATUS_INVALID_STATE	The object is valid but not currently in a state that permits the call.
MLN_STATUS_WRONG_THREAD	The handle is thread-affine and the call came from the wrong thread.
MLN_STATUS_UNSUPPORTED	The entry point or requested behavior is unavailable in this build.
MLN_STATUS_NATIVE_ERROR	Native code failed; the diagnostic describes the error.
MLN_STATUS_CANCELLED	The operation reached its terminal cancelled disposition.
MLN_STATUS_BUSY	A conflicting driver call or lifecycle transition is in flight.
MLN_STATUS_TARGET_LOST	The render target or graphics receiver was irreversibly lost.
MLN_STATUS_NOT_READY	A nonblocking drain or acquisition has nothing to return yet.
MLN_STATUS_NOT_FOUND	A call named an ID with no live object behind it.

Function Documentation

mln_c_version()

uint32_t mln_c_version

(

void

)

Reports the C ABI contract version. The value is 0 while the ABI is unstable, and will increment on each SemVer major release.

mln_supported_render_backend_mask()

uint32_t mln_supported_render_backend_mask

(

void

)

Reports the render backends available in this native library build.

The return value is a mask of mln_render_backend_flag values.