Received-SPF: pass (google.com: domain of linux-kernel+bounces-131633-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) client-ip=2604:1380:45d1:ec00::1;
Date: Thu, 04 Apr 2024 14:36:42 +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 6/9] rust: list: add iterators
Message-ID: <98449574-4c1b-4281-bbd3-3ac2767020cb@proton.me>
In-Reply-To: <20240402-linked-list-v1-6-b1c59ba7ae3b@google.com>
References: <20240402-linked-list-v1-0-b1c59ba7ae3b@google.com> <20240402-linked-list-v1-6-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:
> @@ -414,3 +427,92 @@ fn drop(&mut self) {
>          }
>      }
>  }
> +
> +/// An iterator into a [`List`].
> +///
> +/// # Invariants
> +///
> +/// The `current` pointer points at a value in a list, or it is null if =
the iterator has reached

I think "list" should link to [`List`].

> +/// the end of the list. The `stop` pointer points at the first value in=
 the same list, or it is
> +/// null if the list is empty.
> +#[derive(Clone)]
> +pub struct Iter<'a, T: ?Sized + ListItem<ID>, const ID: u64 =3D 0> {
> +    current: *mut ListLinksFields,
> +    stop: *mut ListLinksFields,
> +    _ty: PhantomData<&'a ListArc<T, ID>>,
> +}
> +
> +impl<'a, T: ?Sized + ListItem<ID>, const ID: u64> Iterator for Iter<'a, =
T, ID> {
> +    type Item =3D ArcBorrow<'a, T>;
> +
> +    fn next(&mut self) -> Option<ArcBorrow<'a, T>> {
> +        if self.current.is_null() {
> +            return None;
> +        }
> +
> +        let current =3D self.current;
> +
> +        // SAFETY: We just checked that `current` is not null, so it is =
in a list, and hence not
> +        // dangling. There's no race because the iterator holds an immut=
able borrow to the list.

This (that the iterator holds an immutable borrow) is not true (there
is no `&List` field in `Iter`), but you can make that an invariant
instead.

> +        let next =3D unsafe { (*current).next };
> +        // INVARIANT: If `current` was the last element of the list, the=
n this updates it to null.
> +        // Otherwise, we update it to the next element.
> +        self.current =3D if next !=3D self.stop {
> +            next
> +        } else {
> +            ptr::null_mut()
> +        };
> +
> +        // SAFETY: The `current` pointer points a value in the list.

Typo: "points a value" -> "points at a value"

I think you should also use consistent naming when referring to the
elements/items/values of a list.

--=20
Cheers,
Benno

> +        let item =3D unsafe { T::view_value(ListLinks::from_fields(curre=
nt)) };
> +        // 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 list. However, the `ArcBorrow` is annotated w=
ith the iterator's
> +        //   lifetime, and the list is immutably borrowed for that lifet=
ime.
> +        // * Values in a list never have a `UniqueArc` reference.
> +        Some(unsafe { ArcBorrow::from_raw(item) })
> +    }
> +}