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:
TrashThreadStrategy
if you are working on a normal application where multithreading is possible.TokioTaskStrategy
orTokioBlockingTaskStrategy
if you are building anasync
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. Withoutstd
, none of thethread
-based strategies are available. TheDebugStrategy
is also disabled as it depends onprintln
. - As long as the
alloc
feature is not disabled (enabled by default; part of thestd
feature) the single-threadedTrashQueueStrategy
is still available to you. If you also do not have access toalloc
, 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. thetokio
module)
Using Backdrop with traits from other crates
rkyv
enablesArchive
/Serialize
/Deserialize
support forBackdrop<T, S>
iff they are implemented forT
.bytecheck
enablesCheckBytes
support forBackdrop<T, S>
iff implemented forT
.
Need support for something else? Please open a PR and we can add it as an optional feature.
Modules
- thread
std
- tokio
tokio
The contents of this module are only available when thetokio
feature is enabled.
Structs
- Wrapper to drop any value at a later time, such as in a background thread.
- ‘Wrapper’ strategy that prints out T when executed.
- Strategy which will leak the contained value rather than dropping it.
- Strategy which drops the contained value in a newly spawned background thread.
- Strategy which spawns a new ‘blocking’ tokio task which drops the contained value.
- TokioTaskStrategy
tokio
Strategy which spawns a new tokio task which drops the contained value. - TrashQueueStrategy
alloc
Strategy which adds garbage to a global ‘trashVecDeque
’. - Strategy which sends any to-be-dropped values to a dedicated ‘trash thread’
- Strategy which drops the contained value normally.
Traits
- The strategy to use to drop
T
.
Type Definitions
- Convenient alias for a
Backdrop
that uses theThreadStrategy
- Convenient alias for a
Backdrop
that uses theTokioBlockingTaskStrategy
- TokioTaskBackdrop
tokio
Convenient alias for aBackdrop
that uses theTokioTaskStrategy
- Convenient alias for a
Backdrop
that uses theTrashThreadStrategy