[−][src]Crate dispose
A small crate for handling resources that must be consumed at the end of their lifetime.
Since Rust's type system is affine rather than linear, Drop::drop
mutably borrows self
,
rather than consuming it. For the most part, this is fine, but for some cases (such as working
with the crate gfx_hal
) resources must be consumed on drop. This crate and the
dispose_derive
crate serve to cover the typical boilerplate for such cases by managing the
ManuallyDrop
wrapper for you.
As a bonus, this crate makes it easy to defer the execution of an FnOnce
closure to the end
of a scope, which can be done using the defer
function.
NOTE: The Dispose
trait does not provide a Drop
impl by itself. For that, a value
implementing Dispose
must be wrapped in a Disposable
struct.
Examples
use dispose::{Dispose, Disposable}; struct MyStruct; impl Dispose for MyStruct { fn dispose(self) { println!("Goodbye, world!"); } } { let _my_struct = Disposable::new(MyStruct); } // prints "Goodbye, world!"
As a design consideration, values implementing Dispose
should always be returned from
functions within Disposable
or any other wrapper properly implementing Drop
. Disposable
is recommended as it contains an unsafe leak
function to retrieve the inner value, if
necessary.
use dispose::{Dispose, Disposable}; mod secrets { pub struct Secrets { launch_codes: u32, } impl Secrets { pub fn new(launch_codes: u32) -> Disposable<Self> { Self { launch_codes }.into() } } impl Dispose for Secrets { fn dispose(mut self) { self.launch_codes = 0x0; } // Nice try, hackers! } } fn main() { let secret = secrets::Secrets::new(0xDEADBEEF); } // secret is properly disposed at the end of the scope fn BAD() { let secret = secrets::Secrets::new(0o1337); let mwahaha = unsafe { Disposable::leak(secret) }; } // .dispose() was not called - data has been leaked!
(My lawyers have advised me to note that the above example is not cryptographically secure. Please do not clean up secure memory by simply setting it to zero.)
Modules
prelude | Contains all the basic traits and derive macros exported by this crate. |
Structs
Disposable | Wrapper for values implementing |
Traits
Dispose | A trait representing a standard "dispose" method for consuming an object at the end of its scope. |
DisposeIterator | A helper tratif for iterators with items implementing |
DisposeIteratorWith | A helper trait for iterators with items implementing |
DisposeWith | A helper trait for objects that must be consumed with the help of another value. |
Functions
defer | Defer an action until the end of a lexical scope. |
defer_with | Defer an action until the end of a lexical scope, passing the provided argument; similar to
|
Derive Macros
Dispose | Add trivial |