Struct RuntimeHandle 

pub struct RuntimeHandle { /* private fields */ }

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

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.

Native may invoke the closure from worker or network threads, so keep it quick and call no map or runtime APIs from it. Return PassThrough to let native networking handle the request, or Handle to complete or release the provided ResourceRequestHandle inline or later.

A successful replacement retires the previous provider before returning and then releases its Rust state. Handles the previous provider already took stay valid; complete and release each one as usual.

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

Clears the runtime-scoped network resource provider, sending later requests to MapLibre’s online file source. The clear waits for in-flight provider callbacks before returning and then releases the Rust callback state. Handles the provider already took stay valid.

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.

Native may invoke the closure from worker or network threads, so keep it quick and call no MapLibre Native APIs from it. Some(url) replaces the request URL; None, an empty string, or a panic keeps the original.

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

Clears the runtime-scoped network URL transform. The clear waits for in-flight transform callbacks before returning and then releases the Rust callback state.

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

where F: Fn(HttpHeaderTransformRequest) -> Vec<HttpHeader> + Send + Sync + 'static,

Installs or replaces the runtime-scoped outgoing HTTP header transform.

Native invokes the closure synchronously on worker or network threads after URL transformation. Returned headers are copied before the closure returns. Panics, duplicate names, and invalid headers leave the request unchanged.

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

Clears the runtime-scoped outgoing HTTP header transform.

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

Starts an ambient cache maintenance operation for this runtime.

pub fn start_set_maximum_ambient_cache_size( &self, size: u64, ) -> Result<OfflineOperationHandle<()>>

Starts a change to this runtime’s maximum ambient cache size.

MapLibre evicts ambient resources to fit the new budget, so lowering it discards cached resources. Offline regions are unaffected.

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>, budget: Option<Duration>, ) -> Result<()>

Advances this runtime: parks the owner thread when timeout allows it, then drains the owner-thread task queues. Drain the queued runtime events with Self::drain_events afterwards.

Some(Duration::ZERO) drains and returns, a longer Some parks for up to that long, and 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.

budget bounds the drain. None drains without a bound; a Some value stops the drain at the first task boundary after that long, measured from the start of the drain. The first queued task always runs, so a bounded pump always makes progress, and tasks left behind set the wake flag so the next pump returns without parking and continues them. The budget bounds the task queues alone: expired timers and ready file descriptors are serviced regardless, and a single task runs to completion once started, so one long task can overrun the budget.

A parking call returns as soon as the runtime’s wake flag is set, and 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 drain_events( &mut self, max_events: usize, ) -> Result<RuntimeEventBatch<'_>>

Drains this runtime’s queued events into one batch borrowed from runtime-owned storage.

max_events bounds the drain. Zero drains every queued event, and a positive value drains at most that many and reports the rest through RuntimeEventBatch::remaining.

The returned batch borrows this handle, so the next drain waits until the batch is dropped, and an event read out of the batch borrows the batch. Take crate::RuntimeEventRef::to_owned for a value that outlives either.

A drain invalidates the batch before it, which the mutable borrow turns into a compile error:

let mut runtime = RuntimeHandle::with_options(&RuntimeOptions::default()).unwrap();
let batch = runtime.drain_events(0).unwrap();
let next = runtime.drain_events(0).unwrap();
let _ = batch.len();

pub fn set_event_mask(&self, mask: RuntimeEventMask) -> Result<()>

Selects which runtime-originated event types this runtime queues.

A runtime reads the bits in RuntimeEventMask::ALL_RUNTIME_EVENTS, so RuntimeEventMask::ALL selects every runtime-originated type. Narrowing gates later events and keeps queued ones. A bit outside ALL is an invalid-argument error.

pub fn event_mask(&self) -> Result<RuntimeEventMask>

Reports which runtime-originated event types this runtime queues, starting from the mask its creation options selected.

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

Explicitly destroys the runtime. A failed destroy leaves the native handle live so child handles can still close safely.

Trait Implementations

impl Debug for RuntimeHandle

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

Formats the value using the given formatter.