Struct Backdrop

pub struct Backdrop<T, S: BackdropStrategy<T>> { /* private fields */ }

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

Backdrop<T, Strategy> is guaranteed to have the same in-memory representation as T. As such, wrapping (and unwrapping) a T into a Backdrop<T, S> has zero memory overhead.

Besides altering how T is dropped, a Backdrop<T, S> behaves as much as possible as a T. This is done by implementing Deref and DerefMut so most methods available for T are also immediately available for Backdrop<T>. Backdrop<T, S> also implements many common traits whenever T implements these.

Customizing the strategy

You customize what strategy is used by picking your desired S parameter, which can be any type that implements the BackdropStrategy trait. This crate comes with many common strategies, but you can also implement your own.

Restrictions

Backdrop<T, Strategy> does not restrict T (besides T needing to be Sized). However, Many Strategy only implement BackdropStrategy<T> when T fits certain restrictions. For instance, the TrashThreadStrategy requires T to be Send since T will be moved to another thread to be cleaned up there.

What about unsized/dynamically-sized types? The current implementation of Backdrop restricts T to be Sized mostly for ease of implementation. It is our expectation that your unsized datastructures probably are already nested in a std::boxed::Box<T> or other smart pointer, which you can wrap with Backdrop as a whole. (Side note: Zero-sized types can be wrapped by Backdrop without problems.)

There is one final important restriction:

The problem with Arc

A Backdrop<Arc<T>, S> will not behave as you might expect: It will cause the backdrop strategy to run whenever the reference count is decremented. But what you probably want, is to run the backdrop strategy exactly when the last Arc<T> is dropped (AKA when the reference count drops to 0) and the contents of the Arc go out of scope.

A Arc<Backdrop<Box<T>, S>> will work as you expect, but you incur an extra pointer indirection (arc -> box -> T) every time you read its internal value.

Instead, use the backdrop_arc crate, which contains a specialized Arc datatype that does exactly what you want without a needless indirection.

Implementations

impl<T, Strategy: BackdropStrategy<T>> Backdrop<T, Strategy>

pub fn new(val: T) -> Self

Construct a new Backdrop<T, S> from any T. This is a zero-cost operation.

From now on, T will no longer be dropped normally, but instead it will be dropped using the implementation of the given BackdropStrategy.

use backdrop::*;

// Either specify the return type:
let mynum: Backdrop<usize, LeakStrategy> = Backdrop::new(42);

// Or use the 'Turbofish' syntax on the function call:
let mynum2 = Backdrop::<_, LeakStrategy>::new(42);

// Or use one of the shorthand type aliases:
let mynum3 = LeakBackdrop::new(42);

assert_eq!(mynum, mynum2);
assert_eq!(mynum2, mynum3);
// <- Because we are using the LeakStrategy, we leak memory here. Fun! :-)

This function is the inverse of Backdrop::into_inner.

Examples found in repository

examples/comparison.rs (line 27)

fn main() {
    let boxed = setup();
    let not_backdropped = boxed.clone();
    time("none", move || {
        assert_eq!(not_backdropped.len(), LEN);
        // Destructor runs here
    });

    let backdropped: TrivialBackdrop<_> = Backdrop::new(boxed.clone());
    time("fake backdrop", move || {
        assert_eq!(backdropped.len(), LEN);
        // Destructor runs here
    });

    let backdropped: thread::ThreadBackdrop<_> = Backdrop::new(boxed.clone());
    time("thread backdrop", move || {
        assert_eq!(backdropped.len(), LEN);
        // Destructor runs here
    });

    TrashThreadStrategy::with_trash_thread(||{
        let backdropped: thread::TrashThreadBackdrop<_> = Backdrop::new(boxed.clone());
        time("trash thread backdrop", move || {
            assert_eq!(backdropped.len(), LEN);
            // Destructor runs here
        });
    });

    TrashQueueStrategy::ensure_initialized();
    let backdropped = Backdrop::<_, TrashQueueStrategy>::new(boxed.clone());
    time("(single threaded) trash queue backdrop", move || {
        assert_eq!(backdropped.len(), LEN);
        // Destructor runs here
    });

    time("(single threaded) trash queue backdrop (actually cleaning up later)", move || {
        TrashQueueStrategy::cleanup_all();
    });

    #[cfg(miri)]
    {
        println!("Skipping Tokio examples when running on Miri, since it does not support Tokio yet");
    }
    #[cfg(not(miri))]
    {
    ::tokio::runtime::Builder::new_multi_thread()
        .enable_all()
        .build()
        .unwrap()
        .block_on(async {
            let backdropped: crate::tokio::TokioTaskBackdrop<_> = Backdrop::new(boxed.clone());
            time("tokio task (multithread runner)", move || {
                assert_eq!(backdropped.len(), LEN);
                // Destructor runs here
            });

            let backdropped: crate::tokio::TokioBlockingTaskBackdrop<_> = Backdrop::new(boxed.clone());
            time("tokio blocking task (multithread runner)", move || {
                assert_eq!(backdropped.len(), LEN);
                // Destructor runs here
            });
        });

    ::tokio::runtime::Builder::new_current_thread()
        .enable_all()
        .build()
        .unwrap()
        .block_on(async {
            let backdropped: crate::tokio::TokioTaskBackdrop<_> = Backdrop::new(setup());
            time("tokio task (current thread runner)", move || {
                assert_eq!(backdropped.len(), LEN);
                // Destructor runs here
            });

            let backdropped: crate::tokio::TokioBlockingTaskBackdrop<_> = Backdrop::new(setup());
            time("tokio blocking task (current thread runner)", move || {
                assert_eq!(backdropped.len(), LEN);
                // Destructor runs here
            });
        });
    }
}

pub fn into_inner(this: Self) -> T

Turns a Backdrop<T, S> back into a normal T. This undoes the effect of Backdrop. The resulting T will be dropped again using normal rules. This function is the inverse of Backdrop::new.

This is a zero-cost operation.

This is an associated function, so call it using fully-qualified syntax.

pub fn change_strategy<S2: BackdropStrategy<T>>(this: Self) -> Backdrop<T, S2>

Changes the strategy used for a Backdrop.

This is a zero-cost operation

This is an associated function, so call it using fully-qualified syntax.

use backdrop::*;

let foo = LeakBackdrop::new(42);
let foo = Backdrop::change_strategy::<TrivialStrategy>(foo);
// Now `foo` will be dropped according to TrivialStrategy (which does the normal drop rules)
// rather than LeakStrategy (which does not cleanup by leaking memory)

Trait Implementations

impl<T: Archive, S> Archive for Backdrop<T, S>

where S: BackdropStrategy<T>,

Available on crate feature rkyv only.

type Archived = <T as Archive>::Archived

The archived representation of this type.

type Resolver = <T as Archive>::Resolver

The resolver for this type. It must contain all the additional information from serializing needed to make the archived type from the normal type.

unsafe fn resolve( &self, pos: usize, resolver: Self::Resolver, out: *mut Self::Archived, )

Creates the archived version of this value at the given position and writes it to the given output.

impl<C: ?Sized, T: CheckBytes<C>, S> CheckBytes<C> for Backdrop<T, S>

where S: BackdropStrategy<T>,

Available on crate feature bytecheck only.

type Error = <T as CheckBytes<C>>::Error

The error that may result from checking the type.

unsafe fn check_bytes<'a>( value: *const Self, context: &mut C, ) -> Result<&'a Self, Self::Error>

Checks whether the given pointer points to a valid value within the given context.

impl<T: Clone, S> Clone for Backdrop<T, S>

where S: BackdropStrategy<T>,

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug, S> Debug for Backdrop<T, S>

where S: BackdropStrategy<T>,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T, S: BackdropStrategy<T>> DerefMut for Backdrop<T, S>

fn deref_mut(&mut self) -> &mut T

Mutably dereferences the value.

impl<Des, T, S> Deserialize<Backdrop<T, S>, Des> for Archived<T>

where T: Archive, Archived<T>: Deserialize<T, Des>, Des: Fallible, S: BackdropStrategy<T>,

Available on crate feature rkyv only.

fn deserialize( &self, deserializer: &mut Des, ) -> Result<Backdrop<T, S>, <Des as Fallible>::Error>

Deserializes using the given deserializer

impl<T: Display, S> Display for Backdrop<T, S>

where S: BackdropStrategy<T>,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T, Strategy: BackdropStrategy<T>> Drop for Backdrop<T, Strategy>

This is where the magic happens: Instead of dropping T normally, we run Strategy::execute on it.

fn drop(&mut self)

Executes the destructor for this type.

impl<T, S> From<T> for Backdrop<T, S>

where S: BackdropStrategy<T>,

Converting between a T and a Backdrop<T, S> is a zero-cost operation

c.f. Backdrop::new

fn from(val: T) -> Self

Converts to this type from the input type.

impl<T: Hash, S> Hash for Backdrop<T, S>

where S: BackdropStrategy<T>,

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T: Ord, S> Ord for Backdrop<T, S>

where S: BackdropStrategy<T>,

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T: PartialEq, S> PartialEq for Backdrop<T, S>

where S: BackdropStrategy<T>,

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialOrd, S> PartialOrd for Backdrop<T, S>

where S: BackdropStrategy<T>,

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<Ser, T: Archive + Serialize<Ser>, S> Serialize<Ser> for Backdrop<T, S>

where Ser: Fallible, S: BackdropStrategy<T>,

Available on crate feature rkyv only.

fn serialize( &self, serializer: &mut Ser, ) -> Result<Self::Resolver, <Ser as Fallible>::Error>

Writes the dependencies for the object and returns a resolver that can create the archived type.

impl<T, S: BackdropStrategy<T>> Deref for Backdrop<T, S>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T: Eq, S> Eq for Backdrop<T, S>

where S: BackdropStrategy<T>,