Skip to content

Commit a480263

Browse files
Darksonnojeda
Darksonn
authored and
ojeda
committed
rust: list: add tracking for ListArc
Add the ability to track whether a ListArc exists for a given value, allowing for the creation of ListArcs without going through UniqueArc. The `impl_list_arc_safe!` macro is extended with a `tracked_by` strategy that defers the tracking of ListArcs to a field of the struct. Additionally, the AtomicListArcTracker type is introduced, which can track whether a ListArc exists using an atomic. By deferring the tracking to a field of type AtomicListArcTracker, structs gain the ability to create ListArcs without going through a UniqueArc. Rust Binder uses this for some objects where we want to be able to insert them into a linked list at any time. Using the AtomicListArcTracker, we are able to check whether an item is already in the list, and if not, we can create a `ListArc` and push it. The macro has the ability to defer the tracking of ListArcs to a field, using whatever strategy that field has. Since we don't add any strategies other than AtomicListArcTracker, another similar option would be to hard-code that the field should be an AtomicListArcTracker. However, Rust Binder has a case where the AtomicListArcTracker is not stored directly in the struct, but in a sub-struct. Furthermore, the outer struct is generic: struct Wrapper<T: ?Sized> { links: ListLinks, inner: T, } Here, the Wrapper struct implements ListArcSafe with `tracked_by inner`, and then the various types used with `inner` also uses the macro to implement ListArcSafe. Some of them use the untracked strategy, and some of them use tracked_by with an AtomicListArcTracker. This way, Wrapper just inherits whichever choice `inner` has made. Reviewed-by: Benno Lossin <benno.lossin@proton.me> Signed-off-by: Alice Ryhl <aliceryhl@google.com> Link: https://lore.kernel.org/r/20240814-linked-list-v5-3-f5f5e8075da0@google.com Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
1 parent 6cd3417 commit a480263

File tree

2 files changed

+170
-3
lines changed

2 files changed

+170
-3
lines changed

‎rust/kernel/list.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,4 @@
55
//! A linked list implementation.
66
77
mod arc;
8-
pub use self::arc::{impl_list_arc_safe, ListArc, ListArcSafe};
8+
pub use self::arc::{impl_list_arc_safe, AtomicTracker, ListArc, ListArcSafe, TryNewListArc};

‎rust/kernel/list/arc.rs

Lines changed: 169 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,10 @@
77
use crate::alloc::{AllocError, Flags};
88
use crate::prelude::*;
99
use crate::sync::{Arc, ArcBorrow, UniqueArc};
10-
use core::marker::Unsize;
10+
use core::marker::{PhantomPinned, Unsize};
1111
use core::ops::Deref;
1212
use core::pin::Pin;
13+
use core::sync::atomic::{AtomicBool, Ordering};
1314

1415
/// Declares that this type has some way to ensure that there is exactly one `ListArc` instance for
1516
/// this id.
@@ -48,9 +49,38 @@ pub trait ListArcSafe<const ID: u64 = 0> {
4849
unsafe fn on_drop_list_arc(&self);
4950
}
5051

52+
/// Declares that this type is able to safely attempt to create `ListArc`s at any time.
53+
///
54+
/// # Safety
55+
///
56+
/// The guarantees of `try_new_list_arc` must be upheld.
57+
pub unsafe trait TryNewListArc<const ID: u64 = 0>: ListArcSafe<ID> {
58+
/// Attempts to convert an `Arc<Self>` into an `ListArc<Self>`. Returns `true` if the
59+
/// conversion was successful.
60+
///
61+
/// This method should not be called directly. Use [`ListArc::try_from_arc`] instead.
62+
///
63+
/// # Guarantees
64+
///
65+
/// If this call returns `true`, then there is no [`ListArc`] pointing to this value.
66+
/// Additionally, this call will have transitioned the tracking inside `Self` from not thinking
67+
/// that a [`ListArc`] exists, to thinking that a [`ListArc`] exists.
68+
fn try_new_list_arc(&self) -> bool;
69+
}
70+
5171
/// Declares that this type supports [`ListArc`].
5272
///
53-
/// When using this macro, it will only be possible to create a [`ListArc`] from a [`UniqueArc`].
73+
/// This macro supports a few different strategies for implementing the tracking inside the type:
74+
///
75+
/// * The `untracked` strategy does not actually keep track of whether a [`ListArc`] exists. When
76+
/// using this strategy, the only way to create a [`ListArc`] is using a [`UniqueArc`].
77+
/// * The `tracked_by` strategy defers the tracking to a field of the struct. The user much specify
78+
/// which field to defer the tracking to. The field must implement [`ListArcSafe`]. If the field
79+
/// implements [`TryNewListArc`], then the type will also implement [`TryNewListArc`].
80+
///
81+
/// The `tracked_by` strategy is usually used by deferring to a field of type
82+
/// [`AtomicTracker`]. However, it is also possible to defer the tracking to another struct
83+
/// using also using this macro.
5484
#[macro_export]
5585
macro_rules! impl_list_arc_safe {
5686
(impl$({$($generics:tt)*})? ListArcSafe<$num:tt> for $t:ty { untracked; } $($rest:tt)*) => {
@@ -61,6 +91,39 @@ macro_rules! impl_list_arc_safe {
6191
$crate::list::impl_list_arc_safe! { $($rest)* }
6292
};
6393

94+
(impl$({$($generics:tt)*})? ListArcSafe<$num:tt> for $t:ty {
95+
tracked_by $field:ident : $fty:ty;
96+
} $($rest:tt)*) => {
97+
impl$(<$($generics)*>)? $crate::list::ListArcSafe<$num> for $t {
98+
unsafe fn on_create_list_arc_from_unique(self: ::core::pin::Pin<&mut Self>) {
99+
$crate::assert_pinned!($t, $field, $fty, inline);
100+
101+
// SAFETY: This field is structurally pinned as per the above assertion.
102+
let field = unsafe {
103+
::core::pin::Pin::map_unchecked_mut(self, |me| &mut me.$field)
104+
};
105+
// SAFETY: The caller promises that there is no `ListArc`.
106+
unsafe {
107+
<$fty as $crate::list::ListArcSafe<$num>>::on_create_list_arc_from_unique(field)
108+
};
109+
}
110+
unsafe fn on_drop_list_arc(&self) {
111+
// SAFETY: The caller promises that there is no `ListArc` reference, and also
112+
// promises that the tracking thinks there is a `ListArc` reference.
113+
unsafe { <$fty as $crate::list::ListArcSafe<$num>>::on_drop_list_arc(&self.$field) };
114+
}
115+
}
116+
unsafe impl$(<$($generics)*>)? $crate::list::TryNewListArc<$num> for $t
117+
where
118+
$fty: TryNewListArc<$num>,
119+
{
120+
fn try_new_list_arc(&self) -> bool {
121+
<$fty as $crate::list::TryNewListArc<$num>>::try_new_list_arc(&self.$field)
122+
}
123+
}
124+
$crate::list::impl_list_arc_safe! { $($rest)* }
125+
};
126+
64127
() => {};
65128
}
66129
pub use impl_list_arc_safe;
@@ -205,6 +268,52 @@ where
205268
}
206269
}
207270

271+
/// Try to create a new `ListArc`.
272+
///
273+
/// This fails if this value already has a `ListArc`.
274+
pub fn try_from_arc(arc: Arc<T>) -> Result<Self, Arc<T>>
275+
where
276+
T: TryNewListArc<ID>,
277+
{
278+
if arc.try_new_list_arc() {
279+
// SAFETY: The `try_new_list_arc` method returned true, so we made the tracking think
280+
// that a `ListArc` exists. This lets us create a `ListArc`.
281+
Ok(unsafe { Self::transmute_from_arc(arc) })
282+
} else {
283+
Err(arc)
284+
}
285+
}
286+
287+
/// Try to create a new `ListArc`.
288+
///
289+
/// This fails if this value already has a `ListArc`.
290+
pub fn try_from_arc_borrow(arc: ArcBorrow<'_, T>) -> Option<Self>
291+
where
292+
T: TryNewListArc<ID>,
293+
{
294+
if arc.try_new_list_arc() {
295+
// SAFETY: The `try_new_list_arc` method returned true, so we made the tracking think
296+
// that a `ListArc` exists. This lets us create a `ListArc`.
297+
Some(unsafe { Self::transmute_from_arc(Arc::from(arc)) })
298+
} else {
299+
None
300+
}
301+
}
302+
303+
/// Try to create a new `ListArc`.
304+
///
305+
/// If it's not possible to create a new `ListArc`, then the `Arc` is dropped. This will never
306+
/// run the destructor of the value.
307+
pub fn try_from_arc_or_drop(arc: Arc<T>) -> Option<Self>
308+
where
309+
T: TryNewListArc<ID>,
310+
{
311+
match Self::try_from_arc(arc) {
312+
Ok(list_arc) => Some(list_arc),
313+
Err(arc) => Arc::into_unique_or_drop(arc).map(Self::from),
314+
}
315+
}
316+
208317
/// Transmutes an [`Arc`] into a `ListArc` without updating the tracking inside `T`.
209318
///
210319
/// # Safety
@@ -350,3 +459,61 @@ where
350459
U: ListArcSafe<ID> + ?Sized,
351460
{
352461
}
462+
463+
/// A utility for tracking whether a [`ListArc`] exists using an atomic.
464+
///
465+
/// # Invariant
466+
///
467+
/// If the boolean is `false`, then there is no [`ListArc`] for this value.
468+
#[repr(transparent)]
469+
pub struct AtomicTracker<const ID: u64 = 0> {
470+
inner: AtomicBool,
471+
// This value needs to be pinned to justify the INVARIANT: comment in `AtomicTracker::new`.
472+
_pin: PhantomPinned,
473+
}
474+
475+
impl<const ID: u64> AtomicTracker<ID> {
476+
/// Creates a new initializer for this type.
477+
pub fn new() -> impl PinInit<Self> {
478+
// INVARIANT: Pin-init initializers can't be used on an existing `Arc`, so this value will
479+
// not be constructed in an `Arc` that already has a `ListArc`.
480+
Self {
481+
inner: AtomicBool::new(false),
482+
_pin: PhantomPinned,
483+
}
484+
}
485+
486+
fn project_inner(self: Pin<&mut Self>) -> &mut AtomicBool {
487+
// SAFETY: The `inner` field is not structurally pinned, so we may obtain a mutable
488+
// reference to it even if we only have a pinned reference to `self`.
489+
unsafe { &mut Pin::into_inner_unchecked(self).inner }
490+
}
491+
}
492+
493+
impl<const ID: u64> ListArcSafe<ID> for AtomicTracker<ID> {
494+
unsafe fn on_create_list_arc_from_unique(self: Pin<&mut Self>) {
495+
// INVARIANT: We just created a ListArc, so the boolean should be true.
496+
*self.project_inner().get_mut() = true;
497+
}
498+
499+
unsafe fn on_drop_list_arc(&self) {
500+
// INVARIANT: We just dropped a ListArc, so the boolean should be false.
501+
self.inner.store(false, Ordering::Release);
502+
}
503+
}
504+
505+
// SAFETY: If this method returns `true`, then by the type invariant there is no `ListArc` before
506+
// this call, so it is okay to create a new `ListArc`.
507+
//
508+
// The acquire ordering will synchronize with the release store from the destruction of any
509+
// previous `ListArc`, so if there was a previous `ListArc`, then the destruction of the previous
510+
// `ListArc` happens-before the creation of the new `ListArc`.
511+
unsafe impl<const ID: u64> TryNewListArc<ID> for AtomicTracker<ID> {
512+
fn try_new_list_arc(&self) -> bool {
513+
// INVARIANT: If this method returns true, then the boolean used to be false, and is no
514+
// longer false, so it is okay for the caller to create a new [`ListArc`].
515+
self.inner
516+
.compare_exchange(false, true, Ordering::Acquire, Ordering::Relaxed)
517+
.is_ok()
518+
}
519+
}

0 commit comments

Comments
 (0)