Trait rocket::mtls::oid::asn1_rs::nom::lib::std::ops::Drop

1.0.0 · source ·
pub trait Drop {
    // Required method
    fn drop(&mut self);
}
Available on crate feature mtls 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.

§Drop check

Dropping interacts with the borrow checker in subtle ways: when a type T is being implicitly dropped as some variable of this type goes out of scope, the borrow checker needs to ensure that calling T’s destructor at this moment is safe. In particular, it also needs to be safe to recursively drop all the fields of T. For example, it is crucial that code like the following is being rejected:

use std::cell::Cell;

struct S<'a>(Cell<Option<&'a S<'a>>>, Box<i32>);
impl Drop for S<'_> {
    fn drop(&mut self) {
        if let Some(r) = self.0.get() {
            // Print the contents of the `Box` in `r`.
            println!("{}", r.1);
        }
    }
}

fn main() {
    // Set up two `S` that point to each other.
    let s1 = S(Cell::new(None), Box::new(42));
    let s2 = S(Cell::new(Some(&s1)), Box::new(42));
    s1.0.set(Some(&s2));
    // Now they both get dropped. But whichever is the 2nd one
    // to be dropped will access the `Box` in the first one,
    // which is a use-after-free!
}

The Nomicon discusses the need for drop check in more detail.

To reject such code, the “drop check” analysis determines which types and lifetimes need to still be live when T gets dropped. The exact details of this analysis are not yet stably guaranteed and subject to change. Currently, the analysis works as follows:

  • If T has no drop glue, then trivially nothing is required to be live. This is the case if neither T nor any of its (recursive) fields have a destructor (impl Drop). PhantomData and ManuallyDrop are considered to never have a destructor, no matter their field type.
  • If T has drop glue, then, for all types U that are owned by any field of T, recursively add the types and lifetimes that need to be live when U gets dropped. The set of owned types is determined by recursively traversing T:
    • Recursively descend through PhantomData, Box, tuples, and arrays (including arrays of length 0).
    • Stop at reference and raw pointer types as well as function pointers and function items; they do not own anything.
    • Stop at non-composite types (type parameters that remain generic in the current context and base types such as integers and bool); these types are owned.
    • When hitting an ADT with impl Drop, stop there; this type is owned.
    • When hitting an ADT without impl Drop, recursively descend to its fields. (For an enum, consider all fields of all variants.)
  • Furthermore, if T implements Drop, then all generic (lifetime and type) parameters of T must be live.

In the above example, the last clause implies that 'a must be live when S<'a> is dropped, and hence the example is rejected. If we remove the impl Drop, the liveness requirement disappears and the example is accepted.

There exists an unstable way for a type to opt-out of the last clause; this is called “drop check eyepatch” or may_dangle. For more details on this nightly-only feature, see the discussion in the Nomicon.

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

Implementations should generally avoid panic!ing, because drop() may itself be called during unwinding due to a panic, and if the drop() panics in that situation (a “double panic”), this will likely abort the program. It is possible to check panicking() first, which may be desirable for a Drop implementation that is reporting a bug of the kind “you didn’t finish using this before it was dropped”; but most types should simply clean up their owned allocations or other resources and return normally from drop(), regardless of what state they are in.

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§

source§

impl Drop for Client

source§

impl Drop for Error

1.6.0 · source§

impl Drop for rocket::mtls::oid::asn1_rs::nom::lib::std::string::Drain<'_>

1.13.0 · source§

impl Drop for CString

1.36.0 · source§

impl Drop for Waker

1.63.0 · source§

impl Drop for OwnedFd

source§

impl Drop for Aes128

source§

impl Drop for Aes128Dec

source§

impl Drop for Aes128Enc

source§

impl Drop for Aes192

source§

impl Drop for Aes192Dec

source§

impl Drop for Aes192Enc

source§

impl Drop for Aes256

source§

impl Drop for Aes256Dec

source§

impl Drop for Aes256Enc

source§

impl Drop for Bytes

source§

impl Drop for BytesMut

source§

impl Drop for RecvStream

source§

impl Drop for TempDir

source§

impl Drop for TempPath

source§

impl Drop for DropGuard

source§

impl Drop for CancellationToken

source§

impl Drop for DuplexStream

source§

impl Drop for tokio::net::tcp::split_owned::OwnedWriteHalf

source§

impl Drop for tokio::net::unix::split_owned::OwnedWriteHalf

source§

impl Drop for Runtime

source§

impl Drop for AbortHandle

source§

impl Drop for Notified<'_>

source§

impl Drop for OwnedSemaphorePermit

source§

impl Drop for SemaphorePermit<'_>

source§

impl Drop for LocalEnterGuard

source§

impl Drop for LocalSet

source§

impl Drop for DefaultGuard

source§

impl Drop for EnteredSpan

source§

impl Drop for Span

source§

impl<'a> Drop for Encoder<'a>

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

impl<'a, T> Drop for http::header::map::Drain<'a, T>

source§

impl<'a, T> Drop for http::header::map::ValueDrain<'a, T>

source§

impl<'a, T> Drop for http::header::map::Drain<'a, T>

source§

impl<'a, T> Drop for http::header::map::ValueDrain<'a, T>

source§

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

source§

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

source§

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

source§

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

source§

impl<'a, T> Drop for tokio::sync::rwlock::read_guard::RwLockReadGuard<'a, T>
where T: ?Sized,

source§

impl<'a, T> Drop for tokio::sync::rwlock::write_guard::RwLockWriteGuard<'a, T>
where T: ?Sized,

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

impl<A> Drop for RepeatN<A>

source§

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

source§

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

source§

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

source§

impl<Fut> Drop for FuturesUnordered<Fut>

1.21.0 · source§

impl<I, A> Drop for rocket::mtls::oid::asn1_rs::nom::lib::std::vec::Splice<'_, I, A>
where I: Iterator, A: Allocator,

source§

impl<I, A> Drop for allocator_api2::stable::vec::splice::Splice<'_, I, A>
where I: Iterator, A: Allocator,

source§

impl<I, K, V, S> Drop for indexmap::map::iter::Splice<'_, I, K, V, S>
where I: Iterator<Item = (K, V)>, K: Hash + Eq, S: BuildHasher,

1.7.0 · source§

impl<K, V, A> Drop for rocket::mtls::oid::asn1_rs::nom::lib::std::collections::btree_map::IntoIter<K, V, A>
where A: Allocator + Clone,

1.7.0 · source§

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

source§

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

source§

impl<T> Drop for UniqueRc<T>

source§

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

source§

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

1.70.0 · source§

impl<T> Drop for OnceLock<T>

source§

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

source§

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

source§

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

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,

source§

impl<T> Drop for futures_channel::mpsc::Receiver<T>

source§

impl<T> Drop for UnboundedReceiver<T>

source§

impl<T> Drop for futures_channel::oneshot::Receiver<T>

source§

impl<T> Drop for futures_channel::oneshot::Sender<T>

source§

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

source§

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

source§

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

source§

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

source§

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

source§

impl<T> Drop for http::header::map::IntoIter<T>

source§

impl<T> Drop for http::header::map::IntoIter<T>

source§

impl<T> Drop for OnceBox<T>

source§

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

source§

impl<T> Drop for JoinHandle<T>

source§

impl<T> Drop for tokio::sync::broadcast::Receiver<T>

source§

impl<T> Drop for tokio::sync::broadcast::Sender<T>

source§

impl<T> Drop for OwnedPermit<T>

source§

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

source§

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

source§

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

source§

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

source§

impl<T> Drop for OnceCell<T>

source§

impl<T> Drop for tokio::sync::oneshot::Receiver<T>

source§

impl<T> Drop for tokio::sync::oneshot::Sender<T>

source§

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

source§

impl<T> Drop for tokio::sync::watch::Receiver<T>

source§

impl<T> Drop for tokio::sync::watch::Sender<T>

source§

impl<T> Drop for JoinSet<T>

source§

impl<T> Drop for Instrumented<T>

source§

impl<T, A> Drop for rocket::mtls::oid::asn1_rs::nom::lib::std::boxed::Box<T, A>
where A: Allocator, T: ?Sized,

1.12.0 · source§

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

source§

impl<T, A> Drop for LinkedList<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 rocket::mtls::oid::asn1_rs::nom::lib::std::collections::vec_deque::Drain<'_, T, A>
where A: Allocator,

1.6.0 · source§

impl<T, A> Drop for rocket::mtls::oid::asn1_rs::nom::lib::std::vec::Drain<'_, T, A>
where A: Allocator,

source§

impl<T, A> Drop for rocket::mtls::oid::asn1_rs::nom::lib::std::vec::IntoIter<T, A>
where A: Allocator,

source§

impl<T, A> Drop for rocket::mtls::oid::asn1_rs::nom::lib::std::vec::Vec<T, A>
where A: Allocator,

source§

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

1.4.0 · source§

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

source§

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

1.4.0 · source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

impl<T, F, A> Drop for ExtractIf<'_, 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,

source§

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

source§

impl<T, R> Drop for Once<T, R>

source§

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

source§

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

source§

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

source§

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

1.40.0 · source§

impl<T, const N: usize> Drop for core::array::iter::IntoIter<T, N>

source§

impl<W> Drop for BufWriter<W>
where W: Write + ?Sized,

source§

impl<W> Drop for base64::write::encoder::EncoderWriter<W>
where W: Write,