Struct SharedUniversal 

pub struct SharedUniversal<T: Copy + Eq + 'static> { /* private fields */ }

Implementations

impl<T: Copy + Eq + 'static> SharedUniversal<T>

pub fn create( base: impl AsRef<Path>, capacity: usize, ) -> Result<Self, UniversalError>

Create a new container. Starts in Vec strategy at (generation=0, version=0).

pub fn open( base: impl AsRef<Path>, capacity: usize, ) -> Result<Self, UniversalError>

Open an existing container. Reads the active (generation, version, strategy) from the state header and opens the matching backing file.

pub fn strategy(&self) -> Strategy

The strategy currently active in shared state. May differ from the locally-held backing if another writer just migrated; the next op call will re-open transparently.

pub fn strategy_version(&self) -> u32

The shared strategy version. Bumps on every migration; wraps to 0 at u32::MAX with the generation counter incrementing.

pub fn strategy_generation(&self) -> u16

The shared generation counter. Bumps each time version wraps from u32::MAX back to 0. Together with version it forms the true monotonic migration counter.

pub fn insert(&self, value: T) -> Result<(), UniversalError>

where T: Hash,

Insert value. For Vec strategy this is push_back; for Map strategy this is insert(value, ()).

pub fn contains(&self, value: &T) -> Result<bool, UniversalError>

where T: Hash,

Membership check. Bumps the contains counter so the local policy can observe contains-heavy workloads.

pub fn len(&self) -> Result<usize, UniversalError>

Number of live entries.

pub fn is_empty(&self) -> Result<bool, UniversalError>

pub fn clear(&self) -> Result<(), UniversalError>

Reset the universal to empty: clears whichever backing is currently live (Vec or Map). Does not change the strategy. Useful for steady-state benches that need to reset accumulated state between iterations. Not thread-safe with concurrent insert/remove from other threads.

pub fn snapshot(&self) -> Result<Vec<T>, UniversalError>

Snapshot all live values into a Vec<T>. Best-effort under concurrent writers.

pub fn op_histogram(&self) -> (u64, u64)

Operation counts since creation. The writer’s policy code reads these to decide when to migrate.

pub fn migrate_to(&self, target: Strategy) -> Result<(), UniversalError>

where T: Hash,

Force a migration to target. Snapshots the current backing, creates a new backing file at version+1, restores the snapshot, then publishes the new (version, strategy) via Release CAS.

Concurrency

Single-writer ONLY. Two processes calling migrate_to concurrently will both build new backings and race on the CAS; the loser orphans its backing file. Use ap-uvj’s voting protocol to coordinate when multiple writers are involved.

pub fn maybe_migrate_by_policy( &self, contains_to_insert_ratio: f64, min_total_ops: u64, ) -> Result<Option<Strategy>, UniversalError>

where T: Hash,

Local-policy migration trigger. If the observed contains ops outnumber insert ops by at least contains_to_insert_ratio, AND total ops exceed min_total_ops, migrate Vec → Map. If the inverse holds, migrate Map → Vec.

Returns Ok(Some(new_strategy)) if a migration happened, Ok(None) if no policy threshold was crossed.

Trait Implementations

impl<T: Copy + Eq + Send + Sync + 'static> AdaptiveInstance for SharedUniversal<T>

fn header(&self) -> &HandshakeHeader

fn ring(&self) -> &ObservationRing

fn make_policy(&self) -> Box<dyn Policy>

fn apply_migration(&self, new_tag: u32)

Called by the sidecar when the policy returns a new strategy tag. Default implementation: just set the tag on the header. Primitives that need heavier migration (data-layout swap) override this to perform the swap before (or after) updating the tag.

impl<T: Copy + Eq + Send + 'static> Send for SharedUniversal<T>

impl<T: Copy + Eq + Sync + 'static> Sync for SharedUniversal<T>