Skip to main content

Module deferred

Module deferred 

Source
Expand description

Owning release: lifecycle vocabulary, structured outcomes, and the provider/context-owned deferred release queue.

Phase 3 issued binding identity, allocation generations, and lifetime pins. This module adds the piece that identity alone cannot express: who owns the final physical release, and what is true after it partially fails.

§The three-step contract

  1. Prepare. crate::MemoryBinding::prepare_release matches the binding identity and the allocation generation, removes the live record exactly once under the per-mechanism lock, and returns an owned PreparedAllocationRelease. Because the record is removed under that lock, two racing final releases cannot both proceed, and a stale handle whose virtual address was reused cannot match a newer generation.
  2. Queue (optional). The prepared request is handed to a DeferredReleaseQueue owned by the provider context. Every queue call happens after all registry and mechanism locks are dropped.
  3. Execute. PreparedAllocationRelease::execute calls the pinned allocator with no lock held and returns an AllocationReleaseOutcome.

§Fail-safe rules

  • A prepared request that is abandoned (dropped without execute) quarantines its ownership. It never frees, never blocks, and never loses metadata.
  • Enqueue failure returns the exact request to the caller inside DeferredEnqueueError; dropping that error quarantines the request rather than losing it.
  • Device loss never calls the allocator. Queued requests finish as device-lost quarantine while keeping their allocator/authority/context pins.
  • No Err/Failed shape may imply “nothing changed” after the device was mutated. Any partial mutation is AllocationReleaseOutcome::Quarantined and carries accounting plus residual facts.

Structs§

DeferredEnqueueError
Enqueue failure that hands the exact prepared request back.
PreparedAllocationRelease
Final ownership of one allocation, detached from its live record.
QuarantinedAllocation
One piece of ownership the runtime kept instead of releasing.
ReleaseAccounting
Byte accounting for one release attempt.
ReleaseFailure
A release that failed before any device mutation.
ResidualOwnership
What the runtime still owns after a non-complete release.

Enums§

AllocationReleaseOutcome
The structured result of one whole-allocation release.
AllocationReleaseState
Where one allocation’s ownership currently sits.
DeferredEnqueueRejection
Why a DeferredReleaseQueue refused final ownership.
DeferredReleaseDisposition
What happened when an owning allocation was handed to a deferred queue.
QuarantineReason
Why ownership was retained instead of released.

Traits§

DeferredReleaseQueue
A provider/context-owned sink for final allocation ownership.