From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-wr1-f43.google.com (mail-wr1-f43.google.com [209.85.221.43]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 1D67737F005 for ; Fri, 24 Jul 2026 21:50:17 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.221.43 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1784929819; cv=none; b=MQ8m8PoQ9g2/KrQ9OsscxjNB/v8Jjg2YWHZiZJsFASZGz7qxvlEJAU388jt/uce6pppYfp9HkV+0UWbwTnaDuJtcEbIG7y6Ip6O9Zgs7dOpeMqXbho15tB/TOr3PksufswmzvWURkMjnJIemc2utWWymhPju2xxPRXH7PZm6w/I= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1784929819; c=relaxed/simple; bh=V5p5t6p533rR7PFtS36zJUJAR2eu3ApCAg9w1qM18Kc=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version; b=n/J+7bnCyznOovy2rLqmiNlXAvINCbXq2+TB18kR0p4CyXfwOsCNlenHspPTWR8psQIHHAFW7Xvi4UeEesOiTKG00o8kQcVyMtNG0Buabi/mvKkhsqm9oQtVY1GsBXxMJTDs9ahniaIs8pArtu/R67JDE48TeYxyfYo6R8fscCo= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=Jk3kknxm; arc=none smtp.client-ip=209.85.221.43 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="Jk3kknxm" Received: by mail-wr1-f43.google.com with SMTP id ffacd0b85a97d-47f703a9d05so597434f8f.0 for ; Fri, 24 Jul 2026 14:50:17 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1784929816; x=1785534616; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to:content-type; bh=X4sw7aR4x0a5vJsGtr8mrTyq++0FBtM5mNvWBcxr0UQ=; b=Jk3kknxm600gsC9wMaYN9996ekiEcXfMeZS2h2Chmw4JjLNlz48mr2dzbjm9WlOh/h 8/a6YyOTbmsWia9/f/0tqDOn4hfWwJWjwhtoIURK6WCrEfm2aT1/aBdFXokkxNOdpCa0 VlAUQbKwD7GayqTLFjZWabw1BuW4QcEibb8r3HZjQhH2ReJRUoU9DysCCR2cI8LDOvx6 T+AqycBA2UiBR1MRgyJX+o4BkVl3ppIWI34wvN18Bi0FgCcH2jR1YRlPaGcryZVdM9nA W7oP92il5orygYrF/I+eNfnNav/bxj6cGYojPXP451duXxggw9ncBQpNK5XmjEVC8f0F L3Hw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1784929816; x=1785534616; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-gg:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to:content-type; bh=X4sw7aR4x0a5vJsGtr8mrTyq++0FBtM5mNvWBcxr0UQ=; b=OcuytaVDPg/8g1HSMmwagLVrs7FKEBDNlRn7Z/CUcmipzKoANRH5V92PQGN34qU/g2 LgBdqGEced51JP67JJBpCXYpKtETe7lVsHL80YirPPo4F5qaZly9NEy6vo8dppv6uhEP f6cJlRjSQfWnuDl/uu56LGU9EjN7eQHvG7XX8qQRRbtG8JrlkOt50Naf75quuA8ir1vD P3TW9JYBGuoqwED3//bayE/a8j35VP8GZTT3h3r0ETz4uHU0l9v6tEJy76Yltg/tF1NK NbzU+8VbQ4WACDyMtx3LfvDk1f4AcuW/hWM5cPyrUbJ3yeA5/BJDL6TRY31Tsw57cfKT pJ/Q== X-Forwarded-Encrypted: i=1; AHgh+Rpq3u+GGEQi611/hnOiS7AIBGRglMM0oZObUfLvukIawlR1Wpel3Sc2fDPmAL547pJAReIswcwIxzeEqGc=@vger.kernel.org X-Gm-Message-State: AOJu0YyCmVR+7Q3pc4kKxZyYrjsXb9cXcU2rF8hZpKGGHSDjPp4kCsXh BS6E1mx+eE1yX0eIo3OfRJpGeM7VW2WF4pVKYn0h++JuzAJyn8EDGi82 X-Gm-Gg: AR+sD13zCC/o5HMB+MmhRyJRzutOhdmrblYofwYQ7wEtvYmf3sj4ALijI95uHoTXWcL DmFZwiY6P+VmvWQmxM67NrDJINbgGKZSa8mBv0H2kfydy1O6zwFMxNFVtULVvLFAqTEVQL3Z/6D aixOQt93UP4pbgOJNdJ8YN2eRHBIrOyb/iMGgKGcp4pYnfO5BEb5CyeccsLaoRjvjd7GLDpYcuE 1q1D65y3nCXj90w81bIDyAy/W/4Of24EASHCGHxplQu6KUOrcbDvP+/7BpshUM2OEdO07X0R1xQ a4nevXmbPmFXRvVhi47nj5JNVYfeuoLS1vWoSAApa1lKeaWKun7XgC3BUsWWt72SV9uI7VSyjKx Qx9rfGtLkkd+tkxWguK5tcgDv/HGybtk0ExA3x220gLUEtVxltElADllLk6x/VYFiOBHk1xS01I 3QJWn4jnfshnSTVfWR8MX4/G403pROGHn+W+bhn0LhVucJsNNNFj9v/3nn X-Received: by 2002:a05:600c:6986:b0:495:4dea:f7f5 with SMTP id 5b1f17b1804b1-496b5726cccmr846045e9.29.1784929816376; Fri, 24 Jul 2026 14:50:16 -0700 (PDT) Received: from Cian.taile2c8f4.ts.net ([2a02:8084:d03:fa00:819d:8e1d:c966:142d]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-496b4d8d6efsm17588265e9.0.2026.07.24.14.50.15 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 24 Jul 2026 14:50:15 -0700 (PDT) From: Cian McGuire To: Miguel Ojeda Cc: Boqun Feng , Gary Guo , Alice Ryhl , Lyude Paul , Daniel Almeida , =?UTF-8?q?Onur=20=C3=96zkan?= , =?UTF-8?q?Bj=C3=B6rn=20Roy=20Baron?= , Benno Lossin , Andreas Hindborg , Trevor Gross , Danilo Krummrich , Tamir Duberstein , Alexandre Courbot , FUJITA Tomonori , Greg Kroah-Hartman , rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org, Cian McGuire Subject: [PATCH 1/4] rust: aref: document safety of ARef doctest example Date: Fri, 24 Jul 2026 22:49:37 +0100 Message-ID: <20260724214940.1070221-1-cianmcguire167@gmail.com> X-Mailer: git-send-email 2.55.0 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit The `into_raw` doctest contains two `unsafe` items whose SAFETY comments were left as "TODO.": the `AlwaysRefCounted` impl for the example's `Empty` type, and the subsequent `ARef::from_raw` call. Both are sound for the same reason: `Empty`'s `inc_ref`/`dec_ref` are no-ops. `AlwaysRefCounted`'s safety contract only constrains `dec_ref`, requiring that it not free the object while a live increment remains; since this `dec_ref` never frees anything, that requirement holds vacuously. The same fact justifies the `from_raw` call. Elsewhere in this file, `Clone` and `From<&T>` justify their own calls to `from_raw` by pointing at a preceding `inc_ref()` call, but no such call happens in this example. That is fine here specifically because `Empty` does not track a real reference count at all, so there is no accounting for `from_raw` to violate, regardless of whether an increment "really" occurred. Suggested-by: Miguel Ojeda Link: https://github.com/Rust-for-Linux/linux/issues/351 Signed-off-by: Cian McGuire --- rust/kernel/sync/aref.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/rust/kernel/sync/aref.rs b/rust/kernel/sync/aref.rs index b721b2e00b98..a27b9b8f2eda 100644 --- a/rust/kernel/sync/aref.rs +++ b/rust/kernel/sync/aref.rs @@ -124,7 +124,8 @@ pub unsafe fn from_raw(ptr: NonNull) -> Self { /// /// struct Empty {} /// - /// # // SAFETY: TODO. + /// # // SAFETY: `inc_ref` and `dec_ref` are no-ops, so the requirement that `dec_ref` + /// # // must not free the object while a live increment remains is trivially satisfied. /// unsafe impl AlwaysRefCounted for Empty { /// fn inc_ref(&self) {} /// unsafe fn dec_ref(_obj: NonNull) {} @@ -132,7 +133,8 @@ pub unsafe fn from_raw(ptr: NonNull) -> Self { /// /// let mut data = Empty {}; /// let ptr = NonNull::::new(&mut data).unwrap(); - /// # // SAFETY: TODO. + /// # // SAFETY: `Empty`'s `inc_ref`/`dec_ref` do not track a real count, so `dec_ref` can + /// # // never free `data`; the safety contract of `from_raw` is vacuously satisfied here. /// let data_ref: ARef = unsafe { ARef::from_raw(ptr) }; /// let raw_ptr: NonNull = ARef::into_raw(data_ref); /// -- 2.55.0