Trait shredder::Finalize [−][src]
pub unsafe trait Finalize { unsafe fn finalize(&mut self); }
Expand description
A trait implementing an alternative to Drop
, useful for non-GcDrop
data.
Usually when you have data in a Gc
you just want its destructor to be called when the data is
collected. However, the collector can’t naively run the drop
method of non-GcDrop
/non-'static
data, since it could access data with an elapsed lifetime. (It’s even UB to
create a reference into a struct holding an invalid reference!) We address this in two parts.
The R
and RMut
structs provide a safe alternative to holding a direct reference with a
non-’static lifetime. Then the Finalize
trait let’s you opt-in to writing unsafe code at
deallocation time.
Note: Some data is !GcDrop
even though it is 'static
, like AtomicGc
or DerefGc
. (Or
anything that contains a AtomicGc
or DerefGc
.) In those cases you will need to use
Finalize
to write destructors, and promise not touch fields of those types.
You probably want to use #[derive(Finalize)]
to implement this :)
Safety
When implementing this trait you’re promising a few things:
-
Your data does not contain any non-
'static
references. (You may useR
andRMut
instead!) -
Your
finalize
method does not access any data with a non-'static
lifetime. In particular you may not call any methods onR
orRMut
other thanfinalize
. (NoDeref
either!) -
Your
finalize
method does not call any methods on aAtomicGc
orDerefGc
. (NoDeref
either!) -
Your
finalize
method does not make anAtomicGc
,DerefGc
,R
orRMut
“live again.” Basically you must not send one of these pieces of data to another thread.
Required methods
Do cleanup on this data, potentially leaving it in an invalid state. (See trait documentation for the rules for implementing this method.)
Please ensure your finalize
implementations delegate properly and call your fields
finalize
methods after doing cleanup.
Safety
After calling this method, no further operations may be performed with this object. You
may not even drop this object! You must mem::forget
it or otherwise force its destructor
not to run.