foreign 0.4.0

/// Traits to map between C structs and native Rust types.
/// Similar to glib-rs but a bit simpler and possibly more
/// idiomatic.
use std::fmt;
use std::fmt::Debug;
use std::marker::PhantomData;
use std::mem::{self, MaybeUninit};
use std::ptr;

/// A type for which there is a canonical representation as a C datum.
#[cfg_attr(
    has_diagnostic_namespace,
    diagnostic::on_unimplemented(
        message = "`{Self}` is not linked to a C representation",
        label = "needs an implementation of `FreeForeign`",
        note = "`FreeForeign` provides the corresponding C pointer type and a `free_foreign` function"
    )
)]
pub trait FreeForeign {
    /// The representation of `Self` as a C datum.  Typically a
    /// `struct`, though there are exceptions: for example `String`
    /// and `str` use `c_char` for strings, since C strings are of
    /// `char *` type.  These exceptional cases will not implement
    /// the `FixedAlloc` trait.
    type Foreign;

    /// Free the C datum pointed to by `p`, or do nothing if it is `NULL`.
    ///
    /// # Safety
    ///
    /// `p` must be `NULL` or point to valid data.
    ///
    /// ```
    /// # use foreign::{CloneToForeign, FreeForeign};
    /// let foreign = "Hello, world!".clone_to_foreign();
    /// unsafe {
    ///     String::free_foreign(foreign.into_inner());
    /// }
    /// ```
    unsafe fn free_foreign(p: *mut Self::Foreign);
}

/// A type for which a representation as a C datum can be produced.
#[cfg_attr(
    has_diagnostic_namespace,
    diagnostic::on_unimplemented(
        message = "`{Self}` cannot be copied into a C datum",
        label = "needs an implementation of `CloneToForeign`",
        note = "`clone_to_foreign` safely allocates a fresh C datum and clones `self` into it"
    )
)]
pub trait CloneToForeign: FreeForeign {
    /// Convert a native Rust object to a foreign C pointer, copying
    /// everything pointed to by `self`; return an [`OwnedPointer`]
    /// which will take care of freeing the storage (same as
    /// `to_glib_none` in `glib-rs`)
    ///
    /// The return value must be such that a call to
    /// [`free_foreign`](FreeForeign::free_foreign) will release
    /// exactly what is allocated here, without leaking memory
    /// or leaving pointers dangling.
    fn clone_to_foreign(&self) -> OwnedPointer<Self>;

    /// Convert a native Rust object to a foreign C pointer, copying
    /// everything pointed to by `self` (same as `to_glib_full`
    /// in `glib-rs`).
    ///
    /// This function is useful when C functions will take ownership
    /// of the returned pointer; alternatively, the pointer can
    /// be freed with [`free_foreign`](FreeForeign::free_foreign).
    #[must_use]
    fn clone_to_foreign_ptr(&self) -> *mut Self::Foreign {
        self.clone_to_foreign().into_inner()
    }
}

/// A type which is stored in a fixed amount of foreign memory, namely
/// `Self::FOREIGN_LEN` values of type `Self::Foreign`.
///
/// # Safety
///
/// Define this trait only if `CloneToForeign` allocates a single memory block,
/// of constant size `Self::FOREIGN_LEN * mem::size_of::<Self::Foreign>()`.
#[cfg_attr(
    has_diagnostic_namespace,
    diagnostic::on_unimplemented(
        message = "a slice, array or `Vec` of `{Self}` cannot be converted to C",
        label = "needs an implementation of `FixedAlloc`",
        note = "a slice converts its elements in place, so `{Self}` must occupy a fixed amount of foreign memory",
    )
)]
pub unsafe trait FixedAlloc: CloneToForeign + FreeForeign + Sized {
    /// How many values of type `Self::Foreign` a single `Self` occupies.
    ///
    /// This is 1 for a type that maps onto a single C datum, which is the
    /// common case and the default.  It is larger for a type that maps onto
    /// several of them, for example an array, whose `Foreign` is the *element*
    /// type; `[u8; 3]` has a `Foreign` of `u8` and a `FOREIGN_LEN` of 3.
    ///
    /// # Safety
    ///
    /// Everything that walks foreign memory an element at a time uses this
    /// as the stride, so getting it wrong writes outside the allocation.
    const FOREIGN_LEN: usize = 1;

    /// Convert a native Rust object to a foreign C struct, copying its
    /// contents to preallocated memory at `dest`.
    ///
    /// ```
    /// # use std::mem::MaybeUninit;
    /// # use foreign::FixedAlloc;
    /// let mut dest = MaybeUninit::uninit();
    /// unsafe {
    ///     u8::clone_into_foreign(dest.as_mut_ptr(), &42);
    ///     assert_eq!(dest.assume_init(), 42);
    /// }
    /// ```
    ///
    /// # Safety
    ///
    /// `dest` must be allocated and writable.
    unsafe fn clone_into_foreign(dest: *mut Self::Foreign, src: &Self);

    /// Copy the `src.len()` elements of the slice into memory at address `dest`,
    /// using [`clone_into_foreign`](FixedAlloc::clone_into_foreign) on each
    /// element.
    ///
    /// ```
    /// # use std::mem::MaybeUninit;
    /// # use foreign::FixedAlloc;
    /// let mut dest: MaybeUninit::<[u8; 3]> = MaybeUninit::uninit();
    /// unsafe {
    ///     u8::clone_from_native_slice(dest.as_mut_ptr().cast(), &[1, 2, 3]);
    ///     assert_eq!(dest.assume_init(), [1, 2, 3]);
    /// };
    /// ```
    ///
    /// # Safety
    ///
    /// `dest` must be allocated, large enough to host `src.len()` values of
    /// type `Self::Foreign`, and writable.
    unsafe fn clone_from_native_slice(mut dest: *mut Self::Foreign, src: &[Self]) {
        // SAFETY: because this type is `FixedSize`, just clone
        // in place under the assumption that `dest` is large enough.
        unsafe {
            for item in src {
                Self::clone_into_foreign(dest, item);
                dest = dest.add(Self::FOREIGN_LEN);
            }
        }
    }
}

/// A [`FixedAlloc`] type that can also be read back out of foreign memory.
///
/// This is separate from `FixedAlloc` because the two directions do not
/// have the same requirements.  Writing to C only needs to know the
/// layout, and a type that borrows can do it.  Reading back constructs a
/// `Self` out of a pointer, and
/// [`cloned_from_foreign`](FromForeign::cloned_from_foreign) takes no
/// lifetime to constrain the result with, so the caller chooses one
/// freely -- `'static` included.  A type that borrows therefore cannot
/// implement it soundly, and should implement only `FixedAlloc`.
///
/// Every type that is already [`FixedAlloc`] and [`FromForeign`] implements
/// this trait.
#[cfg_attr(
    has_diagnostic_namespace,
    diagnostic::on_unimplemented(
        message = "`{Self}` cannot be read back out of a C array",
        label = "cannot be read back out of C",
        note = "this is not implemented directly: writing to C needs only `FixedAlloc`, and \
                reading back additionally needs `FromForeign`, so implement that",
        note = "a type that borrows cannot, since `cloned_from_foreign` has no lifetime to \
                constrain its result with"
    )
)]
pub trait FixedAllocFrom: FixedAlloc + FromForeign {
    /// Copy `N` elements from memory at address `src` into a Rust array,
    /// using [`cloned_from_foreign`](FromForeign::cloned_from_foreign) on each
    /// element.
    ///
    /// ```
    /// # use std::mem::MaybeUninit;
    /// # use foreign::FixedAllocFrom;
    /// let src: [u8; 3] = [1, 2, 3];
    /// let dest: [u8; 3] = unsafe {
    ///     u8::clone_array_from_foreign(src.as_ptr())
    /// };
    /// assert_eq!(dest, src);
    /// ```
    ///
    /// # Safety
    ///
    /// `src` must be allocated, large enough to host `N` values of type
    /// `Self::Foreign`, and readable.
    unsafe fn clone_array_from_foreign<const N: usize>(mut src: *const Self::Foreign) -> [Self; N] {
        // SAFETY: `MaybeUninit<T>` has the same layout as `T`,
        // and its elements can be initialized one at a time
        unsafe {
            let mut uninit = MaybeUninit::<[Self; N]>::uninit();

            let mut dest = uninit.as_mut_ptr().cast::<Self>();
            for _ in 0..N {
                ptr::write(dest, Self::cloned_from_foreign(src));
                dest = dest.add(1);
                src = src.add(Self::FOREIGN_LEN);
            }

            // SAFETY: each element was initialized with write()
            uninit.assume_init()
        }
    }
}

impl<T: FixedAlloc + FromForeign> FixedAllocFrom for T {}

/// A type for C data that can be converted to native Rust object, taking ownership
/// of the C datum.  You should not need to implement this trait as long as the
/// Rust types implement `FromForeign`.
pub trait IntoNative<U> {
    /// Convert a C datum to a native Rust object, taking ownership of
    /// the pointer or Rust object (same as `from_glib_full` in `glib-rs`)
    ///
    /// # Safety
    ///
    /// `self` must point to valid data, or can be `NULL` if `U` is an
    /// `Option` type.  It becomes invalid after the function returns.
    ///
    /// ```
    /// # use foreign::{CloneToForeign, IntoNative};
    /// let s = "Hello, world!".to_string();
    /// let foreign = s.clone_to_foreign();
    /// let native: String = unsafe {
    ///     foreign.into_native()
    ///     // foreign is not leaked
    /// };
    /// assert_eq!(s, native);
    /// ```
    unsafe fn into_native(self) -> U;
}

impl<T, U> IntoNative<U> for *mut T
where
    U: FromForeign<Foreign = T>,
{
    unsafe fn into_native(self) -> U {
        U::from_foreign(self)
    }
}

/// A type which can be constructed from a canonical representation as a
/// C datum.
///
/// # Implementing this trait
///
/// As mentioned below, [`cloned_from_foreign`](FromForeign::cloned_from_foreign)
/// must return a `Self` that owns everything it refers to.
///
/// Therefore, a type that borrows therefore cannot implement
/// this trait at all, and is limited to [`CloneToForeign`]
/// and [`FixedAlloc`].
#[cfg_attr(
    has_diagnostic_namespace,
    diagnostic::on_unimplemented(
        message = "`{Self}` cannot be built from a C datum",
        label = "needs an implementation of `FromForeign`",
        note = "a type that borrows cannot implement this at all, since nothing in the signature constrains the lifetime of `Self`"
    )
)]
pub trait FromForeign: FreeForeign + Sized {
    /// Convert a C datum to a native Rust object, copying everything
    /// pointed to by `p` (same as `from_glib_none` in `glib-rs`)
    ///
    /// The returned value must own its contents *in their entirety*;
    /// `p` might be freed immediately, for example if `cloned_from_foreign`
    /// is called from [`from_foreign`](FromForeign::from_foreign).
    ///
    /// # Safety
    ///
    /// `p` must point to valid data, or can be `NULL` if `Self` is an
    /// `Option` type.
    ///
    /// ```
    /// # use foreign::FromForeign;
    /// let p = c"Hello, world!".as_ptr();
    /// let s = unsafe {
    ///     String::cloned_from_foreign(p as *const std::ffi::c_char)
    /// };
    /// assert_eq!(s, "Hello, world!");
    /// ```
    unsafe fn cloned_from_foreign(p: *const Self::Foreign) -> Self;

    /// Convert a C datum to a native Rust object, taking ownership of
    /// the pointer or Rust object (same as `from_glib_full` in `glib-rs`)
    ///
    /// The default implementation calls `cloned_from_foreign` and frees `p`.
    ///
    /// # Safety
    ///
    /// `p` must point to valid data, or can be `NULL` if `Self` is an
    /// `Option` type.  `p` becomes invalid after the function returns.
    ///
    /// ```
    /// # use foreign::{CloneToForeign, FromForeign};
    /// let s = "Hello, world!";
    /// let foreign = s.clone_to_foreign();
    /// unsafe {
    ///     assert_eq!(String::from_foreign(foreign.into_inner()), s);
    /// }
    /// // foreign is not leaked
    /// ```
    unsafe fn from_foreign(p: *mut Self::Foreign) -> Self {
        let result = Self::cloned_from_foreign(p);
        Self::free_foreign(p);
        result
    }
}

/// A RAII pointer that is automatically freed when it goes out of scope.
/// Note that the pointer can be NULL, and therefore is not subject
/// to niche optimization.
///
/// # Thread safety
///
/// `OwnedPointer` is neither [`Send`] not [`Sync`], as thread-safety
/// cannot be declared for all `T`.  The intended usage pattern is to
/// send Rust values across threads and convert to C in the new thread.
pub struct OwnedPointer<T: FreeForeign + ?Sized> {
    ptr: *mut <T as FreeForeign>::Foreign,
}

impl<T: FreeForeign + ?Sized> OwnedPointer<T> {
    /// Return a new `OwnedPointer` that wraps the NULL pointer.
    pub fn null_mut() -> Self {
        OwnedPointer {
            ptr: ptr::null_mut(),
        }
    }

    /// Return a new `OwnedPointer` that wraps the pointer `ptr`.
    ///
    /// # Safety
    ///
    /// The pointer must be valid and live until the returned `OwnedPointer`
    /// is dropped.
    pub unsafe fn new(ptr: *mut <T as FreeForeign>::Foreign) -> Self {
        OwnedPointer { ptr }
    }

    /// Safely create an `OwnedPointer` from one that has the same
    /// freeing function.
    ///
    /// ```
    /// # use foreign::{CloneToForeign, OwnedPointer};
    /// let s = "Hello, world!";
    /// let foreign_str = s.clone_to_foreign();
    /// let foreign_string = OwnedPointer::<String>::from(foreign_str);
    /// # assert_eq!(foreign_string.into_native(), s);
    /// ```
    pub fn from<U>(x: OwnedPointer<U>) -> Self
    where
        U: FreeForeign<Foreign = <T as FreeForeign>::Foreign> + ?Sized,
    {
        // SAFETY: the pointer type and free function are the same,
        // only the type changes
        unsafe { OwnedPointer::new(x.into_inner()) }
    }

    /// Safely convert an `OwnedPointer` into one that has the same
    /// freeing function.
    ///
    /// ```
    /// # use foreign::{CloneToForeign, OwnedPointer};
    /// let s = "Hello, world!";
    /// let foreign_str = s.clone_to_foreign();
    /// let foreign_string: OwnedPointer<String> = foreign_str.into();
    /// # assert_eq!(foreign_string.into_native(), s);
    /// ```
    pub fn into<U>(self) -> OwnedPointer<U>
    where
        U: FreeForeign<Foreign = <T as FreeForeign>::Foreign> + ?Sized,
    {
        OwnedPointer::from(self)
    }

    /// Return the pointer that is stored in the `OwnedPointer`.  The
    /// pointer is valid for as long as the `OwnedPointer` itself.
    ///
    /// ```
    /// # use foreign::CloneToForeign;
    /// let s = "Hello, world!";
    /// let foreign = s.clone_to_foreign();
    /// let p = foreign.as_ptr();
    /// let len = unsafe { libc::strlen(p) };
    /// drop(foreign);
    /// # assert_eq!(len, 13);
    /// ```
    pub fn as_ptr(&self) -> *const <T as FreeForeign>::Foreign {
        self.ptr
    }

    /// Return the pointer that is stored in the `OwnedPointer`, for
    /// use by C functions that take a non-constant pointer.  The
    /// pointer is valid for as long as the `OwnedPointer` itself.
    ///
    /// This takes `&self`, unlike [`BorrowedMutPointer::as_mut_ptr`],
    /// because the return value has no Rust reference aliases; being
    /// able to hand out a `*mut` is handy because many C APIs
    /// take a non-const pointer without mutating it.
    pub fn as_mut_ptr(&self) -> *mut <T as FreeForeign>::Foreign {
        self.ptr
    }

    /// Return the pointer that is stored in the `OwnedPointer`,
    /// consuming the `OwnedPointer` but not freeing the pointer.
    ///
    /// ```
    /// # use foreign::CloneToForeign;
    /// let s = "Hello, world!";
    /// let p = s.clone_to_foreign().into_inner();
    /// let len = unsafe { libc::strlen(p) };
    /// // p needs to be freed manually
    /// # assert_eq!(len, 13);
    /// # unsafe { libc::free(p as *mut libc::c_void); }
    /// ```
    #[must_use]
    pub fn into_inner(mut self) -> *mut <T as FreeForeign>::Foreign {
        let result = mem::replace(&mut self.ptr, ptr::null_mut());
        mem::forget(self);
        result
    }
}

impl<T: FromForeign> OwnedPointer<T> {
    /// Convert a C datum to a native Rust object, taking ownership of
    /// the pointer or Rust object (same as `from_glib_full` in `glib-rs`)
    ///
    /// ```
    /// # use foreign::{CloneToForeign, IntoNative};
    /// let s = "Hello, world!".to_string();
    /// let foreign = s.clone_to_foreign();
    /// let native: String = unsafe {
    ///     foreign.into_native()
    ///     // foreign is not leaked
    /// };
    /// assert_eq!(s, native);
    /// ```
    pub fn into_native(self) -> T {
        // SAFETY: the pointer was passed to the unsafe constructor OwnedPointer::new
        unsafe { T::from_foreign(self.into_inner()) }
    }
}

impl<T: FreeForeign + ?Sized> Debug for OwnedPointer<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let name = std::any::type_name::<T>();
        let name = format!("OwnedPointer<{name}>");
        f.debug_tuple(&name).field(&self.as_ptr()).finish()
    }
}

impl<T: CloneToForeign + Default> Default for OwnedPointer<T> {
    fn default() -> Self {
        <T as Default>::default().clone_to_foreign()
    }
}

impl<T: FreeForeign + ?Sized> Drop for OwnedPointer<T> {
    fn drop(&mut self) {
        let p = mem::replace(&mut self.ptr, ptr::null_mut());
        // SAFETY: the pointer was passed to the unsafe constructor OwnedPointer::new
        unsafe { T::free_foreign(p) }
    }
}

/// A pointer whose contents were borrowed from a Rust object, and
/// therefore whose lifetime is limited to the lifetime of the
/// underlying Rust object.  The Rust object was borrowed from a
/// shared reference, and therefore the pointer is not mutable.
pub struct BorrowedPointer<P: FreeForeign + ?Sized, T> {
    ptr: *const <P as FreeForeign>::Foreign,
    storage: T,
}

impl<P: FreeForeign + ?Sized, T> BorrowedPointer<P, T> {
    /// Return a new `BorrowedPointer` that wraps the pointer `ptr`.
    /// `storage` can contain any other data that `ptr` points to,
    /// and that should be dropped when the `BorrowedPointer` goes out
    /// of scope.
    ///
    /// # Safety
    ///
    /// The pointer must be valid for the lifetime of the `BorrowedPointer`.
    /// If the pointer points into the storage, `T` must be pinned.
    pub unsafe fn new(ptr: *const <P as FreeForeign>::Foreign, storage: T) -> Self {
        BorrowedPointer { ptr, storage }
    }

    /// Return the pointer that is stored in the `BorrowedPointer`.  The
    /// pointer is valid for as long as the `BorrowedPointer` itself.
    ///
    /// ```
    /// # use foreign::BorrowForeign;
    /// # use std::ffi::CString;
    /// let s = CString::new("Hello, world!").unwrap();
    /// let borrowed = s.borrow_foreign();
    /// let len = unsafe { libc::strlen(borrowed.as_ptr()) };
    /// # assert_eq!(len, 13);
    /// ```
    pub fn as_ptr(&self) -> *const <P as FreeForeign>::Foreign {
        self.ptr
    }

    /// Safely convert a `BorrowedPointer` into one that has the same
    /// underlying type.
    ///
    /// (Not yet sure this is useful as part of the public API).
    pub(crate) fn into<Q>(self) -> BorrowedPointer<Q, T>
    where
        Q: FreeForeign<Foreign = <P as FreeForeign>::Foreign> + ?Sized,
    {
        BorrowedPointer {
            ptr: self.ptr,
            storage: self.storage,
        }
    }

    pub(crate) fn map<Q: FreeForeign<Foreign = P::Foreign> + ?Sized, F: FnOnce(T) -> U, U>(
        self,
        f: F,
    ) -> BorrowedPointer<Q, U> {
        BorrowedPointer {
            ptr: self.ptr,
            storage: f(self.storage),
        }
    }
}

impl<P: FreeForeign + ?Sized> FreeForeign for &P {
    type Foreign = <P as FreeForeign>::Foreign;

    unsafe fn free_foreign(p: *mut Self::Foreign) {
        P::free_foreign(p)
    }
}

impl<P: CloneToForeign + ?Sized> CloneToForeign for &P {
    fn clone_to_foreign(&self) -> OwnedPointer<Self> {
        OwnedPointer::from(CloneToForeign::clone_to_foreign(&**self))
    }
}

impl<P: FreeForeign + ?Sized, T> FreeForeign for BorrowedPointer<P, T> {
    type Foreign = <P as FreeForeign>::Foreign;

    unsafe fn free_foreign(p: *mut Self::Foreign) {
        P::free_foreign(p)
    }
}

impl<P, T> CloneToForeign for BorrowedPointer<P, T>
where
    P: FreeForeign + ?Sized,
    T: CloneToForeign<Foreign = <P as FreeForeign>::Foreign>,
{
    /// Clone the underlying data for the receiver, creating a new
    /// C datum that contains the same data.
    ///
    /// The result is an `OwnedPointer<Self>` rather than an
    /// `OwnedPointer<P>`, but the two have the same `Foreign` type, so it
    /// can be used as it stands or converted with
    /// [`into()`](OwnedPointer::into).
    ///
    /// ```
    /// # use foreign::{BorrowForeign, CloneToForeign};
    /// # use std::ffi::CString;
    /// let s = CString::new("Hello, world!").unwrap();
    /// assert_eq!(s.borrow_foreign().as_ptr(), s.as_ptr());
    /// assert_ne!(s.borrow_foreign().clone_to_foreign().as_ptr(), s.as_ptr());
    /// ```
    ///
    /// ```
    /// # use foreign::{BorrowForeign, CloneToForeign};
    /// let s: i8 = 42;
    /// assert_eq!(s.borrow_foreign().as_ptr(), &s as *const _);
    /// assert_ne!(s.borrow_foreign().clone_to_foreign().as_ptr(), &s as *const _);
    /// ```
    fn clone_to_foreign(&self) -> OwnedPointer<Self> {
        OwnedPointer::from(self.storage.clone_to_foreign())
    }
}

impl<'a, P: FreeForeign + ?Sized> BorrowedPointer<P, &'a P> {
    /// Borrow `value`, with the caller's choice of the C representation for
    /// it.  `f` is handed a raw pointer to the value, and returns a pointer
    /// to the C representation.
    ///
    /// # Safety
    ///
    /// `f` must return a pointer derived from its argument, addressing the
    /// C representation of the value it points at.
    pub unsafe fn new_borrowed<F>(value: &'a P, f: F) -> Self
    where
        F: FnOnce(*const P) -> *const <P as FreeForeign>::Foreign,
    {
        let raw: *const P = value;
        let ptr = f(raw);
        // SAFETY: `ptr` is derived from `raw`, which is `value`, and that
        // same reference is kept as the storage
        unsafe { BorrowedPointer::new(ptr, value) }
    }
}

impl<P: FreeForeign + ?Sized, T> Debug for BorrowedPointer<P, T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let ptr_name = std::any::type_name::<*mut <P as FreeForeign>::Foreign>();
        let storage_name = std::any::type_name::<T>();
        let name = format!("BorrowedPointer<{ptr_name}, {storage_name}>");
        f.debug_tuple(&name).field(&self.as_ptr()).finish()
    }
}

/// A type for which a C representation can be borrowed without cloning.
#[cfg_attr(
    has_diagnostic_namespace,
    diagnostic::on_unimplemented(
        message = "`{Self}` cannot be borrowed as a C datum",
        label = "needs an implementation of `BorrowForeign`",
        note = "borrowing copies nothing, so the C representation has to be findable inside `{Self}`",
        note = "use `clone_to_foreign` if a copy is acceptable"
    )
)]
pub trait BorrowForeign: FreeForeign {
    /// The type of any extra data that are needed while the `BorrowedPointer` is alive.
    type Storage<'a>
    where
        Self: 'a;

    /// Return a wrapper for a C representation of `self`.  The wrapper
    /// borrows the data from `self` and allows access via a constant pointer.
    ///
    /// ```
    /// # use foreign::BorrowForeign;
    /// # use std::ffi::CString;
    /// let s = CString::new("Hello, world!").unwrap();
    /// let borrowed = s.borrow_foreign();
    /// let len = unsafe { libc::strlen(borrowed.as_ptr()) };
    /// # assert_eq!(len, 13);
    /// ```
    fn borrow_foreign(&self) -> BorrowedPointer<Self, Self::Storage<'_>>;
}

/// A type for which a C representation can be created by consuming the
/// Rust representation, hopefully without cloning much of the internal data.
#[cfg_attr(
    has_diagnostic_namespace,
    diagnostic::on_unimplemented(
        message = "`{Self}` cannot be consumed into a C datum",
        label = "needs an implementation of `IntoForeign`",
        note = "`into_foreign` hands its allocation to the result instead of copying, so the C representation has to be findable inside `{Self}`",
        note = "use `clone_to_foreign` if a copy is acceptable"
    )
)]
pub trait IntoForeign: FreeForeign {
    /// The type of any extra data that are needed while the `BorrowedMutPointer` is alive.
    ///
    /// Usually `Self`, though does not have to be.  For example,
    /// [into_foreign()](IntoForeign::into_foreign()) could discard the
    /// unnecessary parts of `self` or perform other conversions.  In
    /// particular, a `Cow<'_, str>` will use a `CString` as the storage.
    type Storage;

    /// Return a wrapper for a C representation of `self`.  The wrapper
    /// becomes the owner of `self` and allows access via a constant pointer.
    ///
    /// ```
    /// # use foreign::IntoForeign;
    /// let s = "Hello, world!".to_string();
    /// let borrowed = s.into_foreign();
    /// let len = unsafe { libc::strlen(borrowed.as_ptr()) };
    /// # assert_eq!(len, 13);
    /// ```
    fn into_foreign(self) -> BorrowedMutPointer<Self, Self::Storage>;
}

/// A pointer whose contents were borrowed from a Rust object, and
/// therefore whose lifetime is limited to the lifetime of the
/// underlying Rust object.  The Rust object is borrowed from an
/// exclusive reference, and therefore the pointer is mutable.
///
/// The storage must not be, or contain, a reference or a `Box` that the
/// pointer was derived from; otherwise, it is retagged whenever the
/// struct moves and this invalidates the pointer.  The easiest way
/// to avoid it for implementations of [`BorrowForeignMut`] is to use
/// [`BorrowedMutPointer::new_borrowed`].
pub struct BorrowedMutPointer<P: FreeForeign + ?Sized, T> {
    ptr: *mut <P as FreeForeign>::Foreign,
    storage: T,
}

impl<P: FreeForeign + ?Sized, T> BorrowedMutPointer<P, T> {
    /// Return a new `BorrowedMutPointer` that wraps the pointer `ptr`.
    /// `storage` can contain any other data that `ptr` points to,
    /// and that should be dropped when the `BorrowedMutPointer` goes out
    /// of scope.
    ///
    /// # Safety
    ///
    /// The pointer must be valid for the lifetime of the `BorrowedMutPointer`.
    /// If the pointer points into the storage, `T` must be pinned.
    pub unsafe fn new(ptr: *mut <P as FreeForeign>::Foreign, storage: T) -> Self {
        BorrowedMutPointer { ptr, storage }
    }

    /// Return the pointer that is stored in the `BorrowedMutPointer`.  The
    /// returned pointer is constant and is valid for as long as the
    /// `BorrowedMutPointer` itself.
    pub fn as_ptr(&self) -> *const <P as FreeForeign>::Foreign {
        self.ptr
    }

    /// Return the pointer that is stored in the `BorrowedMutPointer`.  The
    /// returned pointer is mutable and is valid for as long as the
    /// `BorrowedMutPointer` itself.
    pub fn as_mut_ptr(&mut self) -> *mut <P as FreeForeign>::Foreign {
        self.ptr
    }

    /// Safely convert a `BorrowedMutPointer` into one that has the same
    /// underlying type.
    ///
    /// (Not yet sure this is useful as part of the public API).
    pub(crate) fn into<Q>(self) -> BorrowedMutPointer<Q, T>
    where
        Q: FreeForeign<Foreign = <P as FreeForeign>::Foreign> + ?Sized,
    {
        BorrowedMutPointer {
            ptr: self.ptr,
            storage: self.storage,
        }
    }

    pub(crate) fn map<Q: FreeForeign<Foreign = P::Foreign> + ?Sized, U, F: FnOnce(T) -> U>(
        self,
        f: F,
    ) -> BorrowedMutPointer<Q, U> {
        BorrowedMutPointer {
            ptr: self.ptr,
            storage: f(self.storage),
        }
    }
}

impl<P: FreeForeign + ?Sized, T> FreeForeign for BorrowedMutPointer<P, T> {
    type Foreign = <P as FreeForeign>::Foreign;

    unsafe fn free_foreign(p: *mut Self::Foreign) {
        P::free_foreign(p)
    }
}

impl<P, T> CloneToForeign for BorrowedMutPointer<P, T>
where
    P: FreeForeign + ?Sized,
    T: CloneToForeign<Foreign = <P as FreeForeign>::Foreign>,
{
    /// Clone the underlying data for the receiver, creating a new
    /// C datum that contains the same data.
    fn clone_to_foreign(&self) -> OwnedPointer<Self> {
        OwnedPointer::from(self.storage.clone_to_foreign())
    }
}

impl<'a, P: FreeForeign + ?Sized> BorrowedMutPointer<P, BorrowedStorage<'a, P>> {
    /// Borrow `value` mutably, with the caller's choice of the C
    /// representation for it.  `f` is handed a raw pointer to the
    /// value, and returns a pointer to the C representation.
    ///
    /// Using this in the implementation of [`BorrowForeignMut`] ensures
    /// that both elements of the `BorrowedMutPointer` (the foreign pointer
    /// and the storage) share their provenance.
    ///
    /// # Safety
    ///
    /// `f` must return a pointer derived from its argument, addressing the
    /// C representation of the value it points at.
    pub unsafe fn new_borrowed<F>(value: &'a mut P, f: F) -> Self
    where
        F: FnOnce(*mut P) -> *mut <P as FreeForeign>::Foreign,
    {
        let raw: *mut P = value;
        let ptr = f(raw);
        // SAFETY: both are derived from `raw`, hence from one exclusive
        // borrow; the caller guarantees `f` did not invent the pointer.
        unsafe { BorrowedMutPointer::new(ptr, BorrowedStorage::new(raw)) }
    }
}

impl<P: FreeForeign + ?Sized, T> Debug for BorrowedMutPointer<P, T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let ptr_name = std::any::type_name::<*mut <P as FreeForeign>::Foreign>();
        let storage_name = std::any::type_name::<T>();
        let name = format!("BorrowedMutPointer<{ptr_name}, {storage_name}>");
        f.debug_tuple(&name).field(&self.as_ptr()).finish()
    }
}

/// Storage for a [`BorrowedMutPointer`] that has nothing to own.
///
/// The storage of a `BorrowedMutPointer` does two jobs: it ties the
/// pointer to the lifetime of whatever it points into, and it owns
/// anything that has to outlive the call into C.  When there is nothing
/// to own -- borrowing from a slice or an array, say -- only the first
/// job is left, and an exclusive reference is the obvious way to do it.
///
/// Miri however doesn't like it, at least in the default stacked borrows
/// model.  This is because a raw pointer derived from a reference is
/// a child of that reference's tag, and a reference stored in a struct
/// is retagged every time the struct moves.  This invalidates the
/// pointer.  Tree borrows tolerates that, but stacked borrows does not,
/// so we need to work around it.
///
/// The trick is that the reference isn't really needed; the lifetime
/// and the borrow checker are enough to guarantee soundness, therefore
/// the lifetime can be carried by a `PhantomData`.
///
/// # Why a raw pointer?
///
/// In addition to the lifetime, `BorrowedStorage` does include a
/// raw pointer to the original object.  Effectively, the exclusive
/// reference is split in its two parts, the address and the lifetime,
/// and the address is stored as a raw pointer.
///
/// The pointer makes [`BorrowedStorage`] able to retrieve the original
/// object as needed.  The pointer does not ever escape `BorrowedStorage`,
/// but it can be used within individual methods, for example to clone
/// a [`BorrowedMutPointer`] built on `BorrowedStorage`.
///
/// This requires care so that the [`BorrowedMutPointer`]'s pointer share
/// provenance; this means that the two raw pointers are derived from
/// the same `*mut`, and neither invalidates the other when written.  The
/// easiest way to ensure this is via [`BorrowedMutPointer::new_borrowed`],
/// which derives [`BorrowedMutPointer`]'s own pointer from
/// [`BorrowedStorage`]'s.
///
/// Note that all this is not needed for [`BorrowedPointer`].  Because
/// there is no `Unique` retagging going on for shared references,
/// [`BorrowedPointer::new_borrowed`] is merely a convenience so that
/// [`BorrowForeign`] and [`BorrowForeignMut`] implementations share
/// the same overall shape.
pub struct BorrowedStorage<'a, T: ?Sized> {
    ptr: *mut T,
    _marker: PhantomData<&'a mut T>,
}

impl<'a, T: ?Sized> BorrowedStorage<'a, T> {
    /// # Safety
    ///
    /// `ptr` must point to a `T` that stays valid for `'a`.  It is
    /// dereferenced -- that is the point of storing it rather than a bare
    /// [`PhantomData`] -- so this is a real requirement and not a
    /// formality.
    ///
    /// It must also share provenance with the pointer given to the
    /// accompanying [`BorrowedMutPointer::new`]: both have to be derived
    /// from the same exclusive borrow, so that writing to one leaves the
    /// other valid.  In practice that means taking one `*mut` from the
    /// `&mut self` and building both out of it:
    ///
    /// ```ignore
    /// let raw: *mut Self = self;
    /// BorrowedMutPointer::new(raw.cast::<T>(), BorrowedStorage::new(raw))
    /// ```
    ///
    /// Note that even if a `&mut` appears in between (even implicitly, through
    /// an index expression or a method taking `&mut self`), that is not
    /// undefined behavior as long as the storage is only read through.
    /// This is all this crate does, but deriving both pointers from one
    /// `*mut` via [`BorrowedMutPointer::new_borrowed`] sidesteps the issue.
    pub(crate) unsafe fn new(ptr: *mut T) -> Self {
        BorrowedStorage {
            ptr,
            _marker: PhantomData,
        }
    }
}

impl<T: FreeForeign + ?Sized> FreeForeign for BorrowedStorage<'_, T> {
    type Foreign = <T as FreeForeign>::Foreign;

    unsafe fn free_foreign(p: *mut Self::Foreign) {
        T::free_foreign(p)
    }
}

impl<T: CloneToForeign + ?Sized> CloneToForeign for BorrowedStorage<'_, T> {
    fn clone_to_foreign(&self) -> OwnedPointer<Self> {
        // SAFETY: ptr is valid for the storage's lifetime
        let p = unsafe { (*self.ptr).clone_to_foreign() };
        OwnedPointer::from(p)
    }
}

/// A type for which a C representation can be borrowed mutably without cloning.
#[cfg_attr(
    has_diagnostic_namespace,
    diagnostic::on_unimplemented(
        message = "`{Self}` cannot be borrowed mutably as a C datum",
        label = "needs an implementation of `BorrowForeignMut`",
        note = "borrowing copies nothing, so the C representation has to be findable inside `{Self}`",
        note = "use `clone_to_foreign` if a copy is acceptable"
    )
)]
pub trait BorrowForeignMut: FreeForeign {
    /// The type of any extra data that are needed while the `BorrowedMutPointer` is alive.
    ///
    /// A storage that aliases what the pointer points at must do so with a
    /// raw pointer, not a reference: writing through the accompanying
    /// pointer invalidates a reference kept beside it, and reading it
    /// afterwards is undefined behavior under stacked borrows.
    /// [`BorrowedStorage`] is that, and is what every borrowing
    /// implementation here uses.  A storage that owns the value outright,
    /// as `Box` and `Vec`'s [`IntoForeign`] do, has no such constraint.
    type Storage<'a>
    where
        Self: 'a;

    /// Return a wrapper for a C representation of `self`.  The wrapper
    /// borrows the data from `self` and allows access via a mutable pointer.
    ///
    /// # Examples
    ///
    /// ```
    /// # use foreign::BorrowForeignMut;
    /// let mut i = 123i8;
    /// let mut borrowed = i.borrow_foreign_mut();
    /// unsafe {
    ///     assert_eq!(*borrowed.as_ptr(), 123i8);
    ///     *borrowed.as_mut_ptr() = 45i8;
    /// }
    /// assert_eq!(i, 45i8);
    /// ```
    /// is analogous to:
    /// ```
    /// let mut i = 123i8;
    /// let borrowed = &mut i;
    /// assert_eq!(*borrowed, 123i8);
    /// *borrowed = 45i8;
    /// assert_eq!(i, 45i8);
    /// ```
    ///
    /// For integer types, or anything that implements [`FixedAlloc`], it is also possible
    /// to borrow from a `Vec` or array:
    ///
    /// ```
    /// # use std::ffi::{CStr, c_char};
    /// # use foreign::BorrowForeignMut;
    /// let mut v: [u8; 64] = [0; 64];
    /// # if cfg!(miri) { return; }
    /// unsafe {
    ///     libc::sprintf(v.borrow_foreign_mut().as_mut_ptr().cast::<c_char>(),
    ///                   c"hello %s".as_ptr(),
    ///                   c"world".as_ptr());
    /// }
    /// assert_eq!(CStr::from_bytes_until_nul(&v).unwrap(), c"hello world");
    /// ```
    fn borrow_foreign_mut(&mut self) -> BorrowedMutPointer<Self, Self::Storage<'_>>;
}