pub trait Drop {
    // Required method
    fn drop(&mut self);
}
Available on non-crate feature miri-test-libstd only.
Expand description

Custom code within the destructor.

When a value is no longer needed, Rust will run a “destructor” on that value. The most common way that a value is no longer needed is when it goes out of scope. Destructors may still run in other circumstances, but we’re going to focus on scope for the examples here. To learn about some of those other cases, please see the reference section on destructors.

This destructor consists of two components:

  • A call to Drop::drop for that value, if this special Drop trait is implemented for its type.
  • The automatically generated “drop glue” which recursively calls the destructors of all the fields of this value.

As Rust automatically calls the destructors of all contained fields, you don’t have to implement Drop in most cases. But there are some cases where it is useful, for example for types which directly manage a resource. That resource may be memory, it may be a file descriptor, it may be a network socket. Once a value of that type is no longer going to be used, it should “clean up” its resource by freeing the memory or closing the file or socket. This is the job of a destructor, and therefore the job of Drop::drop.

Examples

To see destructors in action, let’s take a look at the following program:

struct HasDrop;

impl Drop for HasDrop {
    fn drop(&mut self) {
        println!("Dropping HasDrop!");
    }
}

struct HasTwoDrops {
    one: HasDrop,
    two: HasDrop,
}

impl Drop for HasTwoDrops {
    fn drop(&mut self) {
        println!("Dropping HasTwoDrops!");
    }
}

fn main() {
    let _x = HasTwoDrops { one: HasDrop, two: HasDrop };
    println!("Running!");
}

Rust will first call Drop::drop for _x and then for both _x.one and _x.two, meaning that running this will print

Running!
Dropping HasTwoDrops!
Dropping HasDrop!
Dropping HasDrop!

Even if we remove the implementation of Drop for HasTwoDrop, the destructors of its fields are still called. This would result in

Running!
Dropping HasDrop!
Dropping HasDrop!

You cannot call Drop::drop yourself

Because Drop::drop is used to clean up a value, it may be dangerous to use this value after the method has been called. As Drop::drop does not take ownership of its input, Rust prevents misuse by not allowing you to call Drop::drop directly.

In other words, if you tried to explicitly call Drop::drop in the above example, you’d get a compiler error.

If you’d like to explicitly call the destructor of a value, mem::drop can be used instead.

Drop order

Which of our two HasDrop drops first, though? For structs, it’s the same order that they’re declared: first one, then two. If you’d like to try this yourself, you can modify HasDrop above to contain some data, like an integer, and then use it in the println! inside of Drop. This behavior is guaranteed by the language.

Unlike for structs, local variables are dropped in reverse order:

struct Foo;

impl Drop for Foo {
    fn drop(&mut self) {
        println!("Dropping Foo!")
    }
}

struct Bar;

impl Drop for Bar {
    fn drop(&mut self) {
        println!("Dropping Bar!")
    }
}

fn main() {
    let _foo = Foo;
    let _bar = Bar;
}

This will print

Dropping Bar!
Dropping Foo!

Please see the reference for the full rules.

Copy and Drop are exclusive

You cannot implement both Copy and Drop on the same type. Types that are Copy get implicitly duplicated by the compiler, making it very hard to predict when, and how often destructors will be executed. As such, these types cannot have destructors.

Required Methods§

source

fn drop(&mut self)

Executes the destructor for this type.

This method is called implicitly when the value goes out of scope, and cannot be called explicitly (this is compiler error E0040). However, the mem::drop function in the prelude can be used to call the argument’s Drop implementation.

When this method has been called, self has not yet been deallocated. That only happens after the method is over. If this wasn’t the case, self would be a dangling reference.

Panics

Given that a panic! will call drop as it unwinds, any panic! in a drop implementation will likely abort.

Note that even if this panics, the value is considered to be dropped; you must not cause drop to be called again. This is normally automatically handled by the compiler, but when using unsafe code, can sometimes occur unintentionally, particularly when using ptr::drop_in_place.

Implementors§

§

impl Drop for Bytes

§

impl Drop for BytesMut

1.36.0 · source§

impl Drop for Waker

§

impl Drop for kvarn::prelude::compact_str::Drain<'_>

1.13.0 · source§

impl Drop for CString

1.6.0 · source§

impl Drop for alloc::string::Drain<'_>

1.63.0 · source§

impl Drop for OwnedFd

source§

impl Drop for h2::share::RecvStream

§

impl Drop for AbortHandle

§

impl Drop for CancellationToken

§

impl Drop for DefaultGuard

Available on crate feature std only.
§

impl Drop for DropGuard

§

impl Drop for DuplexStream

§

impl Drop for Enter

§

impl Drop for EnteredSpan

§

impl Drop for FixedBuf

§

impl Drop for Guard

§

impl Drop for INotifyWatcher

§

impl Drop for LocalEnterGuard

§

impl Drop for LocalHandle

§

impl Drop for LocalSet

§

impl Drop for Notified<'_>

§

impl Drop for OwnedSemaphorePermit

§

impl Drop for OwnedWriteHalf

§

impl Drop for OwnedWriteHalf

§

impl Drop for PollWatcher

§

impl Drop for Probe

§

impl Drop for RecvStream

§

impl Drop for Runtime

§

impl Drop for Runtime

§

impl Drop for SelectedOperation<'_>

§

impl Drop for SemaphorePermit<'_>

§

impl Drop for SendStream

§

impl Drop for Span

§

impl Drop for WaitGroup

§

impl<'a> Drop for Chunks<'a>

§

impl<'a> Drop for Entered<'a>

§

impl<'a, Alloc> Drop for StrideEval<'a, Alloc>where Alloc: Allocator<u16> + Allocator<u32> + Allocator<f32>,

§

impl<'a, K, F, A> Drop for DrainFilter<'a, K, F, A>where A: Allocator + Clone, F: FnMut(&K) -> bool,

§

impl<'a, K, V, F, A> Drop for DrainFilter<'a, K, V, F, A>where F: FnMut(&K, &mut V) -> bool, A: Allocator + Clone,

§

impl<'a, R, G, T> Drop for MappedReentrantMutexGuard<'a, R, G, T>where R: RawMutex + 'a, G: GetThreadId + 'a, T: 'a + ?Sized,

§

impl<'a, R, G, T> Drop for ReentrantMutexGuard<'a, R, G, T>where R: RawMutex + 'a, G: GetThreadId + 'a, T: 'a + ?Sized,

§

impl<'a, R, T> Drop for MappedMutexGuard<'a, R, T>where R: RawMutex + 'a, T: 'a + ?Sized,

§

impl<'a, R, T> Drop for MappedRwLockReadGuard<'a, R, T>where R: RawRwLock + 'a, T: 'a + ?Sized,

§

impl<'a, R, T> Drop for MappedRwLockWriteGuard<'a, R, T>where R: RawRwLock + 'a, T: 'a + ?Sized,

§

impl<'a, R, T> Drop for MutexGuard<'a, R, T>where R: RawMutex + 'a, T: 'a + ?Sized,

§

impl<'a, R, T> Drop for RwLockReadGuard<'a, R, T>where R: RawRwLock + 'a, T: 'a + ?Sized,

§

impl<'a, R, T> Drop for RwLockUpgradableReadGuard<'a, R, T>where R: RawRwLockUpgrade + 'a, T: 'a + ?Sized,

§

impl<'a, R, T> Drop for RwLockWriteGuard<'a, R, T>where R: RawRwLock + 'a, T: 'a + ?Sized,

source§

impl<'a, T> Drop for kvarn::prelude::header::Drain<'a, T>

source§

impl<'a, T> Drop for ValueDrain<'a, T>

source§

impl<'a, T> Drop for DrainSorted<'a, T>where T: Ord,

§

impl<'a, T> Drop for CallocBackingStore<'a, T>where T: 'a,

§

impl<'a, T> Drop for Drain<'a, T>where T: 'a + Array,

§

impl<'a, T> Drop for MappedMutexGuard<'a, T>where T: ?Sized,

§

impl<'a, T> Drop for MutexGuard<'a, T>where T: ?Sized,

§

impl<'a, T> Drop for RwLockMappedWriteGuard<'a, T>where T: ?Sized,

§

impl<'a, T> Drop for RwLockReadGuard<'a, T>where T: ?Sized,

§

impl<'a, T> Drop for RwLockWriteGuard<'a, T>where T: ?Sized,

§

impl<'brotli_state, AllocU8, AllocU32, AllocHC> Drop for BrotliState<AllocU8, AllocU32, AllocHC>where AllocU8: Allocator<u8>, AllocU32: Allocator<u32>, AllocHC: Allocator<HuffmanCode>,

§

impl<'e, E, W> Drop for EncoderWriter<'e, E, W>where E: Engine, W: Write,

source§

impl<'f> Drop for VaListImpl<'f>

§

impl<'p, 's, T> Drop for SliceVecDrain<'p, 's, T>where T: Default,

§

impl<'p, A, I> Drop for ArrayVecSplice<'p, A, I>where A: Array, I: Iterator<Item = <A as Array>::Item>,

§

impl<'p, A, I> Drop for TinyVecSplice<'p, A, I>where A: Array, I: Iterator<Item = <A as Array>::Item>,

§

impl<'rwlock, T> Drop for RwLockReadGuard<'rwlock, T>where T: ?Sized,

§

impl<'rwlock, T> Drop for RwLockUpgradeableGuard<'rwlock, T>where T: ?Sized,

§

impl<'rwlock, T> Drop for RwLockWriteGuard<'rwlock, T>where T: ?Sized,

§

impl<A> Drop for IntoIter<A>where A: Array,

§

impl<A> Drop for SmallVec<A>where A: Array,

Available on non-crate feature may_dangle only.
§

impl<A, B> Drop for ArcUnion<A, B>

§

impl<C, B> Drop for Connection<C, B>where C: Connection<B>, B: Buf,

§

impl<D, T> Drop for InFlightOneshot<D, T>where D: 'static, T: OneshotOutputTransform<StoredData = D>,

§

impl<E> Drop for CompletionQueue<'_, E>where E: EntryMarker,

§

impl<E> Drop for SubmissionQueue<'_, E>where E: EntryMarker,

§

impl<ErrType, W, BufferType, Alloc> Drop for CompressorWriterCustomIo<ErrType, W, BufferType, Alloc>where W: CustomWrite<ErrType>, BufferType: SliceWrapperMut<u8>, Alloc: BrotliAlloc,

§

impl<ErrType, W, BufferType, AllocU8, AllocU32, AllocHC> Drop for DecompressorWriterCustomIo<ErrType, W, BufferType, AllocU8, AllocU32, AllocHC>where W: CustomWrite<ErrType>, BufferType: SliceWrapperMut<u8>, AllocU8: Allocator<u8>, AllocU32: Allocator<u32>, AllocHC: Allocator<HuffmanCode>,

§

impl<F> Drop for LossyDecoder<F>where F: FnMut(&str),

§

impl<Fut> Drop for FuturesUnordered<Fut>

§

impl<Fut> Drop for Shared<Fut>where Fut: Future,

§

impl<H, T> Drop for ThinArc<H, T>

1.21.0 · source§

impl<I, A> Drop for Splice<'_, I, A>where I: Iterator, A: Allocator,

1.7.0 · source§

impl<K, V, A> Drop for BTreeMap<K, V, A>where A: Allocator + Clone,

1.7.0 · source§

impl<K, V, A> Drop for alloc::collections::btree::map::IntoIter<K, V, A>where A: Allocator + Clone,

source§

impl<K, V, F, A> Drop for alloc::collections::btree::map::DrainFilter<'_, K, V, F, A>where A: Allocator + Clone, F: FnMut(&K, &mut V) -> bool,

§

impl<ReturnValue, ExtraInput, Alloc, U> Drop for WorkerPool<ReturnValue, ExtraInput, Alloc, U>where ReturnValue: Send + 'static, ExtraInput: Send + 'static, Alloc: BrotliAlloc + Send + 'static, U: Send + 'static + Sync,

§

impl<S, C> Drop for IoUring<S, C>where S: EntryMarker, C: EntryMarker,

source§

impl<T> Drop for kvarn::prelude::header::IntoIter<T>

source§

impl<T> Drop for kvarn::prelude::Arc<T>where T: ?Sized,

source§

impl<T> Drop for ThinBox<T>where T: ?Sized,

1.12.0 · source§

impl<T> Drop for PeekMut<'_, T>where T: Ord,

source§

impl<T> Drop for LinkedList<T>

source§

impl<T> Drop for Rc<T>where T: ?Sized,

1.4.0 · source§

impl<T> Drop for alloc::rc::Weak<T>where T: ?Sized,

1.4.0 · source§

impl<T> Drop for alloc::sync::Weak<T>where T: ?Sized,

source§

impl<T> Drop for std::sync::mpsc::Receiver<T>

source§

impl<T> Drop for std::sync::mpsc::Sender<T>

source§

impl<T> Drop for SyncSender<T>

source§

impl<T> Drop for std::sync::mutex::MutexGuard<'_, T>where T: ?Sized,

source§

impl<T> Drop for OnceLock<T>

source§

impl<T> Drop for std::sync::rwlock::RwLockReadGuard<'_, T>where T: ?Sized,

source§

impl<T> Drop for std::sync::rwlock::RwLockWriteGuard<'_, T>where T: ?Sized,

§

impl<T> Drop for Arc<T>where T: ?Sized,

§

impl<T> Drop for AsyncFd<T>where T: AsRawFd,

§

impl<T> Drop for AtomicCell<T>

§

impl<T> Drop for Instrumented<T>

§

impl<T> Drop for JoinHandle<T>

§

impl<T> Drop for JoinSet<T>

§

impl<T> Drop for LocalFutureObj<'_, T>

§

impl<T> Drop for MutexGuard<'_, T>where T: ?Sized,

§

impl<T> Drop for MutexGuard<'_, T>where T: ?Sized,

§

impl<T> Drop for MutexLockFuture<'_, T>where T: ?Sized,

§

impl<T> Drop for OffsetArc<T>

§

impl<T> Drop for OnceBox<T>

§

impl<T> Drop for OnceCell<T>

§

impl<T> Drop for Owned<T>where T: Pointable + ?Sized,

§

impl<T> Drop for OwnedMutexGuard<T>where T: ?Sized,

§

impl<T> Drop for OwnedMutexGuard<T>where T: ?Sized,

§

impl<T> Drop for OwnedMutexLockFuture<T>where T: ?Sized,

§

impl<T> Drop for OwnedPermit<T>

§

impl<T> Drop for OwnedRwLockWriteGuard<T>where T: ?Sized,

§

impl<T> Drop for Permit<'_, T>

§

impl<T> Drop for Receiver<T>

§

impl<T> Drop for Receiver<T>

§

impl<T> Drop for Receiver<T>

§

impl<T> Drop for Receiver<T>

§

impl<T> Drop for Receiver<T>

§

impl<T> Drop for Receiver<T>

§

impl<T> Drop for Sender<T>

§

impl<T> Drop for Sender<T>

§

impl<T> Drop for Sender<T>

§

impl<T> Drop for Sender<T>

§

impl<T> Drop for Sender<T>

§

impl<T> Drop for ShardedLockWriteGuard<'_, T>where T: ?Sized,

§

impl<T> Drop for UnboundedReceiver<T>

source§

impl<T, A> Drop for Box<T, A>where A: Allocator, T: ?Sized,

1.6.0 · source§

impl<T, A> Drop for alloc::collections::vec_deque::drain::Drain<'_, T, A>where A: Allocator,

source§

impl<T, A> Drop for VecDeque<T, A>where A: Allocator,

1.6.0 · source§

impl<T, A> Drop for alloc::vec::drain::Drain<'_, T, A>where A: Allocator,

source§

impl<T, A> Drop for alloc::vec::into_iter::IntoIter<T, A>where A: Allocator,

source§

impl<T, A> Drop for Vec<T, A>where A: Allocator,

§

impl<T, A> Drop for RawDrain<'_, T, A>where A: Allocator + Clone,

§

impl<T, A> Drop for RawIntoIter<T, A>where A: Allocator + Clone,

Available on non-crate feature nightly only.
§

impl<T, A> Drop for RawTable<T, A>where A: Allocator + Clone,

Available on non-crate feature nightly only.
§

impl<T, B> Drop for SendRequest<T, B>where T: OpenStreams<B>, B: Buf,

source§

impl<T, F> Drop for alloc::collections::linked_list::DrainFilter<'_, T, F>where F: FnMut(&mut T) -> bool,

source§

impl<T, F> Drop for LazyLock<T, F>

§

impl<T, F> Drop for TaskLocalFuture<T, F>where T: 'static,

source§

impl<T, F, A> Drop for alloc::collections::btree::set::DrainFilter<'_, T, F, A>where A: Allocator + Clone, F: FnMut(&T) -> bool,

source§

impl<T, F, A> Drop for alloc::vec::drain_filter::DrainFilter<'_, T, F, A>where A: Allocator, F: FnMut(&mut T) -> bool,

source§

impl<T, F, S> Drop for ScopeGuard<T, F, S>where F: FnOnce(T), S: Strategy,

§

impl<T, N> Drop for GenericArrayIter<T, N>where N: ArrayLength<T>,

§

impl<T, U> Drop for MappedMutexGuard<'_, T, U>where T: ?Sized, U: ?Sized,

§

impl<T, U> Drop for OwnedMappedMutexGuard<T, U>where T: ?Sized, U: ?Sized,

§

impl<T, U> Drop for OwnedRwLockMappedWriteGuard<T, U>where T: ?Sized, U: ?Sized,

§

impl<T, U> Drop for OwnedRwLockReadGuard<T, U>where T: ?Sized, U: ?Sized,

1.40.0 · source§

impl<T, const N: usize> Drop for kvarn::prelude::compact_str::core::array::IntoIter<T, N>

§

impl<Ty> Drop for MemoryBlock<Ty>where Ty: Default,

Available on crate feature std only.
source§

impl<W> Drop for BufWriter<W>where W: Write,

source§

impl<W> Drop for GzEncoder<W>where W: Write,