Struct RuntimeHandle 

pub struct RuntimeHandle { /* private fields */ }

Owns one native handle.

A runtime owns maps and the network and cache settings that they share.

See mln_runtime in the C API reference.

Implementations

impl RuntimeHandle

pub fn id(&self) -> u64

Returns the native handle value, which runtime events report as their source.

impl RuntimeHandle

pub fn clear_event_handler(&self) -> Result<NativeFuture<CommandCompletion>>

Stops sending the events of the runtime and its maps to a callback.

See mln_runtime_clear_event_handler in the C API reference.

pub fn clear_http_header_transform( &self, ) -> Result<NativeFuture<CommandCompletion>>

Stops adding headers to the runtime’s HTTP requests.

See mln_runtime_clear_http_header_transform in the C API reference.

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

Removes the runtime’s resource provider, so the library loads every request itself.

See mln_runtime_clear_resource_provider in the C API reference.

pub fn clear_resource_transform( &self, ) -> Result<NativeFuture<CommandCompletion>>

Stops rewriting the URLs of the runtime’s network requests.

See mln_runtime_clear_resource_transform in the C API reference.

pub fn create(options: Option<&RuntimeOptions<'_>>) -> Result<RuntimeHandle>

Creates a runtime.

A runtime holds maps and the resource loading, cache, and offline regions that they share. In a browser, create runtimes on a Web Worker, not on the main thread.

See mln_runtime_create in the C API reference.

Errors

• Status::InvalidArgument when the cache database file that options names can’t be opened or created.

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

Creates a map on runtime.

Asynchronous calls on the map before the completion runs wait for it, and complete with Status::InvalidState when creation fails.

See mln_runtime_create_map in the C API reference.

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

Creates an offline region in the runtime’s cache file.

metadata holds any bytes to store with the region, such as its name. The region doesn’t download until RuntimeHandle::set_offline_region_download_state() makes its download active.

See mln_runtime_create_offline_region in the C API reference.

pub fn delete_offline_region(&self, region_id: i64) -> Result<NativeFuture<()>>

Deletes the offline region region_id from the runtime’s cache file.

See mln_runtime_delete_offline_region in the C API reference.

Errors

• Status::NotFound when the cache file has no region region_id.

pub fn dispose(self) -> Result<(), ReleaseError<Self>>

Releases a runtime in any state, without waiting.

The runtime finishes its teardown after its maps are released.

See mln_runtime_dispose in the C API reference.

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

Reads the offline region region_id.

The result is null when the cache file has no region with that ID.

See mln_runtime_get_offline_region in the C API reference.

pub fn get_offline_region_status( &self, region_id: i64, ) -> Result<NativeFuture<OfflineRegionStatus>>

Reads the download progress of the offline region region_id.

While the download is active, the counts cover what it has visited. Once it’s inactive, they cover every resource the region holds, including those that only earlier versions of its style listed, so the completed counts can exceed the required counts.

See mln_runtime_get_offline_region_status in the C API reference.

Errors

• Status::NotFound when the cache file has no region region_id.

pub fn invalidate_offline_region( &self, region_id: i64, ) -> Result<NativeFuture<()>>

Makes maps check each resource of the offline region region_id with the server before they use it.

The region keeps its resources. Starting its download again fetches the invalidated resources for offline use. If the style or a TileJSON document is then missing or invalid, the download reports an offline region response error and goes on from the stored copy. Resources that the current style no longer lists stay in the region until it’s deleted.

See mln_runtime_invalidate_offline_region in the C API reference.

Errors

• Status::NotFound when the cache file has no region region_id.

pub fn list_offline_regions( &self, ) -> Result<NativeFuture<Vec<OfflineRegionInfo>>>

Lists the offline regions in the runtime’s cache file.

See mln_runtime_list_offline_regions in the C API reference.

pub fn merge_offline_regions( &self, side_database_path: &str, ) -> Result<NativeFuture<Vec<OfflineRegionInfo>>>

Copies the offline regions of another cache file into the runtime’s cache file.

A region whose definition and metadata match one that the runtime’s file already has isn’t copied again. The result lists the runtime’s copy of each region in the other file.

See mln_runtime_merge_offline_regions in the C API reference.

Errors

• Status::InvalidArgument when side_database_path isn’t a readable database file.
• Status::NativeError when the merge would exceed the tile limit that RuntimeEventType::OfflineRegionTileCountLimitExceeded describes.

pub fn release(self) -> Result<NativeFuture<()>, ReleaseError<Self>>

Releases a runtime.

Release the runtime’s maps first.

See mln_runtime_release in the C API reference.

pub fn run_cache_database_operation( &self, operation: CacheDatabaseOperation, ) -> Result<NativeFuture<()>>

Runs a maintenance action on the runtime’s cache database.

See mln_runtime_run_cache_database_operation in the C API reference.

pub fn set_event_handler( &self, handler: RuntimeEventHandler, ) -> Result<NativeFuture<CommandCompletion>>

Sends the events of the runtime and its maps to a callback.

The callback replaces the one set before.

See mln_runtime_set_event_handler in the C API reference.

pub fn set_http_header_transform( &self, transform: HttpHeaderTransform, ) -> Result<NativeFuture<CommandCompletion>>

Adds headers to the runtime’s HTTP requests.

The transform replaces the one set before. In a browser or on OpenHarmony, serve the requests with RuntimeHandle::set_resource_provider() instead.

Runs on a library thread.

See mln_runtime_set_http_header_transform in the C API reference.

Errors

• Status::Unsupported when the library runs in a browser or on OpenHarmony.

pub fn set_maximum_ambient_cache_size( &self, size: u64, ) -> Result<NativeFuture<()>>

Limits the size of the runtime’s ambient cache.

size is in bytes. Offline regions don’t count toward it. It defaults to 50 MB, or to 0 in the browser when the runtime has no cache file.

See mln_runtime_set_maximum_ambient_cache_size in the C API reference.

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

Starts or pauses the download of the offline region region_id.

Setting the state that the download already has does nothing. A download stops when the runtime closes.

See mln_runtime_set_offline_region_download_state in the C API reference.

Errors

• Status::NotFound when the cache file has no region region_id.

pub fn set_offline_region_observed( &self, region_id: i64, events: RuntimeEventFlag, ) -> Result<NativeFuture<()>>

Selects the events that the runtime reports about the download of the offline region region_id.

events holds bits of RuntimeEventFlag::ALL_RUNTIME_EVENTS and replaces the region’s previous selection.

See mln_runtime_set_offline_region_observed in the C API reference.

Errors

• Status::NotFound when the cache file has no region region_id.

pub fn set_resource_provider( &self, provider: ResourceProvider, ) -> Result<NativeFuture<CommandCompletion>>

Serves the runtime’s network requests through a callback.

The provider receives the network requests that its routes match, and the library loads the rest as usual. A provider can serve URL schemes that the library can’t load itself. The provider replaces the one set before.

See mln_runtime_set_resource_provider in the C API reference.

pub fn set_resource_transform( &self, transform: ResourceTransform, ) -> Result<NativeFuture<CommandCompletion>>

Rewrites the URLs of the runtime’s network requests.

The transform replaces the one set before.

See mln_runtime_set_resource_transform in the C API reference.

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

Replaces the metadata of the offline region region_id.

See mln_runtime_update_offline_region_metadata in the C API reference.

Errors

• Status::NotFound when the cache file has no region region_id.

impl RuntimeHandle

pub fn discarding(&self) -> RuntimeHandleDiscarding<'_>

Trait Implementations

impl Debug for RuntimeHandle

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

Formats the value using the given formatter.