Trait DropManually 

pub trait DropManually<FieldTy> {
    // Required method
    fn drop_manually(_: FieldTy);
}

The main/whole point of this whole crate and design: to expose owned access to a FieldTy when drop glue is being run.

• A SafeManuallyDrop<FieldTy, ContainingType>,
• with a (mandatory) impl DropManually<FieldTy> for ContainingType {,
• once it gets dropped / during its drop glue (e.g., from within a ContainingType),
• shall be running the DropManually::drop_manually() logic on that owned FieldTy.

In practice, this becomes the handy, 0-runtime-overhead, non-unsafe, tool to get owned access to a struct’s field (or group thereof) during drop glue.

Indeed, the recipe then becomes:

1. Use, instead of a field: FieldTy, a wrapped field: SafeManuallyDrop<FieldTy, ContainingType>,

   • (Usually Self can be used instead of having to spell out, verbatim, the ContainingType.)

   • (This wrapper type offers transparent Deref{,Mut}, as well as From::from() and “.into()” conversions.)

2. then, provide the companion, mandatory, impl DropManually<FieldTy> for ContainingType {

3. Profit™ from the owned access to FieldTy inside of DropManually::drop_manually()’s body.

“OverrideDropGlue” rather than PrependDropGlue

Note that this new drop glue logic for FieldTy, defined in DropManually::drop_manually(), shall supersede / override its default drop glue.

use ::safe_manually_drop::prelude::*;

pub struct MyType(SafeManuallyDrop<String, Self>);

impl DropManually<String> for MyType {
    fn drop_manually(s: String) {
        // stuff…
    } // <- unless `s` has been moved out (e.g., though `mem::forget()`),
      //    `s`' own drop glue (e.g., here, that of `String`) gets automagically
      //    invoked, rather similarly to the classic `Drop` trait.
      //    But the huge difference is that this function body had to *allow* it
      //    to happen, by not having *consumed* the owned `s: String` in some other
      //    way.
}

fn example(it: MyType) {
    drop(it); // invokes the drop glue of `MyType`,
              // i.e., the `Drop` impl `for SafeManuallyDrop<String, MyType>`
              // i.e., `<MyType as DropManually<String>>::drop_manually()`.
}

For instance: if, inside of DropManually::drop_manually(), the FieldTy is ::core::mem::forget()ten, then FieldTy’s own drop glue shall never actually run, much like when a ManuallyDrop<FieldTy> is drop()-ped/discarded.

With that being said, precisely because DropManually::drop_manually() receives an owned instance of FieldTy, this behavior is rather “opt-out”: that FieldTy owned instance runs out of scope when the function completes, so it will almost always get “dropped” / have its own drop glue being invoked.

The only exceptions are then when other, ownership-consuming, functions, get called on this value.

Typically:

• ::core::mem::forget() to skip/bypass all of the drop glue altogether.
  • note that a direct ManuallyDrop<FieldTy> would probably be better in this instance;
• an impl FnOnce() getting called (the ()-call consumes ownership);
• an owned argument S is fed to a function, such as S in an impl FnOnce(S);
• types using owned type-state patterns, most notably Transaction::{commit,roll_back}().

Required Methods

fn drop_manually(_: FieldTy)

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors