Skip to content

Commit 4679271

Browse files
foebfoeb
committed
rust-lang#66219 documented unsafe in core::sync::atomic
1 parent 9e34664 commit 4679271

File tree

1 file changed

+32
-2
lines changed

1 file changed

+32
-2
lines changed

‎src/libcore/sync/atomic.rs

+32-2
Original file line numberDiff line numberDiff line change
@@ -112,8 +112,6 @@
112112
//! println!("live threads: {}", old_thread_count + 1);
113113
//! ```
114114
115-
// ignore-tidy-undocumented-unsafe
116-
117115
#![stable(feature = "rust1", since = "1.0.0")]
118116
#![cfg_attr(not(target_has_atomic_load_store = "8"), allow(dead_code))]
119117
#![cfg_attr(not(target_has_atomic_load_store = "8"), allow(unused_imports))]
@@ -355,6 +353,7 @@ impl AtomicBool {
355353
#[inline]
356354
#[stable(feature = "atomic_access", since = "1.15.0")]
357355
pub fn get_mut(&mut self) -> &mut bool {
356+
// SAFETY: the mutable reference guarantees unique ownership
358357
unsafe { &mut *(self.v.get() as *mut bool) }
359358
}
360359

@@ -405,6 +404,7 @@ impl AtomicBool {
405404
#[inline]
406405
#[stable(feature = "rust1", since = "1.0.0")]
407406
pub fn load(&self, order: Ordering) -> bool {
407+
// SAFETY: data races are prevented by atomic intrinsics
408408
unsafe { atomic_load(self.v.get(), order) != 0 }
409409
}
410410

@@ -437,6 +437,7 @@ impl AtomicBool {
437437
#[inline]
438438
#[stable(feature = "rust1", since = "1.0.0")]
439439
pub fn store(&self, val: bool, order: Ordering) {
440+
// SAFETY: data races are prevented by atomic intrinsics
440441
unsafe {
441442
atomic_store(self.v.get(), val as u8, order);
442443
}
@@ -468,6 +469,7 @@ impl AtomicBool {
468469
#[stable(feature = "rust1", since = "1.0.0")]
469470
#[cfg(target_has_atomic = "8")]
470471
pub fn swap(&self, val: bool, order: Ordering) -> bool {
472+
// SAFETY: data races are prevented by atomic intrinsics
471473
unsafe { atomic_swap(self.v.get(), val as u8, order) != 0 }
472474
}
473475

@@ -562,6 +564,7 @@ impl AtomicBool {
562564
success: Ordering,
563565
failure: Ordering)
564566
-> Result<bool, bool> {
567+
// SAFETY: data races are prevented by atomic intrinsics
565568
match unsafe {
566569
atomic_compare_exchange(self.v.get(), current as u8, new as u8, success, failure)
567570
} {
@@ -618,6 +621,7 @@ impl AtomicBool {
618621
success: Ordering,
619622
failure: Ordering)
620623
-> Result<bool, bool> {
624+
// SAFETY: data races are prevented by atomic intrinsics
621625
match unsafe {
622626
atomic_compare_exchange_weak(self.v.get(), current as u8, new as u8, success, failure)
623627
} {
@@ -664,6 +668,7 @@ impl AtomicBool {
664668
#[stable(feature = "rust1", since = "1.0.0")]
665669
#[cfg(target_has_atomic = "8")]
666670
pub fn fetch_and(&self, val: bool, order: Ordering) -> bool {
671+
// SAFETY: data races are prevented by atomic intrinsics
667672
unsafe { atomic_and(self.v.get(), val as u8, order) != 0 }
668673
}
669674

@@ -759,6 +764,7 @@ impl AtomicBool {
759764
#[stable(feature = "rust1", since = "1.0.0")]
760765
#[cfg(target_has_atomic = "8")]
761766
pub fn fetch_or(&self, val: bool, order: Ordering) -> bool {
767+
// SAFETY: data races are prevented by atomic intrinsics
762768
unsafe { atomic_or(self.v.get(), val as u8, order) != 0 }
763769
}
764770

@@ -800,6 +806,7 @@ impl AtomicBool {
800806
#[stable(feature = "rust1", since = "1.0.0")]
801807
#[cfg(target_has_atomic = "8")]
802808
pub fn fetch_xor(&self, val: bool, order: Ordering) -> bool {
809+
// SAFETY: data races are prevented by atomic intrinsics
803810
unsafe { atomic_xor(self.v.get(), val as u8, order) != 0 }
804811
}
805812
}
@@ -839,6 +846,7 @@ impl<T> AtomicPtr<T> {
839846
#[inline]
840847
#[stable(feature = "atomic_access", since = "1.15.0")]
841848
pub fn get_mut(&mut self) -> &mut *mut T {
849+
// SAFETY: the mutable reference guarantees unique ownership
842850
unsafe { &mut *self.p.get() }
843851
}
844852

@@ -890,6 +898,7 @@ impl<T> AtomicPtr<T> {
890898
#[inline]
891899
#[stable(feature = "rust1", since = "1.0.0")]
892900
pub fn load(&self, order: Ordering) -> *mut T {
901+
// SAFETY: data races are prevented by atomic intrinsics
893902
unsafe { atomic_load(self.p.get() as *mut usize, order) as *mut T }
894903
}
895904

@@ -924,6 +933,7 @@ impl<T> AtomicPtr<T> {
924933
#[inline]
925934
#[stable(feature = "rust1", since = "1.0.0")]
926935
pub fn store(&self, ptr: *mut T, order: Ordering) {
936+
// SAFETY: data races are prevented by atomic intrinsics
927937
unsafe {
928938
atomic_store(self.p.get() as *mut usize, ptr as usize, order);
929939
}
@@ -957,6 +967,7 @@ impl<T> AtomicPtr<T> {
957967
#[stable(feature = "rust1", since = "1.0.0")]
958968
#[cfg(target_has_atomic = "ptr")]
959969
pub fn swap(&self, ptr: *mut T, order: Ordering) -> *mut T {
970+
// SAFETY: data races are prevented by atomic intrinsics
960971
unsafe { atomic_swap(self.p.get() as *mut usize, ptr as usize, order) as *mut T }
961972
}
962973

@@ -1040,6 +1051,7 @@ impl<T> AtomicPtr<T> {
10401051
success: Ordering,
10411052
failure: Ordering)
10421053
-> Result<*mut T, *mut T> {
1054+
// SAFETY: data races are prevented by atomic intrinsics
10431055
unsafe {
10441056
let res = atomic_compare_exchange(self.p.get() as *mut usize,
10451057
current as usize,
@@ -1100,6 +1112,7 @@ impl<T> AtomicPtr<T> {
11001112
success: Ordering,
11011113
failure: Ordering)
11021114
-> Result<*mut T, *mut T> {
1115+
// SAFETY: data races are prevented by atomic intrinsics
11031116
unsafe {
11041117
let res = atomic_compare_exchange_weak(self.p.get() as *mut usize,
11051118
current as usize,
@@ -1245,6 +1258,7 @@ assert_eq!(some_var.load(Ordering::SeqCst), 5);
12451258
#[inline]
12461259
#[$stable_access]
12471260
pub fn get_mut(&mut self) -> &mut $int_type {
1261+
// SAFETY: the mutable reference guarantees unique ownership
12481262
unsafe { &mut *self.v.get() }
12491263
}
12501264
}
@@ -1299,6 +1313,7 @@ assert_eq!(some_var.load(Ordering::Relaxed), 5);
12991313
#[inline]
13001314
#[$stable]
13011315
pub fn load(&self, order: Ordering) -> $int_type {
1316+
// SAFETY: data races are prevented by atomic intrinsics
13021317
unsafe { atomic_load(self.v.get(), order) }
13031318
}
13041319
}
@@ -1333,6 +1348,7 @@ assert_eq!(some_var.load(Ordering::Relaxed), 10);
13331348
#[inline]
13341349
#[$stable]
13351350
pub fn store(&self, val: $int_type, order: Ordering) {
1351+
// SAFETY: data races are prevented by atomic intrinsics
13361352
unsafe { atomic_store(self.v.get(), val, order); }
13371353
}
13381354
}
@@ -1363,6 +1379,7 @@ assert_eq!(some_var.swap(10, Ordering::Relaxed), 5);
13631379
#[$stable]
13641380
#[$cfg_cas]
13651381
pub fn swap(&self, val: $int_type, order: Ordering) -> $int_type {
1382+
// SAFETY: data races are prevented by atomic intrinsics
13661383
unsafe { atomic_swap(self.v.get(), val, order) }
13671384
}
13681385
}
@@ -1465,6 +1482,7 @@ assert_eq!(some_var.load(Ordering::Relaxed), 10);
14651482
new: $int_type,
14661483
success: Ordering,
14671484
failure: Ordering) -> Result<$int_type, $int_type> {
1485+
// SAFETY: data races are prevented by atomic intrinsics
14681486
unsafe { atomic_compare_exchange(self.v.get(), current, new, success, failure) }
14691487
}
14701488
}
@@ -1517,6 +1535,7 @@ loop {
15171535
new: $int_type,
15181536
success: Ordering,
15191537
failure: Ordering) -> Result<$int_type, $int_type> {
1538+
// SAFETY: data races are prevented by atomic intrinsics
15201539
unsafe {
15211540
atomic_compare_exchange_weak(self.v.get(), current, new, success, failure)
15221541
}
@@ -1551,6 +1570,7 @@ assert_eq!(foo.load(Ordering::SeqCst), 10);
15511570
#[$stable]
15521571
#[$cfg_cas]
15531572
pub fn fetch_add(&self, val: $int_type, order: Ordering) -> $int_type {
1573+
// SAFETY: data races are prevented by atomic intrinsics
15541574
unsafe { atomic_add(self.v.get(), val, order) }
15551575
}
15561576
}
@@ -1583,6 +1603,7 @@ assert_eq!(foo.load(Ordering::SeqCst), 10);
15831603
#[$stable]
15841604
#[$cfg_cas]
15851605
pub fn fetch_sub(&self, val: $int_type, order: Ordering) -> $int_type {
1606+
// SAFETY: data races are prevented by atomic intrinsics
15861607
unsafe { atomic_sub(self.v.get(), val, order) }
15871608
}
15881609
}
@@ -1618,6 +1639,7 @@ assert_eq!(foo.load(Ordering::SeqCst), 0b100001);
16181639
#[$stable]
16191640
#[$cfg_cas]
16201641
pub fn fetch_and(&self, val: $int_type, order: Ordering) -> $int_type {
1642+
// SAFETY: data races are prevented by atomic intrinsics
16211643
unsafe { atomic_and(self.v.get(), val, order) }
16221644
}
16231645
}
@@ -1654,6 +1676,7 @@ assert_eq!(foo.load(Ordering::SeqCst), !(0x13 & 0x31));
16541676
#[$stable_nand]
16551677
#[$cfg_cas]
16561678
pub fn fetch_nand(&self, val: $int_type, order: Ordering) -> $int_type {
1679+
// SAFETY: data races are prevented by atomic intrinsics
16571680
unsafe { atomic_nand(self.v.get(), val, order) }
16581681
}
16591682
}
@@ -1689,6 +1712,7 @@ assert_eq!(foo.load(Ordering::SeqCst), 0b111111);
16891712
#[$stable]
16901713
#[$cfg_cas]
16911714
pub fn fetch_or(&self, val: $int_type, order: Ordering) -> $int_type {
1715+
// SAFETY: data races are prevented by atomic intrinsics
16921716
unsafe { atomic_or(self.v.get(), val, order) }
16931717
}
16941718
}
@@ -1724,6 +1748,7 @@ assert_eq!(foo.load(Ordering::SeqCst), 0b011110);
17241748
#[$stable]
17251749
#[$cfg_cas]
17261750
pub fn fetch_xor(&self, val: $int_type, order: Ordering) -> $int_type {
1751+
// SAFETY: data races are prevented by atomic intrinsics
17271752
unsafe { atomic_xor(self.v.get(), val, order) }
17281753
}
17291754
}
@@ -1835,6 +1860,7 @@ assert!(max_foo == 42);
18351860
issue = "48655")]
18361861
#[$cfg_cas]
18371862
pub fn fetch_max(&self, val: $int_type, order: Ordering) -> $int_type {
1863+
// SAFETY: data races are prevented by atomic intrinsics
18381864
unsafe { $max_fn(self.v.get(), val, order) }
18391865
}
18401866
}
@@ -1887,6 +1913,7 @@ assert_eq!(min_foo, 12);
18871913
issue = "48655")]
18881914
#[$cfg_cas]
18891915
pub fn fetch_min(&self, val: $int_type, order: Ordering) -> $int_type {
1916+
// SAFETY: data races are prevented by atomic intrinsics
18901917
unsafe { $min_fn(self.v.get(), val, order) }
18911918
}
18921919
}
@@ -2429,7 +2456,9 @@ pub fn fence(order: Ordering) {
24292456
// to conventionally implement fences at
24302457
// https://github.com/WebAssembly/tool-conventions/issues/59. We should
24312458
// follow that discussion and implement a solution when one comes about!
2459+
24322460
#[cfg(not(target_arch = "wasm32"))]
2461+
// SAFETY: using an atomic fence is safe
24332462
unsafe {
24342463
match order {
24352464
Acquire => intrinsics::atomic_fence_acq(),
@@ -2518,6 +2547,7 @@ pub fn fence(order: Ordering) {
25182547
#[inline]
25192548
#[stable(feature = "compiler_fences", since = "1.21.0")]
25202549
pub fn compiler_fence(order: Ordering) {
2550+
// SAFETY: doesn't compile to machine code
25212551
unsafe {
25222552
match order {
25232553
Acquire => intrinsics::atomic_singlethreadfence_acq(),

0 commit comments

Comments
 (0)