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;
}

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;

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

Required Methods

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

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

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.

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