Date:   Fri, 27 Jan 2023 13:55:33 +0000
From:   Gary Guo <gary@garyguo.net>
To:     Wedson Almeida Filho <wedsonaf@gmail.com>
Cc:     rust-for-linux@vger.kernel.org, Miguel Ojeda <ojeda@kernel.org>,
        Alex Gaynor <alex.gaynor@gmail.com>,
        Boqun Feng <boqun.feng@gmail.com>,
        =?UTF-8?B?QmrDtnJu?= Roy Baron <bjorn3_gh@protonmail.com>,
        linux-kernel@vger.kernel.org
Subject: Re: [PATCH 2/5] rust: types: introduce `ForeignOwnable`
Message-ID: <20230127135533.3dfc7440.gary@garyguo.net>
In-Reply-To: <20230119174036.64046-2-wedsonaf@gmail.com>
References: <20230119174036.64046-1-wedsonaf@gmail.com>
        <20230119174036.64046-2-wedsonaf@gmail.com>
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?cbqTANkTol3U/eW5x2j9GI6I6sVk6E9gmShROTIb94IVhETIon+NnYQ/XeDk?=
 =?us-ascii?Q?zuQ/d6OKLkaZw6Km5C9jPr8ocO9DSwXh81jEtCV+BrJBshZ3/RudYUL5ZRF7?=
 =?us-ascii?Q?luDZBE645ZZCMDn4iXkDxR81pwhfTA+CFNg3l5y0Jc9bc6ox6PsNfl/B6IjM?=
 =?us-ascii?Q?CwXANckAikXJULrsqksjJKQheTHfkdWDMC68YA/g05wsjAVMAecPvI8rIpbl?=
 =?us-ascii?Q?Sr96f9dUOwPvzzxdWvjGKvttgW3Yoin/adQ5XSZcTeacrQxjhYfOU2Da58Em?=
 =?us-ascii?Q?Bc7d+I7IGCUsQ7ZSGH1uh3IkYwAgoi9dbm4MANf1Yw2xlUGBzv0PobDZL2Cf?=
 =?us-ascii?Q?nxgjMWwVoCk2dWlbbVbJG+AkKGbjP9Mfwu+zqn9zuwiqJMv++mOO6LcCStlq?=
 =?us-ascii?Q?HUOMl1Pczp9nseuTDLARFOSXql0GCa1qaViTwLxwn9+xEWxSizE+Pj0Q2eVN?=
 =?us-ascii?Q?cudyDWSx/lXq4ovd/OHByW+PDMPy8AGvhUELBFa9lIxRSrRoql50uadBCjtA?=
 =?us-ascii?Q?nJ2idNr6uAZ06FMJLkuqP7vMozC0WagwbWdTS+ZNQtz7kan/R3+uRMFLF1tU?=
 =?us-ascii?Q?ggfCHnNHDH8D4WI3kqh9nGwrqTxwPbXrfDRtozm6S0qo1X8YQXM2L/4JF202?=
 =?us-ascii?Q?GNMKLoShwlcoKkY6FU7GkZgyfAX9Otu4GTl4mXu8yaZHKHN4GuGTt62NDVFn?=
 =?us-ascii?Q?E4MDuClGjmmwLYG3/TFCzH/75itm9ymo6bJQtvwNQvn1uKqkVFPLuP/olSmz?=
 =?us-ascii?Q?9s8IA3YmSO1q+9tuiUTQePEBL/hHdtnEHuUcmF1X8kXadO/QlfwdcswH+QFG?=
 =?us-ascii?Q?SwGx3Y2Hv2+4LZhRu9K1nsgJtnkd8gHyb1vNglV1zp8ew7RG3hs3gCdndgYy?=
 =?us-ascii?Q?ChmQQdNRMMwX40Uh2yPzEAvjnufQg+jEwXGRHGAi5X8jafNsPEOmeMIV7VjH?=
 =?us-ascii?Q?rUJtaS5XI+rSaIi7K0Qmq9cwURwNBWpxbopIQ+QHqOG5D1IwoFPcA4AFULGs?=
 =?us-ascii?Q?yVwwF0V1AobFC2b4LdA58wc5MtxqR++nc0qcpYbIXWjFhIGaPv0E6bmuCWqR?=
 =?us-ascii?Q?3IDX8l30MSNZj1O+6XYFcAqgp/q2T6dzVRHUX2lMvBY6Dw1ZwlWffmK4ednw?=
 =?us-ascii?Q?iS4M8MLaqjYZ/k1BbHzZf1E8CG7D2TSO5VS+bWAkHuu4jv+Vrk3wHKQqukdy?=
 =?us-ascii?Q?8IqUAsnjTQklJ3vJzuXwcD+7wK/Bj9lSbHVeoM9RqtN+YtysdlUr37q7ZHEI?=
 =?us-ascii?Q?XANYTahjVEAVrdyXf4sTbZZqJMN1HkrGMg/c5b/Ea/+/2YdrfURj1WJP5rPM?=
 =?us-ascii?Q?KMgcvJ9zKtVHvq5vJ2KeUV/5sTSH86G+a5U8TcxJMxE4LT5CREYF01T6Txdy?=
 =?us-ascii?Q?lNoeKOLP3/UMNdiG2F3DSnROW3XkkYykZ5Ux0zh5nYHFsf7A9mb9gJAfETj0?=
 =?us-ascii?Q?1+ffyk5nuOKJSbjq2jzE3v3TmYi47XCu0wNaqixOPrSOdlxuzETT3h9zYLpo?=
 =?us-ascii?Q?yUFGqDfQh2CQ4osRpqxoq6LMXEySzSWJF6o07wTEUjmXOuHhDdYdYS3GCkU9?=
 =?us-ascii?Q?CRFxCsy1C9paB5YD2L9ghbm0fVnoDQ4p7Ue+pvdc?=
X-OriginatorOrg: garyguo.net
X-MS-Exchange-CrossTenant-Network-Message-Id: b2d32981-d9a1-413b-7155-08db006e2be6
X-MS-Exchange-CrossTenant-AuthSource: LO2P265MB5183.GBRP265.PROD.OUTLOOK.COM
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 27 Jan 2023 13:55:38.9419
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: bbc898ad-b10f-4e10-8552-d9377b823d45
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: LMMgSxMO/zlETaeyogczCa1WW8N70PopyopSROdIKeOar4Ef5dFews9Ca36VPEwhcO65owPfI7AkW9S+3zJKnw==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: CWLP265MB2340
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

On Thu, 19 Jan 2023 14:40:33 -0300
Wedson Almeida Filho <wedsonaf@gmail.com> wrote:

> 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: Wedson Almeida Filho <wedsonaf@gmail.com>
> ---
>  rust/kernel/lib.rs   |  1 +
>  rust/kernel/types.rs | 54 ++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 55 insertions(+)
> 
> diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
> index e0b0e953907d..223564f9f0cc 100644
> --- a/rust/kernel/lib.rs
> +++ b/rust/kernel/lib.rs
> @@ -16,6 +16,7 @@
>  #![feature(coerce_unsized)]
>  #![feature(core_ffi_c)]
>  #![feature(dispatch_from_dyn)]
> +#![feature(generic_associated_types)]
>  #![feature(receiver_trait)]
>  #![feature(unsize)]
>  
> diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
> index f0ad4472292d..5475f6163002 100644
> --- a/rust/kernel/types.rs
> +++ b/rust/kernel/types.rs
> @@ -9,6 +9,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 {
> +    /// 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<T: ForeignOwnable>(ptr: *const core::ffi::c_void) -> ScopeGuard<T, fn(T)> {

I feel that this should could its own guard (maybe `PointerGuard`?) to
be more semantically meaningful than a `ScopeGuard`.

> +        // SAFETY: The safety requirements ensure that `ptr` came from a previous call to
> +        // `into_foreign`.
> +        ScopeGuard::new_with_data(unsafe { T::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.