Received-SPF: pass (google.com: domain of linux-kernel+bounces-129711-linux.lists.archive=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) client-ip=147.75.199.223;
Date: Wed, 03 Apr 2024 12:19:38 +0000
To: Alice Ryhl <aliceryhl@google.com>, Miguel Ojeda <ojeda@kernel.org>, Andrew Morton <akpm@linux-foundation.org>
From: Benno Lossin <benno.lossin@proton.me>
Cc: Alex Gaynor <alex.gaynor@gmail.com>, Wedson Almeida Filho <wedsonaf@gmail.com>, Boqun Feng <boqun.feng@gmail.com>, Gary Guo <gary@garyguo.net>, =?utf-8?Q?Bj=C3=B6rn_Roy_Baron?= <bjorn3_gh@protonmail.com>, Andreas Hindborg <a.hindborg@samsung.com>, Marco Elver <elver@google.com>, Kees Cook <keescook@chromium.org>, Coly Li <colyli@suse.de>, Paolo Abeni <pabeni@redhat.com>, Pierre Gondois <pierre.gondois@arm.com>, Ingo Molnar <mingo@kernel.org>, Jakub Kicinski <kuba@kernel.org>, Wei Yang <richard.weiyang@gmail.com>, Matthew Wilcox <willy@infradead.org>, linux-kernel@vger.kernel.org, rust-for-linux@vger.kernel.org
Subject: Re: [PATCH 7/9] rust: list: add cursor
Message-ID: <4aaf7fd7-49ed-4b3e-b691-0d8d7d426d3a@proton.me>
In-Reply-To: <20240402-linked-list-v1-7-b1c59ba7ae3b@google.com>
References: <20240402-linked-list-v1-0-b1c59ba7ae3b@google.com> <20240402-linked-list-v1-7-b1c59ba7ae3b@google.com>
Feedback-ID: 71780778:user:proton
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable

On 02.04.24 14:17, Alice Ryhl wrote:
> diff --git a/rust/kernel/list.rs b/rust/kernel/list.rs
> index 892705dd0571..47e52818c7bd 100644
> --- a/rust/kernel/list.rs
> +++ b/rust/kernel/list.rs
> @@ -408,6 +408,20 @@ pub fn push_all_back(&mut self, other: &mut List<T, =
ID>) {
>          other.first =3D ptr::null_mut();
>      }
>=20
> +    /// Returns a cursor to the first element of the list.
> +    ///
> +    /// If the list is empty, this returns `None`.
> +    pub fn cursor_front(&mut self) -> Option<Cursor<'_, T, ID>> {
> +        if self.first.is_null() {
> +            None
> +        } else {
> +            Some(Cursor {

Missing INVARIANT comment.

> +                current: self.first,
> +                list: self,
> +            })
> +        }
> +    }
> +
>      /// Creates an iterator over the list.
>      pub fn iter(&self) -> Iter<'_, T, ID> {
>          // INVARIANT: If the list is empty, both pointers are null. Othe=
rwise, both pointers point
> @@ -476,6 +490,69 @@ fn next(&mut self) -> Option<ArcBorrow<'a, T>> {
>      }
>  }
>=20
> +/// A cursor into a [`List`].
> +///
> +/// # Invariants
> +///
> +/// The `current` pointer points a value in `list`.
> +pub struct Cursor<'a, T: ?Sized + ListItem<ID>, const ID: u64 =3D 0> {
> +    current: *mut ListLinksFields,
> +    list: &'a mut List<T, ID>,
> +}
> +
> +impl<'a, T: ?Sized + ListItem<ID>, const ID: u64> Cursor<'a, T, ID> {
> +    /// Access the current element of this cursor.
> +    pub fn current(&self) -> ArcBorrow<'_, T> {
> +        // SAFETY: The `current` pointer points a value in the list.
> +        let me =3D unsafe { T::view_value(ListLinks::from_fields(self.cu=
rrent)) };
> +        // SAFETY:
> +        // * All values in a list are stored in an `Arc`.
> +        // * The value cannot be removed from the list for the duration =
of the lifetime annotated
> +        //   on the returned `ArcBorrow`, because removing it from the l=
ist would require mutable
> +        //   access to the cursor or the list. However, the `ArcBorrow` =
holds an immutable borrow
> +        //   on the cursor, which in turn holds an immutable borrow on t=
he list, so any such

The cursor has a mutable borrow on the list.


> +        //   mutable access requires first releasing the immutable borro=
w on the cursor.
> +        // * Values in a list never have a `UniqueArc` reference.

Is there some type invariant guaranteeing this?

--=20
Cheers,
Benno

> +        unsafe { ArcBorrow::from_raw(me) }
> +    }
> +
> +    /// Move the cursor to the next element.
> +    pub fn next(self) -> Option<Cursor<'a, T, ID>> {
> +        // SAFETY: The `current` field is always in a list.
> +        let next =3D unsafe { (*self.current).next };
> +
> +        if next =3D=3D self.list.first {
> +            None
> +        } else {
> +            Some(Cursor {
> +                current: next,
> +                list: self.list,
> +            })
> +        }
> +    }