Struct CompositionBackend 

pub struct CompositionBackend<L1, L2, O, R = SequentialReadPolicy, W = OptimisticParallelWritePolicy>
where
    L1: Backend,
    L2: Backend,
    O: Offload<'static>,
    R: CompositionReadPolicy,
    W: CompositionWritePolicy,
{ /* private fields */ }

A backend that composes two cache backends into a layered caching system.

The first backend (L1) is checked first on reads, and if not found, the second backend (L2) is checked. On writes, both backends are updated.

Each layer can use its own serialization format and compression since CacheBackend operates on typed data, not raw bytes.

Behavior can be customized via CompositionReadPolicy, CompositionWritePolicy, and RefillPolicy to control how reads, writes, and L1 refills are executed across the layers.

Implementations

impl<L1, L2, O> CompositionBackend<L1, L2, O, SequentialReadPolicy, OptimisticParallelWritePolicy>

where L1: Backend, L2: Backend, O: Offload<'static>,

pub fn new(l1: L1, l2: L2, offload: O) -> Self

Creates a new composition backend with two layers using default policies.

Default policies:

• Read: SequentialReadPolicy (try L1 first, then L2)
• Write: OptimisticParallelWritePolicy (write to both, succeed if ≥1 succeeds)
• Refill: RefillPolicy::Never (do not populate L1 after L2 hit)

Arguments

• l1 - First-layer backend (checked first on reads)
• l2 - Second-layer backend (checked if L1 misses)
• offload - Offload manager for background tasks (e.g., race policy losers)

impl<L1, L2, O, R, W> CompositionBackend<L1, L2, O, R, W>

where L1: Backend, L2: Backend, O: Offload<'static>, R: CompositionReadPolicy, W: CompositionWritePolicy,

pub fn read_policy(&self) -> &R

Returns a reference to the read policy.

pub fn write_policy(&self) -> &W

Returns a reference to the write policy.

pub fn refill_policy(&self) -> &RefillPolicy

Returns a reference to the refill policy.

pub fn offload(&self) -> &O

Returns a reference to the offload manager.

pub fn label(self, label: impl Into<BackendLabel>) -> Self

Set a custom label for this backend.

The label is used for source path composition in multi-layer caches. For example, with label “cache”, the source path might be “cache.L1”.

pub fn with_policy<NewR, NewW>( self, policy: CompositionPolicy<NewR, NewW>, ) -> CompositionBackend<L1, L2, O, NewR, NewW>

where NewR: CompositionReadPolicy, NewW: CompositionWritePolicy,

Set all policies at once using CompositionPolicy builder.

This is the preferred way to configure multiple policies.

Example

use hitbox_backend::{CompositionBackend, composition::CompositionPolicy};
use hitbox_backend::composition::policy::{RaceReadPolicy, SequentialWritePolicy, RefillPolicy};

let policy = CompositionPolicy::new()
    .read(RaceReadPolicy::new())
    .write(SequentialWritePolicy::new())
    .refill(RefillPolicy::Always);

let backend = CompositionBackend::new(l1, l2, offload)
    .with_policy(policy);

pub fn read<NewR: CompositionReadPolicy>( self, read_policy: NewR, ) -> CompositionBackend<L1, L2, O, NewR, W>

Set the read policy (builder pattern).

This consumes the backend and returns a new one with the updated read policy.

Example

use hitbox_backend::CompositionBackend;
use hitbox_backend::composition::policy::RaceReadPolicy;

let backend = CompositionBackend::new(l1, l2, offload)
    .read(RaceReadPolicy::new());

pub fn write<NewW: CompositionWritePolicy>( self, write_policy: NewW, ) -> CompositionBackend<L1, L2, O, R, NewW>

Set the write policy (builder pattern).

This consumes the backend and returns a new one with the updated write policy.

Example

use hitbox_backend::CompositionBackend;
use hitbox_backend::composition::policy::SequentialWritePolicy;

let backend = CompositionBackend::new(l1, l2, offload)
    .write(SequentialWritePolicy::new());

pub fn refill(self, refill_policy: RefillPolicy) -> Self

Set the refill policy (builder pattern).

This consumes the backend and returns a new one with the updated refill policy.

Example

use hitbox_backend::CompositionBackend;
use hitbox_backend::composition::policy::RefillPolicy;

let backend = CompositionBackend::new(l1, l2, offload)
    .refill(RefillPolicy::Always);

Trait Implementations

impl<L1, L2, O, R, W> Backend for CompositionBackend<L1, L2, O, R, W>

where L1: Backend + Clone + Send + Sync + 'static, L2: Backend + Clone + Send + Sync + 'static, O: Offload<'static>, R: CompositionReadPolicy, W: CompositionWritePolicy,

fn read<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 CacheKey, ) -> Pin<Box<dyn Future<Output = BackendResult<Option<CacheValue<Raw>>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Read raw cached data by key.

fn write<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 CacheKey, value: CacheValue<Raw>, ) -> Pin<Box<dyn Future<Output = BackendResult<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Write raw data to cache.

fn remove<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 CacheKey, ) -> Pin<Box<dyn Future<Output = BackendResult<DeleteStatus>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Remove data from cache.

fn label(&self) -> BackendLabel

Backend label for metrics and source path composition.

fn value_format(&self) -> &dyn Format

Serialization format for cached values. Default: BincodeFormat.

fn key_format(&self) -> &CacheKeyFormat

Key serialization format. Default: CacheKeyFormat::Bitcode.

fn compressor(&self) -> &dyn Compressor

Compressor for cached values. Default: PassthroughCompressor.

impl<L1, L2, O, R, W> CacheBackend for CompositionBackend<L1, L2, O, R, W>

where L1: CacheBackend + Clone + Send + Sync + 'static, L2: CacheBackend + Clone + Send + Sync + 'static, O: Offload<'static>, R: CompositionReadPolicy, W: CompositionWritePolicy,

async fn get<T>( &self, key: &CacheKey, ctx: &mut BoxContext, ) -> BackendResult<Option<CacheValue<T::Cached>>>

where T: CacheableResponse, T::Cached: Cacheable,

Retrieve a typed value from cache.

async fn set<T>( &self, key: &CacheKey, value: &CacheValue<T::Cached>, ctx: &mut BoxContext, ) -> BackendResult<()>

where T: CacheableResponse, T::Cached: Cacheable,

Store a typed value in cache.

async fn delete( &self, key: &CacheKey, ctx: &mut BoxContext, ) -> BackendResult<DeleteStatus>

Delete a value from cache.

impl<L1, L2, O, R, W> Clone for CompositionBackend<L1, L2, O, R, W>

where L1: Clone + Backend, L2: Clone + Backend, O: Offload<'static>, R: Clone + CompositionReadPolicy, W: Clone + CompositionWritePolicy,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<L1, L2, O, R, W> Debug for CompositionBackend<L1, L2, O, R, W>

where L1: Debug + Backend, L2: Debug + Backend, O: Debug + Offload<'static>, R: Debug + CompositionReadPolicy, W: Debug + CompositionWritePolicy,

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

Formats the value using the given formatter.