Crate backdrop

source ·
Expand description

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:

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

Type Definitions