Crate backdrop

The backdrop crate allows you to customize when and how your values are dropped. The main entry point of this crate is the Backdrop<T, Strategy> wrapper type. This will wrap any ‘normal’ type T with a zero-cost wrapper that customizes how it is dropped based on the given Strategy, which is a marker (zero-size compile-time only) type that implements the BackdropStrategy<T> trait.

Which strategy is best?

This probably depends very much on your application! Be sure to benchmark! For general applications, the following are good starting recommendations:

• TrashThreadStrategy if you are working on a normal application where multithreading is possible.
• TokioTaskStrategy or TokioBlockingTaskStrategy if you are building an async application on top of the ::tokio crate.
• TrashQueueStrategy if you are writing a single-threaded application.

Backdrop also ships with a bunch of ‘simple testing’ strategies (LeakStrategy, TrivialStrategy, DebugStrategy, ThreadStrategy), that can help to understand how backdrop works, as leaning tool to build your own strategies, and as benchmarking baseline.

Limitations

Backdrop<T, S> implements the Deref and DerefMut traits, enabling you to use most methods available on T also on a Backdrop<T>. On top of this, a bunch of common traits have been implemented for Backdrop<T, S> whenever they are implemented for T.

Features

Basic features

• You can disable the std feature (enabled by default) to use this crate in no-std contexts. Without std, none of the thread-based strategies are available. The DebugStrategy is also disabled as it depends on println.
• As long as the alloc feature is not disabled (enabled by default; part of the std feature) the single-threaded TrashQueueStrategy is still available to you. If you also do not have access to alloc , you’ll probably want to create your own strategy for your particular no-std situation.
• You can enable the optional tokio feature to get access to strategies that drop on a background tokio task. (C.f. the tokio module)

Using Backdrop with traits from other crates

• rkyv enables Archive/Serialize/Deserialize support for Backdrop<T, S> iff they are implemented for T.
• bytecheck enables CheckBytes support for Backdrop<T, S> iff implemented for T.

Need support for something else? Please open a PR and we can add it as an optional feature.

Modules

threadstd

tokiotokio

The contents of this module are only available when the tokio feature is enabled.

Structs

Backdrop

Wrapper to drop any value at a later time, such as in a background thread.

DebugStrategystd

‘Wrapper’ strategy that prints out T when executed.

LeakStrategy

Strategy which will leak the contained value rather than dropping it.

ThreadStrategystd

Strategy which drops the contained value in a newly spawned background thread.

TokioBlockingTaskStrategytokio

Strategy which spawns a new ‘blocking’ tokio task which drops the contained value.

TokioTaskStrategytokio

Strategy which spawns a new tokio task which drops the contained value.

TrashQueueStrategyalloc

Strategy which adds garbage to a global ‘trash VecDeque’.

TrashThreadStrategystd

Strategy which sends any to-be-dropped values to a dedicated ‘trash thread’

TrivialStrategy

Strategy which drops the contained value normally.

Traits

BackdropStrategy

The strategy to use to drop T.

Type Aliases

LeakBackdrop

ThreadBackdropstd

Convenient alias for a Backdrop that uses the ThreadStrategy

TokioBlockingTaskBackdroptokio

Convenient alias for a Backdrop that uses the TokioBlockingTaskStrategy

TokioTaskBackdroptokio

Convenient alias for a Backdrop that uses the TokioTaskStrategy

TrashThreadBackdropstd

Convenient alias for a Backdrop that uses the TrashThreadStrategy

TrivialBackdrop