Struct defer_drop::DeferDrop

#[repr(transparent)]
pub struct DeferDrop<T: Send + 'static> { /* private fields */ }

Wrapper type that, when dropped, sends the inner value to a global background thread to be dropped. Useful in cases where a value takes a long time to drop (for instance, a windows file that might block on close, or a large data structure that has to extensively recursively trawl itself).

DeferDrop implements Deref and DerefMut, meaning it can be dereferenced and freely used like a container around its inner type.

Notes:

Carefully consider whether this pattern is necessary for your use case. Like all worker-thread abstractions, sending the value to a separate thread comes with its own costs, so it should only be done if performance profiling indicates that it’s a performance gain.

There is only one global worker thread. Dropped values are enqueued in an unbounded channel to be consumed by this thread; if you produce more garbage than the thread can handle, this will cause unbounded memory consumption. There is currently no way for the thread to signal or block if it is overwhelmed.

All of the standard non-determinism threading caveats apply here. The objects are guaranteed to be destructed in the order received through a channel, which means that objects sent from a single thread will be destructed in order. However, there is no guarantee about the ordering of interleaved values from different threads. Additionally, there are no guarantees about how long the values will be queued before being dropped, or even that they will be dropped at all. If your main thread terminates before all drops could be completed, they will be silently lost (as though via a mem::forget). This behavior is entirely up to your OS’s thread scheduler. There is no way to receive a signal indicating when a particular object was dropped.

Example

use defer_drop::DeferDrop;
use std::time::{Instant, Duration};
use std::iter::repeat_with;

let massive_vec: Vec<Vec<i32>> = repeat_with(|| vec![1, 2, 3])
    .take(1_000_000)
    .collect();

let deferred = DeferDrop::new(massive_vec.clone());

fn timer(f: impl FnOnce()) -> Duration {
    let start = Instant::now();
    f();
    Instant::now() - start
}

let drop1 = timer(move || drop(massive_vec));
let drop2 = timer(move || drop(deferred));

assert!(drop2 < drop1);

Implementations

impl<T: Send + 'static> DeferDrop<T>

pub fn new(value: T) -> Self

Create a new DeferDrop value.

pub fn into_inner(this: Self) -> T

Unwrap the DeferDrop, returning the inner value. This has the effect of cancelling the deferred drop behavior; ownership of the inner value is transferred to the caller.

Trait Implementations

impl<T: Send + 'static> AsMut<T> for DeferDrop<T>

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

Converts this type into a mutable reference of the (usually inferred) input type.

impl<T: Send + 'static> AsRef<T> for DeferDrop<T>

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: Clone + Send + 'static> Clone for DeferDrop<T>

fn clone(&self) -> DeferDrop<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug + Send + 'static> Debug for DeferDrop<T>

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

Formats the value using the given formatter.

impl<T: Default + Send + 'static> Default for DeferDrop<T>

fn default() -> DeferDrop<T>

Returns the “default value” for a type.

impl<T: Send + 'static> Deref for DeferDrop<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T: Send + 'static> DerefMut for DeferDrop<T>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'de, T: Deserialize<'de> + Send + 'static> Deserialize<'de> for DeferDrop<T>

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>where
    D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T: Send + 'static> Drop for DeferDrop<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Send + 'static> From<T> for DeferDrop<T>

fn from(value: T) -> Self

Converts to this type from the input type.

impl<T: Hash + Send + 'static> Hash for DeferDrop<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 + Send + 'static> Ord for DeferDrop<T>

fn cmp(&self, other: &DeferDrop<T>) -> Ordering

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere
    Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl<T: PartialEq + Send + 'static> PartialEq<DeferDrop<T>> for DeferDrop<T>

fn eq(&self, other: &DeferDrop<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<T: PartialOrd + Send + 'static> PartialOrd<DeferDrop<T>> for DeferDrop<T>

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl<T: Serialize + Send + 'static> Serialize for DeferDrop<T>

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>where
    S: Serializer,

Serialize this value into the given Serde serializer.

impl<T: Eq + Send + 'static> Eq for DeferDrop<T>

impl<T: Send + 'static> StructuralEq for DeferDrop<T>

impl<T: Send + 'static> StructuralPartialEq for DeferDrop<T>