Struct RuntimeHandle 

pub struct RuntimeHandle { /* private fields */ }

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

Implementations

impl RuntimeHandle

pub fn new() -> Result<Self>

Creates a runtime on the current thread using native default options.

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

Creates a runtime on the current thread using explicit options.

pub fn create_map(&self) -> Result<MapHandle>

Creates a map owned by this runtime with native default map options.

pub fn create_map_with_options(&self, options: &MapOptions) -> Result<MapHandle>

Creates a map owned by this runtime with explicit map 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 must be installed before 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.

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 run_once(&self) -> Result<()>

Runs one pending owner-thread task for this runtime.

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

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

pub fn discard_one_event(&self) -> Result<bool>

Polls and discards one queued runtime event, returning whether one was present.

pub fn drain_events(&self) -> Result<usize>

Polls and discards queued runtime events until the queue is empty.

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.