Struct BindingRegistry 

pub struct BindingRegistry { /* private fields */ }

A narrow registry for provider/context pins and binding identity.

Lock order

There are two lock classes: the registry lock protects registration and current selection; each mechanism lock protects only lifecycle, allocation identities, queued releases, and quarantined ownership. They are never held together. Allocator/capability callbacks, deferred-queue callbacks, waits, and device operations run with neither lock held.

Implementations

impl BindingRegistry

pub fn new() -> Result<Self, BindingError>

pub fn register_provider_context( &self, device: DeviceKey, resource: Arc<dyn BindingResource>, ) -> Result<RegisteredProviderContext, BindingError>

pub fn register_authority( &self, device: DeviceKey, resource: Arc<dyn BindingResource>, ) -> Result<RegisteredAuthority, BindingError>

pub fn register_allocator( &self, context: RegisteredProviderContext, authority: RegisteredAuthority, allocator: Arc<dyn DeviceAllocator>, ) -> Result<RegisteredMechanism, BindingError>

pub unsafe fn register_trusted_composite( &self, context: RegisteredProviderContext, authority: RegisteredAuthority, allocator: Arc<dyn DeviceAllocator>, ) -> Result<RegisteredMechanism, BindingError>

Register a transparent/composite wrapper as one trusted coherent bundle.

Safety

The registrar must ensure ordinary allocation, optional capabilities, and canonical release all reach one coherent device mechanism, authority, and provider context. Rust cannot prove that a hostile split-inner wrapper satisfies this raw-pointer contract.

pub fn select(&self, mechanism: RegisteredMechanism) -> Result<(), BindingError>

Make mechanism the mechanism that later bind(device) calls use.

A mechanism can be retired or lost between validation and publication, so the candidate is re-checked after it is published. When that re-check fails the selection is withdrawn, and the withdrawal never leaves a dead or unregistered mechanism selected: it will not overwrite a newer selection, restores the previous selection only while that is still registered and Active, and otherwise clears the selection so a later registration for the device can heal it.

pub fn bind(&self, device: DeviceKey) -> Result<MemoryBinding, BindingError>

pub fn bind_registered( &self, mechanism: RegisteredMechanism, ) -> Result<MemoryBinding, BindingError>

pub fn retire(&self, mechanism: RegisteredMechanism) -> Result<(), BindingError>

Stop issuing new work through mechanism.

Existing allocations keep the original allocator/context/authority pinned and may still use MemoryBinding::release explicitly.

The lifecycle is made terminal before the selection is dropped. The two lock classes cannot be held together, so the reverse order leaves a window in which a concurrent select that already validated this mechanism publishes it after the clear and still observes Active at its own re-check, wedging the device on a retired selection. Retiring first means any such select must fail its re-check and withdraw itself.

pub fn invalidate_device( &self, device: DeviceKey, reason: impl Into<Arc<str>>, ) -> Result<(), BindingError>

Invalidate every mechanism and binding for device.

This method changes identity/lifetime state only. It does not invoke a device callback, free physical memory, release a lease, or refund quota.

Like BindingRegistry::retire, every affected mechanism is made terminal before the selection is dropped, so a select racing device loss cannot leave a lost mechanism selected. Only a selection naming a mechanism this call actually invalidated is dropped, so a mechanism registered after this call returns is never deselected by it. A registration that lands while this call is in flight may still end up unselected, because the slot it tried to claim was held by an identity this call then dropped; that fails closed, and the next registration or explicit BindingRegistry::select restores a selection.

pub fn confirm_context_terminated( &self, context: RegisteredProviderContext, ) -> Result<(), BindingError>

Record externally observed provider-context/process termination.

This is the device-loss teardown boundary. Allocation identities become terminal without calling the allocator. Accounting/delegated quota must be reconciled by the owning authority only after its own required process or context termination observation.

pub fn quarantined( &self, mechanism: RegisteredMechanism, ) -> Result<Vec<QuarantinedAllocation>, BindingError>

Ownership this mechanism deliberately retained instead of releasing.

Taking this list never invokes a provider and never calls an allocator.

pub fn remove_provider_context( &self, context: RegisteredProviderContext, ) -> Result<(), BindingError>

Remove the registry’s provider-context pin after all mechanism registrations using it have been removed. Existing binding handles keep their own pin until they retire.

pub fn remove_authority( &self, authority: RegisteredAuthority, ) -> Result<(), BindingError>

Remove the registry’s authority pin after all mechanism registrations using it have been removed. This does not refund charges or delegated quota; the authority owner performs accounting reconciliation separately.

pub fn remove(&self, mechanism: RegisteredMechanism) -> Result<(), BindingError>

Remove a terminal/retired registration once no allocation metadata, queued release, quarantined ownership, or active callback remains. Existing binding/capability handles still pin the entry and resources, but remain inactive.

Queued and quarantined ownership both block removal: a queued request still holds an active-operation pin, and quarantined ownership is reported separately so the caller learns why removal is unsafe rather than seeing a bare lifecycle complaint.

pub fn snapshot( &self, mechanism: RegisteredMechanism, ) -> Result<MechanismSnapshot, BindingError>

pub fn snapshots(&self) -> Result<Vec<MechanismSnapshot>, BindingError>

Snapshot every registered mechanism without exposing the registration map to a process manager.

The registry lock is released before any per-mechanism lock is taken, so the two lock classes remain never-nested.

Trait Implementations

impl Clone for BindingRegistry

fn clone(&self) -> BindingRegistry

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BindingRegistry

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

Formats the value using the given formatter.