Struct CacheBuilder 

pub struct CacheBuilder<V> { /* private fields */ }

Builder for a Cache.

use amalgam::{Cache, EntryOptions};
use std::time::Duration;

let cache: Cache<String> = Cache::builder()
    .name("users")
    .key_prefix("u:")
    .default_options(EntryOptions::new(Duration::from_secs(60)))
    .build();

Implementations

impl<V> CacheBuilder<V>

pub fn new() -> Self

Creates a builder with default settings.

pub fn instance_id(self, id: impl AsRef<str>) -> Self

Sets this instance’s id (used to ignore its own backplane messages). A random id is generated if not set.

pub fn distributed(self, distributed: Arc<dyn DistributedCache>) -> Self

Attaches an L2 distributed cache backend. Pair with serializer.

pub fn serializer(self, serializer: Arc<dyn DistributedSerializer<V>>) -> Self

Sets the serializer used for the L2 wire format (e.g. JsonSerializer).

pub fn backplane(self, backplane: Arc<dyn Backplane>) -> Self

Attaches a backplane for multi-node L1 invalidation.

Note: when a backplane is configured, build spawns a listener task and so must be called from within a tokio runtime.

pub fn name(self, name: impl AsRef<str>) -> Self

Sets the cache’s name (used in events/diagnostics).

pub fn key_prefix(self, prefix: impl AsRef<str>) -> Self

Sets a prefix prepended to every key.

pub fn default_options(self, options: EntryOptions) -> Self

Sets the default entry options merged into every operation that does not supply its own.

pub fn clock(self, clock: Arc<dyn Clock>) -> Self

Injects a custom Clock (e.g. ManualClock in tests).

pub fn max_capacity(self, capacity: u64) -> Self

Caps the number of entries held in L1 (None = unbounded).

pub fn lock_shards(self, shards: usize) -> Self

Sets the number of single-flight lock shards (rounded up to a power of two).

pub fn remove_by_tag_behavior(self, behavior: RemoveByTagBehavior) -> Self

Sets what remove_by_tag does to matched entries.

pub fn events_capacity(self, capacity: usize) -> Self

Sets the event channel’s buffer capacity.

pub fn distributed_locker(self, locker: Arc<dyn DistributedLocker>) -> Self

Attaches a cross-node distributed locker (e.g. Redis-backed) for cluster-wide single-flight.

pub fn plugin(self, plugin: Arc<dyn Plugin>) -> Self

Registers a Plugin to observe events and lifecycle.

pub fn distributed_circuit_breaker(self, duration: Duration) -> Self

Opens the L2 circuit breaker for duration after an L2 failure (Duration::ZERO disables it — the default).

pub fn backplane_circuit_breaker(self, duration: Duration) -> Self

Opens the backplane circuit breaker for duration after a backplane failure (Duration::ZERO disables it — the default).

pub fn auto_recovery(self, config: RecoveryConfig) -> Self

Configures (or disables) auto-recovery of failed L2 / backplane operations.

pub fn default_options_provider( self, provider: Arc<dyn DefaultEntryOptionsProvider>, ) -> Self

Sets a provider of dynamic, per-key default options (consulted when a call supplies no explicit options).

pub fn ignore_incoming_backplane(self, ignore: bool) -> Self

Drops all incoming backplane notifications (dangerous; for testing).

pub fn distributed_wire_version(self, version: impl AsRef<str>) -> Self

Sets the L2 wire-format version combined with distributed keys.

pub fn distributed_key_modifier_mode(self, mode: KeyModifierMode) -> Self

Sets how the wire-format version is combined with the L2 key (prefix, suffix, or none).

pub fn disable_tagging(self, disable: bool) -> Self

Disables tagging cache-wide (FusionCache DisableTagging).

When enabled, the per-read tag/clear-marker check is skipped entirely (a small read-path saving for caches that never tag), and remove_by_tag / remove_by_tags / clear are ignored and logged at warn (never silently) — the Rust-idiomatic counterpart of FusionCache throwing on tag use when tagging is disabled. Off by default.

pub fn wait_for_initial_backplane_subscribe(self, wait: bool) -> Self

Whether to establish the backplane subscription before build returns (FusionCache WaitForInitialBackplaneSubscribe, default true).

In amalgam this is inherently satisfied: the listener calls backplane.subscribe() synchronously inside build, and the Redis backplane completes its SUBSCRIBE during connect() before being handed to the builder — so there is no startup window where the node serves while unsubscribed. The flag is retained for configuration parity and is queryable via Cache::wait_for_initial_backplane_subscribe.

impl<V: Clone + Send + Sync + 'static> CacheBuilder<V>

pub fn build(self) -> Cache<V>

Builds the cache.

Trait Implementations

impl<V> Default for CacheBuilder<V>

fn default() -> Self

Returns the “default value” for a type.