Struct SegmentBorrowRegistry 

pub struct SegmentBorrowRegistry { /* private fields */ }

Instruction-scoped segment borrow registry.

Tracks active segment borrows and enforces conflict rules. Designed for inline use in an execution context, no heap, no dynamic dispatch.

Uses compact 8-byte address fingerprints and a flat array of fixed-size entries. Total stack footprint: ~280 bytes (vs ~1.3 KB with full 32-byte addresses and Option wrappers).

Example

let mut borrows = SegmentBorrowRegistry::new();
borrows.register_read(&vault_key, 0, 8)?;   // read balance
borrows.register_write(&vault_key, 8, 32)?;  // write metadata, OK, non-overlapping
borrows.register_write(&vault_key, 0, 8)?;   // REJECTED, overlaps read

Implementations

impl SegmentBorrowRegistry

pub const fn new() -> Self

Create an empty registry.

pub const fn len(&self) -> usize

Number of active borrows.

pub const fn is_empty(&self) -> bool

Whether the registry is empty.

pub fn register_leased_read( &mut self, key: &Address, offset: u32, size: u32, ) -> Result<SegmentBorrow, ProgramError>

Register a new read borrow and return the SegmentBorrow record the caller can hand to SegmentLease::new for RAII release. This is the plumbing that makes crate::segment_lease::SegRef possible.

pub fn register_leased_write( &mut self, key: &Address, offset: u32, size: u32, ) -> Result<SegmentBorrow, ProgramError>

Mutable counterpart of [register_leased_read].

pub fn register(&mut self, new: SegmentBorrow) -> Result<(), ProgramError>

Register a new segment borrow, checking for conflicts.

Returns Err(AccountBorrowFailed) if the new borrow overlaps an existing borrow with incompatible access (read+write or write+write) on the same account (full-address identity, not fingerprint).

pub fn register_read( &mut self, key: &Address, offset: u32, size: u32, ) -> Result<(), ProgramError>

Convenience: register a read borrow for the given account region.

pub fn register_write( &mut self, key: &Address, offset: u32, size: u32, ) -> Result<(), ProgramError>

Convenience: register a write borrow for the given account region.

pub fn release(&mut self, borrow: &SegmentBorrow) -> bool

Release a previously registered borrow.

Finds the first matching entry and removes it, compacting the array. Identity is full-address (not fingerprint) to stay collision-safe.

pub fn clear(&mut self)

Reset the registry, clearing all active borrows.

pub fn would_conflict(&self, proposed: &SegmentBorrow) -> bool

Check if a proposed borrow would conflict, without registering it.

Uses full-address identity, fingerprint collisions do not produce false positives.

pub fn register_guard( &mut self, borrow: SegmentBorrow, ) -> Result<SegmentBorrowGuard<'_>, ProgramError>

Register a borrow and return an RAII guard that auto-releases it on drop.

This is the preferred way to acquire segment borrows, the guard ensures the borrow is released even if the caller returns early via ? or encounters an error.

Example

{
    let _guard = borrows.register_guard_write(&key, 0, 8)?;
    // ... write to segment ...
} // guard dropped → borrow released

pub fn register_guard_read( &mut self, key: &Address, offset: u32, size: u32, ) -> Result<SegmentBorrowGuard<'_>, ProgramError>

Register a read borrow with RAII auto-release.

pub fn register_guard_write( &mut self, key: &Address, offset: u32, size: u32, ) -> Result<SegmentBorrowGuard<'_>, ProgramError>

Register a write borrow with RAII auto-release.

pub fn for_each<F: FnMut(&SegmentBorrow)>(&self, f: F)

Visit each active borrow in registration order.

Intended for diagnostics and for the hopper explain introspection path, never for hot-path decisions.

pub fn find_exact( &self, key: &Address, offset: u32, size: u32, kind: AccessKind, ) -> Option<&SegmentBorrow>

Look up an active borrow by exact (key, offset, size, kind).