Struct InstanceTracker 

pub struct InstanceTracker { /* private fields */ }

Thread-safe tracker — instantiated in both the DataWriter and the DataReader.

Implementations

impl InstanceTracker

pub fn new() -> Self

New tracker with its own InstanceHandleAllocator.

pub fn with_allocator(allocator: Arc<InstanceHandleAllocator>) -> Self

Tracker with a shared allocator (e.g. when a writer and reader in the same participant draw their handles from the same pool).

pub fn register( &self, keyhash: KeyHash, key_holder: Vec<u8>, timestamp: Option<Time>, ) -> InstanceHandle

Registers the instance if it is not yet known; otherwise just reactivates it (Spec §2.2.2.4.2.5).

Always returns the (stable) InstanceHandle.

pub fn should_deliver_under_time_based_filter( &self, keyhash: &KeyHash, sample_ts: Time, min_separation_nanos: u128, ) -> bool

Spec §2.2.3.12 TIME_BASED_FILTER — decides whether a sample with sample_ts may be delivered to the user API. false if t - last_delivered_ts < min_separation (drop); true otherwise (deliver).

For an unknown instance or the first sample (no last_delivered_ts) it is always true.

pub fn should_deliver_under_destination_order( &self, keyhash: &KeyHash, source_ts: Time, by_source_timestamp: bool, ) -> bool

Spec §2.2.3.18 DESTINATION_ORDER — decides whether a sample with source_ts may be delivered to the user API. BY_RECEPTION_TIMESTAMP: always true. BY_SOURCE_TIMESTAMP: only if source_ts is strictly greater than this instance’s last_delivered_ts (the tie-break on equal timestamps via the writer GUID happens in the typed path).

pub fn record_delivery(&self, keyhash: &KeyHash, sample_ts: Time)

Marks that a sample with sample_ts was delivered to the user API (Spec §2.2.3.12 — for the next filter decision).

pub fn lookup(&self, keyhash: &KeyHash) -> Option<InstanceHandle>

Lookup without mutation (Spec §2.2.2.4.2.14 lookup_instance).

pub fn get_by_handle(&self, handle: InstanceHandle) -> Option<InstanceState>

Returns a copy of the state snapshot for a handle.

pub fn get_by_keyhash(&self, keyhash: &KeyHash) -> Option<InstanceState>

Returns a copy of the state snapshot for a KeyHash.

pub fn get_key_holder(&self, handle: InstanceHandle) -> Option<Vec<u8>>

Returns the key-holder byte stream for a handle (Spec §2.2.2.4.2.13 get_key_value).

pub fn dispose(&self, handle: InstanceHandle, timestamp: Option<Time>) -> bool

Marks the instance as NOT_ALIVE_DISPOSED (Spec §2.2.2.4.2.10 dispose).

Returns false if the instance is not known.

pub fn unregister( &self, handle: InstanceHandle, timestamp: Option<Time>, ) -> bool

Decrements the writer counter; if it drops to 0, the instance transitions to NOT_ALIVE_NO_WRITERS (Spec §2.2.2.4.2.7).

pub fn should_accept_sample_under_exclusive_ownership( &self, keyhash: &KeyHash, writer_guid: [u8; 16], writer_strength: i32, ) -> bool

Spec §2.2.3.10 OWNERSHIP=EXCLUSIVE strength selection. Returns true if a sample from the writer with (writer_guid, writer_strength) should be accepted for the instance keyhash.

Algorithm (Spec §2.2.3.10):

• No current owner → accept + set as owner.
• Strength > current → accept + replace owner.
• Strength == current and guid > current_guid → accept (spec tie-break via the lexicographically higher guid).
• Strength < current → reject.
• Strength == current and guid < current → reject.
• Strength == current and guid == current → accept (same writer).

pub fn clear_owner_for_writer(&self, writer_guid: [u8; 16]) -> usize

Spec §2.2.3.23 — on liveliness loss of a writer: clear the owner for all instances whose owner was this writer. The next sample triggers failover selection.

pub fn clear_owner_for_writer_prefix(&self, prefix: [u8; 12]) -> usize

Like Self::clear_owner_for_writer, but matches on the first 12 bytes of the GUID (GuidPrefix). Allows failover when only the participant identity (e.g. via SPDP lease expiry) is known.

pub fn autopurge( &self, now: Time, autopurge_disposed_delay_nanos: u128, autopurge_nowriter_delay_nanos: u128, ) -> usize

Spec §2.2.3.22 READER_DATA_LIFECYCLE — purges instances whose disposed/no-writer marker is older than the respective delay. now is the caller-side wall-clock; the delays are in nanoseconds. Returns the number of removed instances.

Lazy purge: called from the read path (or a background tick). The spec leaves the strategy open — we delete the affected instance entirely, so that subsequent read/take no longer see it.

pub fn observe_sample( &self, keyhash: KeyHash, key_holder: Vec<u8>, timestamp: Option<Time>, ) -> (InstanceHandle, bool)

Reader-side hook: marks that a sample has arrived for this instance. Returns (handle, was_new), where was_new == true means this instance was previously unknown or the reader view was freshly reset (view_state = NEW).

pub fn mark_view_seen(&self, handle: InstanceHandle)

Reader side: after the first read/take of an instance, its view state is set to NOT_NEW.

pub fn drain_samples(&self, handle: InstanceHandle, n: u32)

Reader side: after take, samples_in_cache is reduced by n.

pub fn ordered_handles(&self) -> Vec<InstanceHandle>

Lists all instance handles in stable order (BTreeMap order by KeyHash). Spec §2.2.2.5.3.28 read_next_instance.

pub fn next_handle_after( &self, previous: InstanceHandle, ) -> Option<InstanceHandle>

Returns the first handle whose sort order lies strictly after previous_handle (or the very first one if previous == HANDLE_NIL). Spec §2.2.2.5.3.28.

pub fn len(&self) -> usize

Number of tracked instances.

pub fn is_empty(&self) -> bool

true if no instances are tracked.

Trait Implementations

impl Clone for InstanceTracker

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for InstanceTracker

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

Formats the value using the given formatter.

impl Default for InstanceTracker

fn default() -> Self

Returns the “default value” for a type.