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.

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)

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. If something is missing that you really need, 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