Commit 0fc4424d authored by Wedson Almeida Filho's avatar Wedson Almeida Filho Committed by Miguel Ojeda
Browse files

rust: types: introduce `ForeignOwnable` 



It was originally called `PointerWrapper`. It is used to convert
a Rust object to a pointer representation (void *) that can be
stored on the C side, used, and eventually returned to Rust.

Signed-off-by: default avatarWedson Almeida Filho <wedsonaf@gmail.com>
Reviewed-by: default avatarVincenzo Palazzo <vincenzopalazzodev@gmail.com>
Reviewed-by: default avatarMartin Rodriguez Reboredo <yakoyoku@gmail.com>
Reviewed-by: default avatarGary Guo <gary@garyguo.net>
Reviewed-by: default avatarAndreas Hindborg <a.hindborg@samsung.com>
Signed-off-by: default avatarMiguel Ojeda <ojeda@kernel.org>
parent 4d4692a2

rust/kernel/lib.rs

+1 −0
Original line number Diff line number Diff line
@@ -16,6 +16,7 @@ 
#![feature(coerce_unsized)]

#![feature(core_ffi_c)]

#![feature(dispatch_from_dyn)]

#![feature(generic_associated_types)]

#![feature(receiver_trait)]

#![feature(unsize)]

rust/kernel/types.rs

+54 −0
Original line number Diff line number Diff line
@@ -8,6 +8,60 @@ use core::{ 
    ops::{Deref, DerefMut},

};



/// Used to transfer ownership to and from foreign (non-Rust) languages.

///

/// Ownership is transferred from Rust to a foreign language by calling [`Self::into_foreign`] and

/// later may be transferred back to Rust by calling [`Self::from_foreign`].

///

/// This trait is meant to be used in cases when Rust objects are stored in C objects and

/// eventually "freed" back to Rust.

pub trait ForeignOwnable: Sized {

    /// Type of values borrowed between calls to [`ForeignOwnable::into_foreign`] and

    /// [`ForeignOwnable::from_foreign`].

    type Borrowed<'a>;



    /// Converts a Rust-owned object to a foreign-owned one.

    ///

    /// The foreign representation is a pointer to void.

    fn into_foreign(self) -> *const core::ffi::c_void;



    /// Borrows a foreign-owned object.

    ///

    /// # Safety

    ///

    /// `ptr` must have been returned by a previous call to [`ForeignOwnable::into_foreign`] for

    /// which a previous matching [`ForeignOwnable::from_foreign`] hasn't been called yet.

    /// Additionally, all instances (if any) of values returned by [`ForeignOwnable::borrow_mut`]

    /// for this object must have been dropped.

    unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> Self::Borrowed<'a>;



    /// Mutably borrows a foreign-owned object.

    ///

    /// # Safety

    ///

    /// `ptr` must have been returned by a previous call to [`ForeignOwnable::into_foreign`] for

    /// which a previous matching [`ForeignOwnable::from_foreign`] hasn't been called yet.

    /// Additionally, all instances (if any) of values returned by [`ForeignOwnable::borrow`] and

    /// [`ForeignOwnable::borrow_mut`] for this object must have been dropped.

    unsafe fn borrow_mut(ptr: *const core::ffi::c_void) -> ScopeGuard<Self, fn(Self)> {

        // SAFETY: The safety requirements ensure that `ptr` came from a previous call to

        // `into_foreign`.

        ScopeGuard::new_with_data(unsafe { Self::from_foreign(ptr) }, |d| {

            d.into_foreign();

        })

    }



    /// Converts a foreign-owned object back to a Rust-owned one.

    ///

    /// # Safety

    ///

    /// `ptr` must have been returned by a previous call to [`ForeignOwnable::into_foreign`] for

    /// which a previous matching [`ForeignOwnable::from_foreign`] hasn't been called yet.

    /// Additionally, all instances (if any) of values returned by [`ForeignOwnable::borrow`] and

    /// [`ForeignOwnable::borrow_mut`] for this object must have been dropped.

    unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self;

}



/// Runs a cleanup function/closure when dropped.

///

/// The [`ScopeGuard::dismiss`] function prevents the cleanup function from running.