Struct RuntimeHandle 

pub struct RuntimeHandle { /* private fields */ }

Owner-thread runtime handle for MapLibre Native work and event polling.

Implementations

impl RuntimeHandle

pub fn with_options(options: &RuntimeOptions) -> Result<Self>

Creates a runtime on the current thread using explicit options.

pub fn set_resource_provider<F>(&self, callback: F) -> Result<()>

where F: Fn(ResourceRequest, ResourceRequestHandle) -> ResourceProviderDecision + Send + Sync + 'static,

Installs or replaces the runtime-scoped network resource provider.

The provider may be installed or replaced before or after creating maps from this runtime. Native code may invoke it from worker or network threads, so the closure must be thread-safe and 'static. Keep the closure quick, and do not call map or runtime APIs from it. Return PassThrough to let native networking handle the request. Return Handle to complete or release the provided ResourceRequestHandle inline or later. If the callback completes the handle inline, the wrapper returns native Handle even when the closure returns PassThrough, preventing native double handling.

A successful replacement retires the previous provider before returning, so this method releases the previous closure’s Rust state once native can no longer invoke it. Requests the previous provider already took a ResourceRequestHandle for keep that handle; complete and release each one as usual.

pub fn clear_resource_provider(&self) -> Result<()>

Clears the runtime-scoped network resource provider.

Clearing may happen before or after creating maps from this runtime. Requests that reach the C API network file source then go to MapLibre’s online file source. Native clear waits for in-flight provider callbacks before returning, so this method releases Rust callback state after a successful clear. Requests the provider already took a ResourceRequestHandle for keep that handle; complete and release each one as usual.

pub fn set_resource_transform<F>(&self, callback: F) -> Result<()>

where F: Fn(ResourceTransformRequest) -> Option<String> + Send + Sync + 'static,

Installs or replaces the runtime-scoped network URL transform.

The transform may be installed before or after creating maps from this runtime. Native code may invoke it from worker or network threads, so the closure must be thread-safe and 'static. Keep the closure quick, and do not call MapLibre Native APIs from it. Returning Some(url) replaces the request URL; returning None or an empty string keeps the original URL. Panics are contained and treated by native code as no rewrite.

pub fn clear_resource_transform(&self) -> Result<()>

Clears the runtime-scoped network URL transform.

Clearing may happen before or after creating maps from this runtime. Native clear waits for in-flight transform callbacks before returning, so this method can release Rust callback state after a successful clear.

pub fn start_ambient_cache_operation( &self, operation: AmbientCacheOperation, ) -> Result<OfflineOperationHandle<()>>

Starts an ambient cache maintenance operation for this runtime.

pub fn start_create_offline_region( &self, definition: &OfflineRegionDefinition, metadata: &[u8], ) -> Result<OfflineOperationHandle<OfflineRegionInfo>>

Starts creating an offline region.

pub fn start_offline_region( &self, region_id: i64, ) -> Result<OfflineOperationHandle<Option<OfflineRegionInfo>>>

Starts getting an offline region snapshot by ID.

pub fn start_offline_regions( &self, ) -> Result<OfflineOperationHandle<Vec<OfflineRegionInfo>>>

Starts listing offline regions in this runtime’s database.

pub fn start_merge_offline_regions_database( &self, path: &str, ) -> Result<OfflineOperationHandle<Vec<OfflineRegionInfo>>>

Starts merging offline regions from another database path.

pub fn start_update_offline_region_metadata( &self, region_id: i64, metadata: &[u8], ) -> Result<OfflineOperationHandle<OfflineRegionInfo>>

Starts updating opaque metadata for an offline region.

pub fn start_offline_region_status( &self, region_id: i64, ) -> Result<OfflineOperationHandle<OfflineRegionStatus>>

Starts getting the current completed/download status for an offline region.

pub fn start_set_offline_region_observed( &self, region_id: i64, observed: bool, ) -> Result<OfflineOperationHandle<()>>

Starts enabling or disabling runtime events for an offline region.

pub fn start_set_offline_region_download_state( &self, region_id: i64, state: OfflineRegionDownloadState, ) -> Result<OfflineOperationHandle<()>>

Starts setting an offline region’s native download state.

pub fn start_invalidate_offline_region( &self, region_id: i64, ) -> Result<OfflineOperationHandle<()>>

Starts invalidating cached resources for an offline region.

pub fn start_delete_offline_region( &self, region_id: i64, ) -> Result<OfflineOperationHandle<()>>

Starts deleting an offline region.

pub fn pump(&self, timeout: Option<Duration>) -> Result<()>

Advances this runtime.

The call parks the owner thread when timeout allows it, then drains the owner-thread task queues. Drain the queued runtime events with Self::poll_event afterwards.

timeout sets the park bound. Some(Duration::ZERO) drains and returns; hosts pumping from a frame callback pass it. A longer Some parks for up to that long; hosts that own their pump thread pass one and take their cadence from the runtime’s own work. None parks until a wake arrives.

The drain runs every task queued when it begins plus every task those enqueue, so a single call can span a full style parse.

The runtime holds a wake flag. Style, tile, offline, and resource responses set it, as do queued runtime events and WakeSource::signal. A parking call returns as soon as the flag is set and clears it before returning, and work arriving during the drain sets it again. A call also returns without parking while unread runtime events are queued. Timers and ready file descriptors set the flag only when they queue owner-thread work, so pass a bounded timeout to cap how long a call waits.

A non-zero timeout blocks the calling thread. Call it outside any lock that a thread signalling a WakeSource takes, and outside native callbacks.

pub fn wake_source(&self) -> Result<WakeSource>

Acquires a WakeSource that releases this runtime’s parked owner thread. The returned source is usable from any thread.

pub fn poll_event(&self) -> Result<Option<RuntimeEvent>>

Polls one queued runtime event and copies it into an owned Rust value.

Polling also advances binding-owned state that the event reports. A polled crate::RuntimeEventType::MapStyleLoaded event releases the upcall state of custom geometry sources the newly loaded style dropped, so keep polling to completion to let that state be reclaimed; a map whose events go unpolled keeps those sources’ callback state alive.

pub fn close(self) -> Result<(), HandleOperationError<Self>>

Explicitly destroys the runtime.

Native destruction errors are returned. When destruction fails, the underlying native handle remains live in the shared state so child handles that retain the runtime can still close safely.

Trait Implementations

impl Debug for RuntimeHandle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.