Class RuntimeHandle

Namespace

Maplibre.NativeFfi.Runtime

Assembly

Maplibre.NativeFfi.dll

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

public sealed class RuntimeHandle : IDisposable

Inheritance

object

RuntimeHandle

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Properties

IsClosed

Whether this wrapper has successfully closed its native handle.

public bool IsClosed { get; }

Property Value

bool

Methods

AcquireWakeSource()

Acquires a wake source that releases this runtime's parked owner thread. The returned source is usable from any thread, and the caller disposes it.

public WakeSource AcquireWakeSource()

Returns

WakeSource

ClearHttpHeaderTransform()

Clears headers added to built-in HTTP requests.

public void ClearHttpHeaderTransform()

ClearResourceProvider()

Clears the runtime-scoped resource provider callback.

public void ClearResourceProvider()

ClearResourceTransform()

Clears the runtime-scoped resource transform callback.

public void ClearResourceTransform()

Close()

Destroys the runtime on its owner thread.

public void Close()

Create(RuntimeOptions)

Creates a runtime on the current thread.

public static RuntimeHandle Create(RuntimeOptions options)

Parameters

options RuntimeOptions

Returns

RuntimeHandle

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

DrainEvents()

Drains every queued runtime event into one batch of copies.

public RuntimeEventBatch DrainEvents()

Returns

RuntimeEventBatch

Remarks

The batch reports the events this runtime and its maps queued under the masks they select, in queue order, as managed copies of the borrowed native records.

DrainEvents(int)

Drains at most maxEvents queued runtime events.

public RuntimeEventBatch DrainEvents(int maxEvents)

Parameters

maxEvents int

Returns

RuntimeEventBatch

Remarks

Zero drains every queued event. A positive value drains at most that many and reports how many stayed queued in RemainingCount, so a host that takes a bounded slice per iteration learns to come back.

GetEventMask()

Reports which runtime-originated event types this runtime queues.

public RuntimeEventMask GetEventMask()

Returns

RuntimeEventMask

Remarks

The value is the mask last set, including bits outside AllRuntimeEvents that this runtime ignores. A runtime created with the default EventMask reports every event type this library selects by default, including any this binding does not declare.

Pump(TimeSpan)

Advances this runtime.

public void Pump(TimeSpan timeout)

Parameters

timeout TimeSpan

Remarks

The call parks the owner thread when timeout allows it, then drains the owner-thread task queues. Drain the queued runtime events with DrainEvents() afterwards.

Zero drains and returns, a positive value parks for up to that long, and a negative value parks until a wake arrives. Timers and ready file descriptors wake the runtime 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. A queued event releases a park, so a host that pumps and drains in a loop keeps making progress.

budget bounds the drain. Null or a negative value drains without a bound. Zero or a positive 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.

Pump(TimeSpan, TimeSpan?)

Advances this runtime.

public void Pump(TimeSpan timeout, TimeSpan? budget)

Parameters

timeout TimeSpan

budget TimeSpan?

Remarks

The call parks the owner thread when timeout allows it, then drains the owner-thread task queues. Drain the queued runtime events with DrainEvents() afterwards.

Zero drains and returns, a positive value parks for up to that long, and a negative value parks until a wake arrives. Timers and ready file descriptors wake the runtime 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. A queued event releases a park, so a host that pumps and drains in a loop keeps making progress.

budget bounds the drain. Null or a negative value drains without a bound. Zero or a positive 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.

SetEventMask(RuntimeEventMask)

Selects which runtime-originated event types this runtime queues.

public void SetEventMask(RuntimeEventMask mask)

Parameters

mask RuntimeEventMask

Remarks

The mask reads the bits in AllRuntimeEvents and ignores the rest, so All selects every runtime-originated type. An event type this mask clears is never queued, so it neither reaches a batch nor wakes a parked Pump(TimeSpan, TimeSpan?).

SetHttpHeaderTransform(HttpHeaderTransformCallback)

Installs or replaces headers added to built-in HTTP requests.

public void SetHttpHeaderTransform(HttpHeaderTransformCallback callback)

Parameters

callback HttpHeaderTransformCallback

SetResourceProvider(ResourceProviderCallback)

Installs or replaces the runtime-scoped resource provider callback.

public void SetResourceProvider(ResourceProviderCallback callback)

Parameters

callback ResourceProviderCallback

SetResourceTransform(ResourceTransformCallback)

Installs or replaces the runtime-scoped resource transform callback.

public void SetResourceTransform(ResourceTransformCallback callback)

Parameters

callback ResourceTransformCallback

StartAmbientCacheOperation(AmbientCacheOperation)

Starts an ambient cache maintenance operation.

public OfflineOperationHandle StartAmbientCacheOperation(AmbientCacheOperation operation)

Parameters

operation AmbientCacheOperation

Returns

OfflineOperationHandle

StartCreateOfflineRegion(OfflineRegionDefinition, byte[])

Starts an offline region creation operation.

public OfflineOperationHandle StartCreateOfflineRegion(OfflineRegionDefinition definition, byte[] metadata)

Parameters

definition OfflineRegionDefinition

metadata byte[]

Returns

OfflineOperationHandle

StartDeleteOfflineRegion(long)

Starts an offline region delete operation.

public OfflineOperationHandle StartDeleteOfflineRegion(long id)

Parameters

id long

Returns

OfflineOperationHandle

StartInvalidateOfflineRegion(long)

Starts an offline region invalidation operation.

public OfflineOperationHandle StartInvalidateOfflineRegion(long id)

Parameters

id long

Returns

OfflineOperationHandle

StartMergeOfflineRegionsDatabase(string)

Starts an offline region database merge operation.

public OfflineOperationHandle StartMergeOfflineRegionsDatabase(string path)

Parameters

path string

Returns

OfflineOperationHandle

StartOfflineRegion(long)

Starts an offline region lookup operation.

public OfflineOperationHandle StartOfflineRegion(long id)

Parameters

id long

Returns

OfflineOperationHandle

StartOfflineRegionStatus(long)

Starts an offline region status lookup operation.

public OfflineOperationHandle StartOfflineRegionStatus(long id)

Parameters

id long

Returns

OfflineOperationHandle

StartOfflineRegions()

Starts an offline region list operation.

public OfflineOperationHandle StartOfflineRegions()

Returns

OfflineOperationHandle

StartSetMaximumAmbientCacheSize(ulong)

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

public OfflineOperationHandle StartSetMaximumAmbientCacheSize(ulong size)

Parameters

size ulong

Returns

OfflineOperationHandle

Remarks

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

StartSetOfflineRegionDownloadState(long, OfflineRegionDownloadState)

Starts an offline region download-state update operation.

public OfflineOperationHandle StartSetOfflineRegionDownloadState(long id, OfflineRegionDownloadState downloadState)

Parameters

id long

downloadState OfflineRegionDownloadState

Returns

OfflineOperationHandle

StartSetOfflineRegionObserved(long, bool)

Starts an offline region observed-state update operation.

public OfflineOperationHandle StartSetOfflineRegionObserved(long id, bool observed)

Parameters

id long

observed bool

Returns

OfflineOperationHandle

StartUpdateOfflineRegionMetadata(long, byte[])

Starts an offline region metadata update operation.

public OfflineOperationHandle StartUpdateOfflineRegionMetadata(long id, byte[] metadata)

Parameters

id long

metadata byte[]

Returns

OfflineOperationHandle

TakeCreateOfflineRegionResult(OfflineOperationHandle)

public OfflineRegionInfo TakeCreateOfflineRegionResult(OfflineOperationHandle operation)

Parameters

operation OfflineOperationHandle

Returns

OfflineRegionInfo

TakeMergeOfflineRegionsDatabaseResult(OfflineOperationHandle)

public IReadOnlyList<OfflineRegionInfo> TakeMergeOfflineRegionsDatabaseResult(OfflineOperationHandle operation)

Parameters

operation OfflineOperationHandle

Returns

IReadOnlyList<OfflineRegionInfo>

TakeOfflineRegionResult(OfflineOperationHandle)

public OfflineRegionInfo? TakeOfflineRegionResult(OfflineOperationHandle operation)

Parameters

operation OfflineOperationHandle

Returns

OfflineRegionInfo

TakeOfflineRegionStatusResult(OfflineOperationHandle)

public OfflineRegionStatus TakeOfflineRegionStatusResult(OfflineOperationHandle operation)

Parameters

operation OfflineOperationHandle

Returns

OfflineRegionStatus

TakeOfflineRegionsResult(OfflineOperationHandle)

public IReadOnlyList<OfflineRegionInfo> TakeOfflineRegionsResult(OfflineOperationHandle operation)

Parameters

operation OfflineOperationHandle

Returns

IReadOnlyList<OfflineRegionInfo>

TakeUpdateOfflineRegionMetadataResult(OfflineOperationHandle)

public OfflineRegionInfo TakeUpdateOfflineRegionMetadataResult(OfflineOperationHandle operation)

Parameters

operation OfflineOperationHandle

Returns

OfflineRegionInfo