remove try_ versions of the initializer macros

The `try_[pin_]init!` versions of the initializer macros are
superfluous. Instead of forcing the user to always write an error in
`try_[pin_]init!` and not allowing one in `[pin_]init!`, combine them
into `[pin_]init!` that defaults the error to
`core::convert::Infallible`, but also allows to specify a custom one.

Projects using pin-init still can provide their own defaulting
initializers using the `try_` prefix.

Signed-off-by: Benno Lossin <lossin@kernel.org>

Author: BennoLossin

README.md

@@ -135,7 +135,7 @@ struct DriverData {
 
 impl DriverData {
     fn new() -> impl PinInit<Self, Error> {
-        try_pin_init!(Self {
+        pin_init!(Self {
             status <- CMutex::new(0),
             buffer: Box::init(pin_init::init_zeroed())?,
         }? Error)

examples/linked_list.rs

@@ -6,7 +6,6 @@
 
 use core::{
     cell::Cell,
-    convert::Infallible,
     marker::PhantomPinned,
     pin::Pin,
     ptr::{self, NonNull},
@@ -31,31 +30,31 @@ pub struct ListHead {
 
 impl ListHead {
     #[inline]
-    pub fn new() -> impl PinInit<Self, Infallible> {
-        try_pin_init!(&this in Self {
+    pub fn new() -> impl PinInit<Self> {
+        pin_init!(&this in Self {
             next: unsafe { Link::new_unchecked(this) },
             prev: unsafe { Link::new_unchecked(this) },
             pin: PhantomPinned,
-        }? Infallible)
+        })
     }
 
     #[inline]
     #[allow(dead_code)]
-    pub fn insert_next(list: &ListHead) -> impl PinInit<Self, Infallible> + '_ {
-        try_pin_init!(&this in Self {
+    pub fn insert_next(list: &ListHead) -> impl PinInit<Self> + '_ {
+        pin_init!(&this in Self {
             prev: list.next.prev().replace(unsafe { Link::new_unchecked(this)}),
             next: list.next.replace(unsafe { Link::new_unchecked(this)}),
             pin: PhantomPinned,
-        }? Infallible)
+        })
     }
 
     #[inline]
-    pub fn insert_prev(list: &ListHead) -> impl PinInit<Self, Infallible> + '_ {
-        try_pin_init!(&this in Self {
+    pub fn insert_prev(list: &ListHead) -> impl PinInit<Self> + '_ {
+        pin_init!(&this in Self {
             next: list.prev.next().replace(unsafe { Link::new_unchecked(this)}),
             prev: list.prev.replace(unsafe { Link::new_unchecked(this)}),
             pin: PhantomPinned,
-        }? Infallible)
+        })
     }
 
     #[inline]

examples/pthread_mutex.rs

@@ -98,11 +98,11 @@ mod pthread_mtx {
                 // SAFETY: mutex has been initialized
                 unsafe { pin_init_from_closure(init) }
             }
-            try_pin_init!(Self {
-            data: UnsafeCell::new(data),
-            raw <- init_raw(),
-            pin: PhantomPinned,
-        }? Error)
+            pin_init!(Self {
+                data: UnsafeCell::new(data),
+                raw <- init_raw(),
+                pin: PhantomPinned,
+            }? Error)
         }
 
         #[allow(dead_code)]

src/lib.rs

@@ -146,7 +146,7 @@
 //!
 //! impl DriverData {
 //!     fn new() -> impl PinInit<Self, Error> {
-//!         try_pin_init!(Self {
+//!         pin_init!(Self {
 //!             status <- CMutex::new(0),
 //!             buffer: Box::init(pin_init::init_zeroed())?,
 //!         }? Error)
@@ -528,7 +528,7 @@ macro_rules! stack_pin_init {
 ///     x: u32,
 /// }
 ///
-/// stack_try_pin_init!(let foo: Foo = try_pin_init!(Foo {
+/// stack_try_pin_init!(let foo: Foo = pin_init!(Foo {
 ///     a <- CMutex::new(42),
 ///     b: Box::try_new(Bar {
 ///         x: 64,
@@ -555,7 +555,7 @@ macro_rules! stack_pin_init {
 ///     x: u32,
 /// }
 ///
-/// stack_try_pin_init!(let foo: Foo =? try_pin_init!(Foo {
+/// stack_try_pin_init!(let foo: Foo =? pin_init!(Foo {
 ///     a <- CMutex::new(42),
 ///     b: Box::try_new(Bar {
 ///         x: 64,
@@ -584,10 +584,10 @@ macro_rules! stack_try_pin_init {
     };
 }
 
-/// Construct an in-place, pinned initializer for `struct`s.
+/// Construct an in-place, fallible pinned initializer for `struct`s.
 ///
-/// This macro defaults the error to [`Infallible`]. If you need a different error, then use
-/// [`try_pin_init!`].
+/// The error type defaults to [`Infallible`]; if you need a different one, write `? Error` at the
+/// end, after the struct initializer.
 ///
 /// The syntax is almost identical to that of a normal `struct` initializer:
 ///
@@ -783,54 +783,10 @@ macro_rules! pin_init {
     ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? {
         $($fields:tt)*
     }) => {
-        $crate::try_pin_init!($(&$this in)? $t $(::<$($generics),*>)? {
+        $crate::pin_init!($(&$this in)? $t $(::<$($generics),*>)? {
             $($fields)*
         }? ::core::convert::Infallible)
     };
-}
-
-/// Construct an in-place, fallible pinned initializer for `struct`s.
-///
-/// If the initialization can complete without error (or [`Infallible`]), then use [`pin_init!`].
-///
-/// You can use the `?` operator or use `return Err(err)` inside the initializer to stop
-/// initialization and return the error.
-///
-/// IMPORTANT: if you have `unsafe` code inside of the initializer you have to ensure that when
-/// initialization fails, the memory can be safely deallocated without any further modifications.
-///
-/// The syntax is identical to [`pin_init!`] with the following exception: you must append `? $type`
-/// after the `struct` initializer to specify the error type you want to use.
-///
-/// # Examples
-///
-/// ```rust
-/// # #![feature(allocator_api)]
-/// # #[path = "../examples/error.rs"] mod error; use error::Error;
-/// use pin_init::{pin_data, try_pin_init, PinInit, InPlaceInit, init_zeroed};
-///
-/// #[pin_data]
-/// struct BigBuf {
-///     big: Box<[u8; 1024 * 1024 * 1024]>,
-///     small: [u8; 1024 * 1024],
-///     ptr: *mut u8,
-/// }
-///
-/// impl BigBuf {
-///     fn new() -> impl PinInit<Self, Error> {
-///         try_pin_init!(Self {
-///             big: Box::init(init_zeroed())?,
-///             small: [0; 1024 * 1024],
-///             ptr: core::ptr::null_mut(),
-///         }? Error)
-///     }
-/// }
-/// # let _ = Box::pin_init(BigBuf::new());
-/// ```
-// For a detailed example of how this macro works, see the module documentation of the hidden
-// module `macros` inside of `macros.rs`.
-#[macro_export]
-macro_rules! try_pin_init {
     ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? {
         $($fields:tt)*
     }? $err:ty) => {
@@ -847,10 +803,10 @@ macro_rules! try_pin_init {
     }
 }
 
-/// Construct an in-place initializer for `struct`s.
+/// Construct an in-place, fallible initializer for `struct`s.
 ///
-/// This macro defaults the error to [`Infallible`]. If you need a different error, then use
-/// [`try_init!`].
+/// This macro defaults the error to [`Infallible`]; if you need a different one, write `? Error`
+/// at the end, after the struct initializer.
 ///
 /// The syntax is identical to [`pin_init!`] and its safety caveats also apply:
 /// - `unsafe` code must guarantee either full initialization or return an error and allow
@@ -890,52 +846,10 @@ macro_rules! init {
     ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? {
         $($fields:tt)*
     }) => {
-        $crate::try_init!($(&$this in)? $t $(::<$($generics),*>)? {
+        $crate::init!($(&$this in)? $t $(::<$($generics),*>)? {
             $($fields)*
         }? ::core::convert::Infallible)
-    }
-}
-
-/// Construct an in-place fallible initializer for `struct`s.
-///
-/// If the initialization can complete without error (or [`Infallible`]), then use
-/// [`init!`].
-///
-/// The syntax is identical to [`try_pin_init!`]. You need to specify a custom error
-/// via `? $type` after the `struct` initializer.
-/// The safety caveats from [`try_pin_init!`] also apply:
-/// - `unsafe` code must guarantee either full initialization or return an error and allow
-///   deallocation of the memory.
-/// - the fields are initialized in the order given in the initializer.
-/// - no references to fields are allowed to be created inside of the initializer.
-///
-/// # Examples
-///
-/// ```rust
-/// # #![feature(allocator_api)]
-/// # use core::alloc::AllocError;
-/// # use pin_init::InPlaceInit;
-/// use pin_init::{try_init, Init, init_zeroed};
-///
-/// struct BigBuf {
-///     big: Box<[u8; 1024 * 1024 * 1024]>,
-///     small: [u8; 1024 * 1024],
-/// }
-///
-/// impl BigBuf {
-///     fn new() -> impl Init<Self, AllocError> {
-///         try_init!(Self {
-///             big: Box::init(init_zeroed())?,
-///             small: [0; 1024 * 1024],
-///         }? AllocError)
-///     }
-/// }
-/// # let _ = Box::init(BigBuf::new());
-/// ```
-// For a detailed example of how this macro works, see the module documentation of the hidden
-// module `macros` inside of `macros.rs`.
-#[macro_export]
-macro_rules! try_init {
+    };
     ($(&$this:ident in)? $t:ident $(::<$($generics:ty),* $(,)?>)? {
         $($fields:tt)*
     }? $err:ty) => {

tests/ring_buf.rs

@@ -166,7 +166,7 @@ pub struct EvenU64 {
 impl EvenU64 {
     #[allow(clippy::manual_is_multiple_of)]
     pub fn new2(value: u64) -> impl Init<Self, Error> {
-        try_init!(Self {
+        init!(Self {
             info: "Hello world!".to_owned(),
             data: if value % 2 == 0 {
                 value
@@ -178,7 +178,7 @@ impl EvenU64 {
 
     #[allow(clippy::manual_is_multiple_of)]
     pub fn new(value: u64) -> impl Init<Self, ()> {
-        try_init!(Self {
+        init!(Self {
             info: "Hello world!".to_owned(),
             data: if value % 2 == 0 {
                 value

tests/ui/compile-fail/init/missing_error_type.rs

@@ -5,5 +5,5 @@ struct Foo {
 }
 
 fn main() {
-    let _ = try_init!(Foo { x: Box::new(0)? }?);
+    let _ = init!(Foo { x: Box::new(0)? }?);
 }

tests/ui/compile-fail/init/missing_error_type.stderr

@@ -1,8 +1,8 @@
 error: unexpected end of macro invocation
- --> tests/ui/compile-fail/init/missing_error_type.rs:8:47
+ --> tests/ui/compile-fail/init/missing_error_type.rs:8:43
   |
-8 |     let _ = try_init!(Foo { x: Box::new(0)? }?);
-  |                                               ^ missing tokens in macro arguments
+8 |     let _ = init!(Foo { x: Box::new(0)? }?);
+  |                                           ^ missing tokens in macro arguments
   |
 note: while trying to match meta-variable `$err:ty`
  --> src/lib.rs

tests/ui/compile-fail/init/missing_field.rs

@@ -9,7 +9,7 @@ struct Foo {
 
 fn main() {
     let _foo = pin_init!(Foo { a: 0 });
-    let _foo = try_pin_init!(Foo { a: 0 }? ::std::convert::Infallible);
+    let _foo = pin_init!(Foo { a: 0 }? ::std::convert::Infallible);
     let _foo = init!(Foo { a: 0 });
-    let _foo = try_init!(Foo { a: 0 }? ::std::convert::Infallible);
+    let _foo = init!(Foo { a: 0 }? ::std::convert::Infallible);
 }

tests/ui/compile-fail/init/missing_field.stderr

@@ -5,10 +5,10 @@ error[E0063]: missing field `b` in initializer of `Foo`
    |                          ^^^ missing `b`
 
 error[E0063]: missing field `b` in initializer of `Foo`
-  --> tests/ui/compile-fail/init/missing_field.rs:12:30
+  --> tests/ui/compile-fail/init/missing_field.rs:12:26
    |
-12 |     let _foo = try_pin_init!(Foo { a: 0 }? ::std::convert::Infallible);
-   |                              ^^^ missing `b`
+12 |     let _foo = pin_init!(Foo { a: 0 }? ::std::convert::Infallible);
+   |                          ^^^ missing `b`
 
 error[E0063]: missing field `b` in initializer of `Foo`
   --> tests/ui/compile-fail/init/missing_field.rs:13:22
@@ -17,7 +17,7 @@ error[E0063]: missing field `b` in initializer of `Foo`
    |                      ^^^ missing `b`
 
 error[E0063]: missing field `b` in initializer of `Foo`
-  --> tests/ui/compile-fail/init/missing_field.rs:14:26
+  --> tests/ui/compile-fail/init/missing_field.rs:14:22
    |
-14 |     let _foo = try_init!(Foo { a: 0 }? ::std::convert::Infallible);
-   |                          ^^^ missing `b`
+14 |     let _foo = init!(Foo { a: 0 }? ::std::convert::Infallible);
+   |                      ^^^ missing `b`

tests/ui/compile-fail/init/missing_pin_data.stderr

@@ -10,4 +10,4 @@ error[E0599]: no associated item named `__pin_data` found for struct `Foo` in th
   = help: items from traits can only be used if the trait is implemented and in scope
   = note: the following trait defines an item `__pin_data`, perhaps you need to implement it:
           candidate #1: `HasPinData`
-  = note: this error originates in the macro `$crate::try_pin_init` which comes from the expansion of the macro `pin_init` (in Nightly builds, run with -Z macro-backtrace for more info)
+  = note: this error originates in the macro `$crate::pin_init` which comes from the expansion of the macro `pin_init` (in Nightly builds, run with -Z macro-backtrace for more info)