From: Tamir Duberstein <tamird@gmail.com>
Date: Thu, 7 Nov 2024 10:36:46 +0000 (-0500)
Subject: rust: sync: document `PhantomData` in `Arc`
X-Git-Tag: v6.14-rc1~172^2~26
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=2dde1c8b04a5c415912bc3ffa8b677eb364dbcb7;p=thirdparty%2Flinux.git

rust: sync: document `PhantomData` in `Arc`

Add a comment explaining the relevant semantics of `PhantomData`. This
should help future readers who may, as I did, assume that this field is
redundant at first glance.

Signed-off-by: Tamir Duberstein <tamird@gmail.com>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Link: https://lore.kernel.org/r/20241107-simplify-arc-v2-1-7256e638aac1@gmail.com
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
---

diff --git a/rust/kernel/sync/arc.rs b/rust/kernel/sync/arc.rs
index fa4509406ee90..9f0b04400e8e5 100644
--- a/rust/kernel/sync/arc.rs
+++ b/rust/kernel/sync/arc.rs
@@ -127,6 +127,14 @@ mod std_vendor;
 /// ```
 pub struct Arc<T: ?Sized> {
     ptr: NonNull<ArcInner<T>>,
+    // NB: this informs dropck that objects of type `ArcInner<T>` may be used in `<Arc<T> as
+    // Drop>::drop`. Note that dropck already assumes that objects of type `T` may be used in
+    // `<Arc<T> as Drop>::drop` and the distinction between `T` and `ArcInner<T>` is not presently
+    // meaningful with respect to dropck - but this may change in the future so this is left here
+    // out of an abundance of caution.
+    //
+    // See https://doc.rust-lang.org/nomicon/phantom-data.html#generic-parameters-and-drop-checking
+    // for more detail on the semantics of dropck in the presence of `PhantomData`.
     _p: PhantomData<ArcInner<T>>,
 }