::drop-with-owned-fields

Safe and sound owned access to a struct's fields in Drop: no more unsafe usage of ManuallyDrop!

The #[drop_with_owned_fields] attribute of this crate automates and encapsulates the process of wrapping the fields of a struct in ManuallyDrop, which is typically needed when having the intention to drop()-in-place a certain field before others are, or when actually needing to take full, owned, access to that field. These two operations are unsafe, despite the notorious soundness of the whole pattern, which is quite unfortunate. The objective of this crate is to properly identify and automate this "notoriously sound" pattern, so as to expose a safe and sound API for users to take advantage of, with all the power of the type system supporting them and gently nudging them away from bugs.

Examples

Example: Defer<impl FnOnce()>

Take, for instance, the following, rather typical, example:

struct Defer<F: FnOnce()> {
    f: F,
};

impl<F: FnOnce()> Drop for Defer<F> {
    fn drop(&mut self) {
        (self.f)() // Error, cannot move out of `self.f` which is behind a mutable reference
    }
}

Alas, our usage of the correct FnOnce() bound (since we only need to call it once) has made this snippet fail!

• Full error message:

  Click to show

  # /*
  error[E0507]: cannot move out of `self.f` which is behind a mutable reference
   --> src/_lib.rs:37:9
    |
  7 |         (self.f)()
    |         ^^^^^^^^--
    |         |
    |         `self.f` moved due to this call
    |         move occurs because `self.f` has type `F`, which does not implement the `Copy` trait
    |
  note: this value implements `FnOnce`, which causes it to be moved when called
   --> src/_lib.rs:37:9
    |
  7 |         (self.f)()
    |         ^^^^^^^^
  # */
  

Enter #[drop_with_owned_fields]:

# fn main() {}
#
use ::drop_with_owned_fields::drop_with_owned_fields;

#[drop_with_owned_fields]
struct Defer<F: FnOnce()> {
    f: F,
}

#[drop_with_owned_fields]
impl<F: FnOnce()> Drop for Defer<F> {
    fn drop(Self { f }: _) {
        f(); // ✅
    }
}

Note that the second usage of #[drop_with_owned_fields] on that impl Drop block is only supported by enabling the "drop-sugar" feature of the crate, which shall, in turn, enable the "full" features of ::syn (resulting in a slightly higher from-scratch compile-time, should no other crate in the dependency tree have enabled it already).

Without it, the Drop block and logic would have had to be spelled out a bit more explicitly, like so:

# fn main() {}
#
use ::drop_with_owned_fields::prelude::*;

#[drop_with_owned_fields]
struct Defer<F: FnOnce()> { f: F }

impl<F: FnOnce()> DropWithOwnedFields for Defer<F> {
    fn drop(DestructuredFieldsOf::<Self> { f }: DestructuredFieldsOf<Self>) {
        f(); // ✅
    }
}

# fn main() {}
#
use ::drop_with_owned_fields::prelude::*;

#[drop_with_owned_fields]
struct Defer<F: FnOnce()> { f: F }

impl<F: FnOnce()> DropWithOwnedFields for Defer<F> {
    fn drop(this: DestructuredFieldsOf<Self>) {
        if true {
            // One approach…
            (this.f)(); // ✅
        } else {
            // …or another.
            let DestructuredFieldsOf::<Self> { f } = this;
            f(); // ✅
        }
    }
}

If you forget to impl DropWithOwnedFields (with or without sugar), like so:

# use ::drop_with_owned_fields::drop_with_owned_fields;
#
#[drop_with_owned_fields]
struct Example {
    // …
}
#
# fn main() {}

you will then get the following compiler error message:

# /*
error[E0277]: the trait bound `Example: DropWithOwnedFields` is not satisfied
 --> src/_lib.rs:130:1
  |
6 | #[drop_with_owned_fields]
  | ^^^^^^^^^^^^^^^^^^^^^^^^^ the trait `DropWithOwnedFields` is not implemented for `Example`
  |
  = note: The `#[drop_with_owned_fields]` annotation expects 🫵 you to provide a companion `impl` of `DropWithOwnedFields` (the whole point!).

          If you have enabled the `"drop-sugar"` Cargo feature, you can even write a direct `impl` of `Drop` instead, but with a `#[drop_with_owned_fields]` annotation on top of it.

  = note: this error originates in the attribute macro `drop_with_owned_fields` (...)
# */

Example: .transaction.commit() in Drop

use ::drop_with_owned_fields::drop_with_owned_fields;

use example_lib::Transaction;
// where:
mod example_lib {
    pub struct Transaction {
        // …
    }

    impl Transaction {
        /// Owned access required for stronger type-safety 👌
        pub fn commit(self) {
            // …
        }
    }
}

#[drop_with_owned_fields]
struct CommitOnDrop {
    txn: Transaction,
}

#[drop_with_owned_fields]
impl Drop for CommitOnDrop {
    fn drop(Self { txn }: _) {
        txn.commit(); // ✅
    }
}
#
# fn main() {}

Unsugaring

Taking the Defer<F> example, for instance, but renamed as Foo:

#[::drop_with_owned_fields::drop_with_owned_fields]
impl<F: FnOnce()> Drop for Foo<F> {
    fn drop(Self { f }: _) {
        f();
    }
}

#[::drop_with_owned_fields::drop_with_owned_fields]
struct Foo<F: FnOnce()> {
    f: F,
}
#
# fn main() {}

unsugars to code along the following lines (papering over robust namespacing and privacy):

# use ::core::{mem::ManuallyDrop, ops::{Deref, DerefMut}};
# use ::drop_with_owned_fields::prelude::*;
#
/// Unsugaring of the `Drop` impl.
impl<F: FnOnce()> DropWithOwnedFields for Foo<F> {
    fn drop(FooFields { f }: FooFields<F>) {
        f();
    }
}

// == Unsugaring of the `struct Foo` definition: ==

struct FooFields<F: FnOnce()> {
    f: F,
}

/// This is what makes `DestructuredFieldsOf<Foo<F>> == FooFields<F>`.
impl<F: FnOnce()> ::drop_with_owned_fields::DestructureFields for Foo<F> {
    type DestructuredFields = FooFields<F>;
    # fn destructure_fields_disabling_extra_drop(self) -> Self::DestructuredFields { todo!() }
}
# impl<F: FnOnce()> ::drop_with_owned_fields::ඞ::drop_with_owned_fields_annotation for Foo<F> {}

// The `ManuallyDrop` unsafe-but-sound pattern!
struct Foo<F: FnOnce()> {
    // real fields no longer in the `struct`, but moved to the companion `SelfFields` data type!
    // 👇
    manually_drop_fields: ManuallyDrop<FooFields<F>>,
}
impl<F: FnOnce()> Drop for Foo<F>
where
# /*
    // This is what makes the real `impl Drop` use and require your `DropWithOwned` logic
    //     👇
    Self : DropWithOwnedFields,
# */
{
    fn drop(&mut self) {
        let fields = unsafe {
            ManuallyDrop::take(&mut self.manually_drop_fields)
        };
        <Self as DropWithOwnedFields>::drop(fields);
    }
}

// -- Niceties --

// -- 1. `.field_name` access sugar:
impl<F: FnOnce()> Deref for Foo<F> {
    type Target = FooFields<F>;
    // …
    # fn deref(&self) -> &FooFields<F> { &self.manually_drop_fields }
}
// Ditto for `DerefMut`

# #[cfg(any())]
// -- 2. Constructor builder/helper
impl<F: FnOnce()> Into<Foo<F>> for FooFields<F> {
    // ...
}
#
# fn main() {}

Mainly, notice the very important addition of a "companion struct": FooFields<F>:

The companion struct FooFields<…>

This is the struct containing all of the fields laid out as they initially were for the original Foo definition. The trick having been about splitting the original Foo definition (as input to the macro) into two struct definitions:

• the FooFields<…> "copy", which has the fields but has no extra/customized Drop glue nor impl whatsoever.

• the Foo<…> original type, which does have the desired extra/customized Drop impl, but in exchange of that it had to forsake carrying the fields directly, using a ManuallyDrop<FooFields<…>> layer instead.

More generally, for every StructName<Generics…>, there shall be a companion StructNameFields<Generics…> definition.

• There is a way to make the attribute name this data structure as you desire: its default name can thus be overridden;

• otherwise, the default name is currently left unspecified (and will probably involve some ඞ sigil somewhere in the name to communicate this fact and deter from direct usage).

  Instead, the DestructureFields trait can be used, especially its DestructuredFields associated type.

  Or the convenience DestructuredFieldsOf<_> type alias:

  DestructuredFieldsOf<Foo<F>> = <Foo<F> as DestructureFields>::DestructuredFields
                               = FooFields<F>
  

  This yields a properly specified and usable type name.

It is guaranteed to have the same fields as the original Foo definition, in terms of:

• deconstructing and/or accessing these fields in Drop of Deref{,Mut};
• constructing this FooFields { … } instance, which, as we are about to see, shall be not only handy but paramount for the instantiation of a Foo { … } value.

Braced literal construction of Foo { … }

It is not longer available once the #[drop_with_owned_fields] pass has happened onto Foo's definition.

Indeed, instead, we have something along the lines of:

struct Foo<F> {
    manually_drop_fiels: ManuallyDrop<FooFields<F>>,
}

• (with .manually_drop_fields being a field name left private);

This, obviously, prevents the "typical" braced-struct-literal construction of a Foo { … }.

# use ::core::mem::ManuallyDrop;
#
struct FooFields<F: FnOnce()> { f: F }

struct Foo<F: FnOnce()> {
    manually_drop_fiels: ManuallyDrop<FooFields<F>>,
}

let _foo = Foo {
    f: || (),
};

# /*
error[E0560]: struct `Foo<_>` has no field named `f`
  --> src/_lib.rs:392:5
   |
12 |     f: || (),
   |     ^ `Foo<_>` does not have this field
   |
# */

Instead, the workaround is to involve the perfectly-available braced-struct-literal construction of the FooFields { … } struct and its eponymous fields, and then simply call .into() to convert it "back" into a Foo { … }:

use ::drop_with_owned_fields::prelude::*;

#[drop_with_owned_fields]
pub struct Defer<F: FnOnce()> {
    f: F,
}

#[drop_with_owned_fields]
impl<F: FnOnce()> Drop for Defer<F> {
    fn drop(Self { f }: _) {
        f();
    }
}

impl<F: FnOnce()> Defer<F> {
    pub fn new(f: F) -> Self {
        DestructuredFieldsOf::<Self> { f }.into() // 👈
    }
}

fn main() {
    let _defer = Defer::new(|| println!("General Kenobi."));
    println!("Hello, there!");
}

Renaming the companion struct

Since having to type DestructuredFieldsOf<Foo<F>> all the time can be deemed cumbersome, and noisy, the #[drop_with_owned_fields] attribute accepts an optional attribute arg to:

• both override the name of that companion struct,
• and adjust its visibility so that it be allowed to be fully public should the author with so:

use ::drop_with_owned_fields::prelude::*;

#[drop_with_owned_fields(
    pub type FooFields = DestructuredFieldsOf<Self>,
)]
pub struct Foo<F: FnOnce()> { f: F }

impl<F: FnOnce()> DropWithOwnedFields for Foo<F> {
    fn drop(FooFields { f }: FooFields<F>) {
        f(); // ✅
    }
}
#
# fn main() {}