Trait Offload 

pub trait Offload<'a>:
    Send
    + Sync
    + Clone {
    // Required method
    fn spawn<F>(&self, kind: impl Into<SmolStr>, future: F)
       where F: Future<Output = ()> + Send + 'a;

    // Provided method
    fn register<K, F>(&self, key: K, future: F)
       where K: Into<OffloadKey>,
             F: Future<Output = ()> + Send + 'a { ... }
}

Trait for spawning background tasks.

This trait allows components like CacheFuture and CompositionBackend to offload work to be executed in the background without blocking the main request path.

Lifetime Parameter

The lifetime parameter 'a determines what futures can be spawned:

• Offload<'static>: Can spawn futures that live forever (real background tasks)
• Offload<'a>: Can only spawn futures that live at least as long as 'a

This enables DisabledOffload to accept any lifetime (since it doesn’t actually spawn anything), while OffloadManager requires 'static.

Implementations

• DisabledOffload: Does nothing, accepts any lifetime. Use when background execution is not needed (e.g., reqwest middleware integration).
• OffloadManager (in hitbox crate): Real background execution, requires 'static.

Clone bound

Implementors should use Arc internally to ensure all cloned instances share the same configuration and state.

Example

use hitbox_core::{Offload, OffloadKey};

fn offload_cache_write<'a, O: Offload<'a>>(offload: &O, key: CacheKey) {
    offload.register((key, "cache_write"), async move {
        // Perform background cache write
        println!("Writing to cache");
    });
}

Required Methods

fn spawn<F>(&self, kind: impl Into<SmolStr>, future: F)

where F: Future<Output = ()> + Send + 'a,

👎Deprecated since 0.2.1: use register instead, will be removed in 0.3

Spawn a future to be executed in the background.

The future will be executed asynchronously and its result will be handled according to the implementation’s policy.

Arguments

• kind - A label categorizing the task type (e.g., “revalidate”, “cache_write”). Used for metrics and tracing.
• future - The future to execute in the background. Must be Send + 'a. For real background execution, 'a must be 'static.

Deprecation

This method will be removed in version 0.3. Use register instead:

// Before (deprecated)
offload.spawn("revalidate", async { /* ... */ });

// After
offload.register(OffloadKey::generated("revalidate", id), async { /* ... */ });

Provided Methods

fn register<K, F>(&self, key: K, future: F)

where K: Into<OffloadKey>, F: Future<Output = ()> + Send + 'a,

Register a future to be executed in the background.

This is the primary method for spawning background tasks.

Arguments

• key - The key identifying this task. A tuple (CacheKey, &str) can also be passed.
• future - The future to execute in the background. Must be Send + 'a.

Example

use hitbox_core::{Offload, OffloadKey, CacheKey};

let cache_key = CacheKey::from_str("user", "123");
offload.register((cache_key, "revalidate"), async {
    // Revalidate cache entry
});

offload.register(OffloadKey::explicit("cleanup", 1), async {
    // Cleanup task
});

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<'a> Offload<'a> for DisabledOffload