]>
Commit | Line | Data |
---|---|---|
85aaf69f | 1 | #![stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 2 | |
c30ab7b3 | 3 | //! Thread-safe reference-counting pointers. |
1a4d82fc | 4 | //! |
3dfed10e | 5 | //! See the [`Arc<T>`][Arc] documentation for more details. |
2b03887a FG |
6 | //! |
7 | //! **Note**: This module is only available on platforms that support atomic | |
8 | //! loads and stores of pointers. This may be detected at compile time using | |
9 | //! `#[cfg(target_has_atomic = "ptr")]`. | |
1a4d82fc | 10 | |
94b46f34 | 11 | use core::any::Any; |
e9174d1e | 12 | use core::borrow; |
60c5eb7d | 13 | use core::cmp::Ordering; |
dfeec247 XL |
14 | use core::fmt; |
15 | use core::hash::{Hash, Hasher}; | |
29967ef6 | 16 | use core::hint; |
92a42be0 | 17 | use core::intrinsics::abort; |
17df50a5 | 18 | #[cfg(not(no_global_oom_handling))] |
dfeec247 | 19 | use core::iter; |
353b0b11 | 20 | use core::marker::{PhantomData, Unsize}; |
17df50a5 XL |
21 | #[cfg(not(no_global_oom_handling))] |
22 | use core::mem::size_of_val; | |
23 | use core::mem::{self, align_of_val_raw}; | |
dfeec247 | 24 | use core::ops::{CoerceUnsized, Deref, DispatchFromDyn, Receiver}; |
94222f64 | 25 | use core::panic::{RefUnwindSafe, UnwindSafe}; |
0bf4aa26 | 26 | use core::pin::Pin; |
2c00a5a8 | 27 | use core::ptr::{self, NonNull}; |
17df50a5 | 28 | #[cfg(not(no_global_oom_handling))] |
f9f354fc | 29 | use core::slice::from_raw_parts_mut; |
dfeec247 | 30 | use core::sync::atomic; |
04454e1e | 31 | use core::sync::atomic::Ordering::{Acquire, Relaxed, Release}; |
041b39d2 | 32 | |
17df50a5 XL |
33 | #[cfg(not(no_global_oom_handling))] |
34 | use crate::alloc::handle_alloc_error; | |
35 | #[cfg(not(no_global_oom_handling))] | |
fe692bf9 | 36 | use crate::alloc::WriteCloneIntoRaw; |
17df50a5 | 37 | use crate::alloc::{AllocError, Allocator, Global, Layout}; |
f9f354fc | 38 | use crate::borrow::{Cow, ToOwned}; |
9fa01778 XL |
39 | use crate::boxed::Box; |
40 | use crate::rc::is_dangling; | |
17df50a5 | 41 | #[cfg(not(no_global_oom_handling))] |
9fa01778 | 42 | use crate::string::String; |
17df50a5 | 43 | #[cfg(not(no_global_oom_handling))] |
9fa01778 | 44 | use crate::vec::Vec; |
1a4d82fc | 45 | |
416331ca XL |
46 | #[cfg(test)] |
47 | mod tests; | |
48 | ||
c30ab7b3 SL |
49 | /// A soft limit on the amount of references that may be made to an `Arc`. |
50 | /// | |
51 | /// Going above this limit will abort your program (although not | |
52 | /// necessarily) at _exactly_ `MAX_REFCOUNT + 1` references. | |
353b0b11 FG |
53 | /// Trying to go above it might call a `panic` (if not actually going above it). |
54 | /// | |
55 | /// This is a global invariant, and also applies when using a compare-exchange loop. | |
56 | /// | |
57 | /// See comment in `Arc::clone`. | |
c1a9b12d SL |
58 | const MAX_REFCOUNT: usize = (isize::MAX) as usize; |
59 | ||
353b0b11 FG |
60 | /// The error in case either counter reaches above `MAX_REFCOUNT`, and we can `panic` safely. |
61 | const INTERNAL_OVERFLOW_ERROR: &str = "Arc counter overflow"; | |
62 | ||
ba9703b0 XL |
63 | #[cfg(not(sanitize = "thread"))] |
64 | macro_rules! acquire { | |
65 | ($x:expr) => { | |
66 | atomic::fence(Acquire) | |
67 | }; | |
68 | } | |
69 | ||
70 | // ThreadSanitizer does not support memory fences. To avoid false positive | |
71 | // reports in Arc / Weak implementation use atomic loads for synchronization | |
72 | // instead. | |
73 | #[cfg(sanitize = "thread")] | |
74 | macro_rules! acquire { | |
75 | ($x:expr) => { | |
76 | $x.load(Acquire) | |
77 | }; | |
78 | } | |
79 | ||
041b39d2 XL |
80 | /// A thread-safe reference-counting pointer. 'Arc' stands for 'Atomically |
81 | /// Reference Counted'. | |
1a4d82fc | 82 | /// |
c30ab7b3 SL |
83 | /// The type `Arc<T>` provides shared ownership of a value of type `T`, |
84 | /// allocated in the heap. Invoking [`clone`][clone] on `Arc` produces | |
e74abb32 | 85 | /// a new `Arc` instance, which points to the same allocation on the heap as the |
b7449926 | 86 | /// source `Arc`, while increasing a reference count. When the last `Arc` |
e74abb32 XL |
87 | /// pointer to a given allocation is destroyed, the value stored in that allocation (often |
88 | /// referred to as "inner value") is also dropped. | |
1a4d82fc | 89 | /// |
c30ab7b3 | 90 | /// Shared references in Rust disallow mutation by default, and `Arc` is no |
ea8adc8c XL |
91 | /// exception: you cannot generally obtain a mutable reference to something |
92 | /// inside an `Arc`. If you need to mutate through an `Arc`, use | |
93 | /// [`Mutex`][mutex], [`RwLock`][rwlock], or one of the [`Atomic`][atomic] | |
94 | /// types. | |
9e0c209e | 95 | /// |
2b03887a FG |
96 | /// **Note**: This type is only available on platforms that support atomic |
97 | /// loads and stores of pointers, which includes all platforms that support | |
98 | /// the `std` crate but not all those which only support [`alloc`](crate). | |
99 | /// This may be detected at compile time using `#[cfg(target_has_atomic = "ptr")]`. | |
100 | /// | |
7cac9316 XL |
101 | /// ## Thread Safety |
102 | /// | |
103 | /// Unlike [`Rc<T>`], `Arc<T>` uses atomic operations for its reference | |
83c7162d | 104 | /// counting. This means that it is thread-safe. The disadvantage is that |
7cac9316 | 105 | /// atomic operations are more expensive than ordinary memory accesses. If you |
e74abb32 | 106 | /// are not sharing reference-counted allocations between threads, consider using |
7cac9316 XL |
107 | /// [`Rc<T>`] for lower overhead. [`Rc<T>`] is a safe default, because the |
108 | /// compiler will catch any attempt to send an [`Rc<T>`] between threads. | |
109 | /// However, a library might choose `Arc<T>` in order to give library consumers | |
c30ab7b3 | 110 | /// more flexibility. |
1a4d82fc | 111 | /// |
7cac9316 XL |
112 | /// `Arc<T>` will implement [`Send`] and [`Sync`] as long as the `T` implements |
113 | /// [`Send`] and [`Sync`]. Why can't you put a non-thread-safe type `T` in an | |
114 | /// `Arc<T>` to make it thread-safe? This may be a bit counter-intuitive at | |
115 | /// first: after all, isn't the point of `Arc<T>` thread safety? The key is | |
116 | /// this: `Arc<T>` makes it thread safe to have multiple ownership of the same | |
117 | /// data, but it doesn't add thread safety to its data. Consider | |
c295e0f8 XL |
118 | /// <code>Arc<[RefCell\<T>]></code>. [`RefCell<T>`] isn't [`Sync`], and if `Arc<T>` was always |
119 | /// [`Send`], <code>Arc<[RefCell\<T>]></code> would be as well. But then we'd have a problem: | |
ea8adc8c | 120 | /// [`RefCell<T>`] is not thread safe; it keeps track of the borrowing count using |
7cac9316 XL |
121 | /// non-atomic operations. |
122 | /// | |
123 | /// In the end, this means that you may need to pair `Arc<T>` with some sort of | |
ea8adc8c | 124 | /// [`std::sync`] type, usually [`Mutex<T>`][mutex]. |
7cac9316 XL |
125 | /// |
126 | /// ## Breaking cycles with `Weak` | |
127 | /// | |
c30ab7b3 | 128 | /// The [`downgrade`][downgrade] method can be used to create a non-owning |
3dfed10e | 129 | /// [`Weak`] pointer. A [`Weak`] pointer can be [`upgrade`][upgrade]d |
e74abb32 XL |
130 | /// to an `Arc`, but this will return [`None`] if the value stored in the allocation has |
131 | /// already been dropped. In other words, `Weak` pointers do not keep the value | |
132 | /// inside the allocation alive; however, they *do* keep the allocation | |
133 | /// (the backing store for the value) alive. | |
c30ab7b3 SL |
134 | /// |
135 | /// A cycle between `Arc` pointers will never be deallocated. For this reason, | |
3dfed10e XL |
136 | /// [`Weak`] is used to break cycles. For example, a tree could have |
137 | /// strong `Arc` pointers from parent nodes to children, and [`Weak`] | |
32a655c1 | 138 | /// pointers from children back to their parents. |
c30ab7b3 | 139 | /// |
7cac9316 XL |
140 | /// # Cloning references |
141 | /// | |
1b1a35ee | 142 | /// Creating a new reference from an existing reference-counted pointer is done using the |
3dfed10e | 143 | /// `Clone` trait implemented for [`Arc<T>`][Arc] and [`Weak<T>`][Weak]. |
7cac9316 XL |
144 | /// |
145 | /// ``` | |
146 | /// use std::sync::Arc; | |
147 | /// let foo = Arc::new(vec![1.0, 2.0, 3.0]); | |
148 | /// // The two syntaxes below are equivalent. | |
149 | /// let a = foo.clone(); | |
150 | /// let b = Arc::clone(&foo); | |
b7449926 | 151 | /// // a, b, and foo are all Arcs that point to the same memory location |
7cac9316 XL |
152 | /// ``` |
153 | /// | |
7cac9316 XL |
154 | /// ## `Deref` behavior |
155 | /// | |
add651ee | 156 | /// `Arc<T>` automatically dereferences to `T` (via the [`Deref`] trait), |
c30ab7b3 | 157 | /// so you can call `T`'s methods on a value of type `Arc<T>`. To avoid name |
13cf67c4 | 158 | /// clashes with `T`'s methods, the methods of `Arc<T>` itself are associated |
29967ef6 | 159 | /// functions, called using [fully qualified syntax]: |
c34b1796 AL |
160 | /// |
161 | /// ``` | |
1a4d82fc | 162 | /// use std::sync::Arc; |
1a4d82fc | 163 | /// |
29967ef6 | 164 | /// let my_arc = Arc::new(()); |
c295e0f8 | 165 | /// let my_weak = Arc::downgrade(&my_arc); |
c30ab7b3 | 166 | /// ``` |
1a4d82fc | 167 | /// |
29967ef6 XL |
168 | /// `Arc<T>`'s implementations of traits like `Clone` may also be called using |
169 | /// fully qualified syntax. Some people prefer to use fully qualified syntax, | |
170 | /// while others prefer using method-call syntax. | |
171 | /// | |
172 | /// ``` | |
173 | /// use std::sync::Arc; | |
174 | /// | |
175 | /// let arc = Arc::new(()); | |
176 | /// // Method-call syntax | |
177 | /// let arc2 = arc.clone(); | |
178 | /// // Fully qualified syntax | |
179 | /// let arc3 = Arc::clone(&arc); | |
180 | /// ``` | |
181 | /// | |
3dfed10e | 182 | /// [`Weak<T>`][Weak] does not auto-dereference to `T`, because the inner value may have |
e74abb32 | 183 | /// already been dropped. |
1a4d82fc | 184 | /// |
3dfed10e XL |
185 | /// [`Rc<T>`]: crate::rc::Rc |
186 | /// [clone]: Clone::clone | |
c30ab7b3 SL |
187 | /// [mutex]: ../../std/sync/struct.Mutex.html |
188 | /// [rwlock]: ../../std/sync/struct.RwLock.html | |
3dfed10e | 189 | /// [atomic]: core::sync::atomic |
3dfed10e XL |
190 | /// [downgrade]: Arc::downgrade |
191 | /// [upgrade]: Weak::upgrade | |
c295e0f8 | 192 | /// [RefCell\<T>]: core::cell::RefCell |
3dfed10e | 193 | /// [`RefCell<T>`]: core::cell::RefCell |
ea8adc8c | 194 | /// [`std::sync`]: ../../std/sync/index.html |
1b1a35ee | 195 | /// [`Arc::clone(&from)`]: Arc::clone |
29967ef6 | 196 | /// [fully qualified syntax]: https://doc.rust-lang.org/book/ch19-03-advanced-traits.html#fully-qualified-syntax-for-disambiguation-calling-methods-with-the-same-name |
1a4d82fc | 197 | /// |
c30ab7b3 | 198 | /// # Examples |
5bcae85e | 199 | /// |
c30ab7b3 SL |
200 | /// Sharing some immutable data between threads: |
201 | /// | |
202 | // Note that we **do not** run these tests here. The windows builders get super | |
203 | // unhappy if a thread outlives the main thread and then exits at the same time | |
204 | // (something deadlocks) so we just avoid this entirely by not running these | |
205 | // tests. | |
5bcae85e | 206 | /// ```no_run |
c30ab7b3 | 207 | /// use std::sync::Arc; |
5bcae85e SL |
208 | /// use std::thread; |
209 | /// | |
c30ab7b3 | 210 | /// let five = Arc::new(5); |
5bcae85e SL |
211 | /// |
212 | /// for _ in 0..10 { | |
7cac9316 | 213 | /// let five = Arc::clone(&five); |
5bcae85e SL |
214 | /// |
215 | /// thread::spawn(move || { | |
5e7ed085 | 216 | /// println!("{five:?}"); |
c30ab7b3 SL |
217 | /// }); |
218 | /// } | |
219 | /// ``` | |
5bcae85e | 220 | /// |
32a655c1 SL |
221 | /// Sharing a mutable [`AtomicUsize`]: |
222 | /// | |
c295e0f8 | 223 | /// [`AtomicUsize`]: core::sync::atomic::AtomicUsize "sync::atomic::AtomicUsize" |
5bcae85e | 224 | /// |
c30ab7b3 SL |
225 | /// ```no_run |
226 | /// use std::sync::Arc; | |
227 | /// use std::sync::atomic::{AtomicUsize, Ordering}; | |
228 | /// use std::thread; | |
229 | /// | |
230 | /// let val = Arc::new(AtomicUsize::new(5)); | |
231 | /// | |
232 | /// for _ in 0..10 { | |
7cac9316 | 233 | /// let val = Arc::clone(&val); |
c30ab7b3 SL |
234 | /// |
235 | /// thread::spawn(move || { | |
236 | /// let v = val.fetch_add(1, Ordering::SeqCst); | |
5e7ed085 | 237 | /// println!("{v:?}"); |
5bcae85e SL |
238 | /// }); |
239 | /// } | |
240 | /// ``` | |
c30ab7b3 SL |
241 | /// |
242 | /// See the [`rc` documentation][rc_examples] for more examples of reference | |
243 | /// counting in general. | |
244 | /// | |
1b1a35ee | 245 | /// [rc_examples]: crate::rc#examples |
ba9703b0 | 246 | #[cfg_attr(not(test), rustc_diagnostic_item = "Arc")] |
85aaf69f | 247 | #[stable(feature = "rust1", since = "1.0.0")] |
add651ee FG |
248 | pub struct Arc< |
249 | T: ?Sized, | |
250 | #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, | |
251 | > { | |
2c00a5a8 | 252 | ptr: NonNull<ArcInner<T>>, |
60c5eb7d | 253 | phantom: PhantomData<ArcInner<T>>, |
add651ee | 254 | alloc: A, |
1a4d82fc JJ |
255 | } |
256 | ||
92a42be0 | 257 | #[stable(feature = "rust1", since = "1.0.0")] |
add651ee | 258 | unsafe impl<T: ?Sized + Sync + Send, A: Allocator + Send> Send for Arc<T, A> {} |
92a42be0 | 259 | #[stable(feature = "rust1", since = "1.0.0")] |
add651ee | 260 | unsafe impl<T: ?Sized + Sync + Send, A: Allocator + Sync> Sync for Arc<T, A> {} |
1a4d82fc | 261 | |
94222f64 | 262 | #[stable(feature = "catch_unwind", since = "1.9.0")] |
add651ee | 263 | impl<T: RefUnwindSafe + ?Sized, A: Allocator + UnwindSafe> UnwindSafe for Arc<T, A> {} |
94222f64 | 264 | |
9c376795 | 265 | #[unstable(feature = "coerce_unsized", issue = "18598")] |
add651ee | 266 | impl<T: ?Sized + Unsize<U>, U: ?Sized, A: Allocator> CoerceUnsized<Arc<U, A>> for Arc<T, A> {} |
1a4d82fc | 267 | |
dfeec247 | 268 | #[unstable(feature = "dispatch_from_dyn", issue = "none")] |
a1dfa0c6 XL |
269 | impl<T: ?Sized + Unsize<U>, U: ?Sized> DispatchFromDyn<Arc<U>> for Arc<T> {} |
270 | ||
416331ca | 271 | impl<T: ?Sized> Arc<T> { |
3c0e092e | 272 | unsafe fn from_inner(ptr: NonNull<ArcInner<T>>) -> Self { |
add651ee | 273 | unsafe { Self::from_inner_in(ptr, Global) } |
416331ca XL |
274 | } |
275 | ||
276 | unsafe fn from_ptr(ptr: *mut ArcInner<T>) -> Self { | |
add651ee FG |
277 | unsafe { Self::from_ptr_in(ptr, Global) } |
278 | } | |
279 | } | |
280 | ||
281 | impl<T: ?Sized, A: Allocator> Arc<T, A> { | |
282 | #[inline] | |
283 | unsafe fn from_inner_in(ptr: NonNull<ArcInner<T>>, alloc: A) -> Self { | |
284 | Self { ptr, phantom: PhantomData, alloc } | |
285 | } | |
286 | ||
287 | #[inline] | |
288 | unsafe fn from_ptr_in(ptr: *mut ArcInner<T>, alloc: A) -> Self { | |
289 | unsafe { Self::from_inner_in(NonNull::new_unchecked(ptr), alloc) } | |
416331ca XL |
290 | } |
291 | } | |
292 | ||
cc61c64b | 293 | /// `Weak` is a version of [`Arc`] that holds a non-owning reference to the |
e74abb32 | 294 | /// managed allocation. The allocation is accessed by calling [`upgrade`] on the `Weak` |
c295e0f8 | 295 | /// pointer, which returns an <code>[Option]<[Arc]\<T>></code>. |
1a4d82fc | 296 | /// |
cc61c64b | 297 | /// Since a `Weak` reference does not count towards ownership, it will not |
e74abb32 XL |
298 | /// prevent the value stored in the allocation from being dropped, and `Weak` itself makes no |
299 | /// guarantees about the value still being present. Thus it may return [`None`] | |
300 | /// when [`upgrade`]d. Note however that a `Weak` reference *does* prevent the allocation | |
301 | /// itself (the backing store) from being deallocated. | |
5bcae85e | 302 | /// |
e74abb32 XL |
303 | /// A `Weak` pointer is useful for keeping a temporary reference to the allocation |
304 | /// managed by [`Arc`] without preventing its inner value from being dropped. It is also used to | |
305 | /// prevent circular references between [`Arc`] pointers, since mutual owning references | |
cc61c64b XL |
306 | /// would never allow either [`Arc`] to be dropped. For example, a tree could |
307 | /// have strong [`Arc`] pointers from parent nodes to children, and `Weak` | |
308 | /// pointers from children back to their parents. | |
5bcae85e | 309 | /// |
cc61c64b | 310 | /// The typical way to obtain a `Weak` pointer is to call [`Arc::downgrade`]. |
c30ab7b3 | 311 | /// |
3dfed10e | 312 | /// [`upgrade`]: Weak::upgrade |
e9174d1e | 313 | #[stable(feature = "arc_weak", since = "1.4.0")] |
add651ee FG |
314 | pub struct Weak< |
315 | T: ?Sized, | |
316 | #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, | |
317 | > { | |
8faf50e0 XL |
318 | // This is a `NonNull` to allow optimizing the size of this type in enums, |
319 | // but it is not necessarily a valid pointer. | |
320 | // `Weak::new` sets this to `usize::MAX` so that it doesn’t need | |
9c376795 | 321 | // to allocate space on the heap. That's not a value a real pointer |
8faf50e0 | 322 | // will ever have because RcBox has alignment at least 2. |
f035d41b | 323 | // This is only possible when `T: Sized`; unsized `T` never dangle. |
2c00a5a8 | 324 | ptr: NonNull<ArcInner<T>>, |
add651ee | 325 | alloc: A, |
1a4d82fc JJ |
326 | } |
327 | ||
7453a54e | 328 | #[stable(feature = "arc_weak", since = "1.4.0")] |
add651ee | 329 | unsafe impl<T: ?Sized + Sync + Send, A: Allocator + Send> Send for Weak<T, A> {} |
7453a54e | 330 | #[stable(feature = "arc_weak", since = "1.4.0")] |
add651ee | 331 | unsafe impl<T: ?Sized + Sync + Send, A: Allocator + Sync> Sync for Weak<T, A> {} |
1a4d82fc | 332 | |
9c376795 | 333 | #[unstable(feature = "coerce_unsized", issue = "18598")] |
add651ee | 334 | impl<T: ?Sized + Unsize<U>, U: ?Sized, A: Allocator> CoerceUnsized<Weak<U, A>> for Weak<T, A> {} |
dfeec247 | 335 | #[unstable(feature = "dispatch_from_dyn", issue = "none")] |
a1dfa0c6 | 336 | impl<T: ?Sized + Unsize<U>, U: ?Sized> DispatchFromDyn<Weak<U>> for Weak<T> {} |
c1a9b12d | 337 | |
7453a54e | 338 | #[stable(feature = "arc_weak", since = "1.4.0")] |
9c376795 | 339 | impl<T: ?Sized> fmt::Debug for Weak<T> { |
9fa01778 | 340 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
c34b1796 AL |
341 | write!(f, "(Weak)") |
342 | } | |
343 | } | |
344 | ||
ba9703b0 XL |
345 | // This is repr(C) to future-proof against possible field-reordering, which |
346 | // would interfere with otherwise safe [into|from]_raw() of transmutable | |
347 | // inner types. | |
348 | #[repr(C)] | |
62682a34 | 349 | struct ArcInner<T: ?Sized> { |
85aaf69f | 350 | strong: atomic::AtomicUsize, |
c1a9b12d SL |
351 | |
352 | // the value usize::MAX acts as a sentinel for temporarily "locking" the | |
353 | // ability to upgrade weak pointers or downgrade strong ones; this is used | |
e9174d1e | 354 | // to avoid races in `make_mut` and `get_mut`. |
85aaf69f | 355 | weak: atomic::AtomicUsize, |
c1a9b12d | 356 | |
1a4d82fc JJ |
357 | data: T, |
358 | } | |
359 | ||
487cf647 FG |
360 | /// Calculate layout for `ArcInner<T>` using the inner value's layout |
361 | fn arcinner_layout_for_value_layout(layout: Layout) -> Layout { | |
362 | // Calculate layout using the given value layout. | |
363 | // Previously, layout was calculated on the expression | |
364 | // `&*(ptr as *const ArcInner<T>)`, but this created a misaligned | |
365 | // reference (see #54908). | |
366 | Layout::new::<ArcInner<()>>().extend(layout).unwrap().0.pad_to_align() | |
367 | } | |
368 | ||
62682a34 SL |
369 | unsafe impl<T: ?Sized + Sync + Send> Send for ArcInner<T> {} |
370 | unsafe impl<T: ?Sized + Sync + Send> Sync for ArcInner<T> {} | |
1a4d82fc JJ |
371 | |
372 | impl<T> Arc<T> { | |
373 | /// Constructs a new `Arc<T>`. | |
374 | /// | |
375 | /// # Examples | |
376 | /// | |
377 | /// ``` | |
378 | /// use std::sync::Arc; | |
379 | /// | |
85aaf69f | 380 | /// let five = Arc::new(5); |
1a4d82fc | 381 | /// ``` |
136023e0 | 382 | #[cfg(not(no_global_oom_handling))] |
1a4d82fc | 383 | #[inline] |
85aaf69f | 384 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
385 | pub fn new(data: T) -> Arc<T> { |
386 | // Start the weak pointer count as 1 which is the weak pointer that's | |
387 | // held by all the strong pointers (kinda), see std/rc.rs for more info | |
923072b8 | 388 | let x: Box<_> = Box::new(ArcInner { |
85aaf69f SL |
389 | strong: atomic::AtomicUsize::new(1), |
390 | weak: atomic::AtomicUsize::new(1), | |
3b2f2976 | 391 | data, |
923072b8 | 392 | }); |
3c0e092e | 393 | unsafe { Self::from_inner(Box::leak(x).into()) } |
e9174d1e SL |
394 | } |
395 | ||
04454e1e FG |
396 | /// Constructs a new `Arc<T>` while giving you a `Weak<T>` to the allocation, |
397 | /// to allow you to construct a `T` which holds a weak pointer to itself. | |
3dfed10e | 398 | /// |
5099ac24 | 399 | /// Generally, a structure circularly referencing itself, either directly or |
04454e1e FG |
400 | /// indirectly, should not hold a strong reference to itself to prevent a memory leak. |
401 | /// Using this function, you get access to the weak pointer during the | |
402 | /// initialization of `T`, before the `Arc<T>` is created, such that you can | |
403 | /// clone and store it inside the `T`. | |
5099ac24 | 404 | /// |
04454e1e FG |
405 | /// `new_cyclic` first allocates the managed allocation for the `Arc<T>`, |
406 | /// then calls your closure, giving it a `Weak<T>` to this allocation, | |
407 | /// and only afterwards completes the construction of the `Arc<T>` by placing | |
408 | /// the `T` returned from your closure into the allocation. | |
409 | /// | |
410 | /// Since the new `Arc<T>` is not fully-constructed until `Arc<T>::new_cyclic` | |
411 | /// returns, calling [`upgrade`] on the weak reference inside your closure will | |
412 | /// fail and result in a `None` value. | |
5099ac24 FG |
413 | /// |
414 | /// # Panics | |
04454e1e | 415 | /// |
5099ac24 FG |
416 | /// If `data_fn` panics, the panic is propagated to the caller, and the |
417 | /// temporary [`Weak<T>`] is dropped normally. | |
418 | /// | |
419 | /// # Example | |
04454e1e | 420 | /// |
3dfed10e | 421 | /// ``` |
04454e1e | 422 | /// # #![allow(dead_code)] |
3dfed10e XL |
423 | /// use std::sync::{Arc, Weak}; |
424 | /// | |
5099ac24 FG |
425 | /// struct Gadget { |
426 | /// me: Weak<Gadget>, | |
3dfed10e XL |
427 | /// } |
428 | /// | |
5099ac24 FG |
429 | /// impl Gadget { |
430 | /// /// Construct a reference counted Gadget. | |
431 | /// fn new() -> Arc<Self> { | |
04454e1e FG |
432 | /// // `me` is a `Weak<Gadget>` pointing at the new allocation of the |
433 | /// // `Arc` we're constructing. | |
434 | /// Arc::new_cyclic(|me| { | |
435 | /// // Create the actual struct here. | |
436 | /// Gadget { me: me.clone() } | |
437 | /// }) | |
5099ac24 FG |
438 | /// } |
439 | /// | |
440 | /// /// Return a reference counted pointer to Self. | |
441 | /// fn me(&self) -> Arc<Self> { | |
442 | /// self.me.upgrade().unwrap() | |
443 | /// } | |
444 | /// } | |
3dfed10e | 445 | /// ``` |
5099ac24 | 446 | /// [`upgrade`]: Weak::upgrade |
136023e0 | 447 | #[cfg(not(no_global_oom_handling))] |
3dfed10e | 448 | #[inline] |
5099ac24 FG |
449 | #[stable(feature = "arc_new_cyclic", since = "1.60.0")] |
450 | pub fn new_cyclic<F>(data_fn: F) -> Arc<T> | |
451 | where | |
452 | F: FnOnce(&Weak<T>) -> T, | |
453 | { | |
3dfed10e XL |
454 | // Construct the inner in the "uninitialized" state with a single |
455 | // weak reference. | |
923072b8 | 456 | let uninit_ptr: NonNull<_> = Box::leak(Box::new(ArcInner { |
3dfed10e XL |
457 | strong: atomic::AtomicUsize::new(0), |
458 | weak: atomic::AtomicUsize::new(1), | |
459 | data: mem::MaybeUninit::<T>::uninit(), | |
923072b8 | 460 | })) |
3dfed10e XL |
461 | .into(); |
462 | let init_ptr: NonNull<ArcInner<T>> = uninit_ptr.cast(); | |
463 | ||
add651ee | 464 | let weak = Weak { ptr: init_ptr, alloc: Global }; |
3dfed10e XL |
465 | |
466 | // It's important we don't give up ownership of the weak pointer, or | |
467 | // else the memory might be freed by the time `data_fn` returns. If | |
468 | // we really wanted to pass ownership, we could create an additional | |
469 | // weak pointer for ourselves, but this would result in additional | |
470 | // updates to the weak reference count which might not be necessary | |
471 | // otherwise. | |
472 | let data = data_fn(&weak); | |
473 | ||
474 | // Now we can properly initialize the inner value and turn our weak | |
475 | // reference into a strong reference. | |
3c0e092e | 476 | let strong = unsafe { |
3dfed10e | 477 | let inner = init_ptr.as_ptr(); |
5869c6ff | 478 | ptr::write(ptr::addr_of_mut!((*inner).data), data); |
3dfed10e XL |
479 | |
480 | // The above write to the data field must be visible to any threads which | |
481 | // observe a non-zero strong count. Therefore we need at least "Release" ordering | |
482 | // in order to synchronize with the `compare_exchange_weak` in `Weak::upgrade`. | |
483 | // | |
484 | // "Acquire" ordering is not required. When considering the possible behaviours | |
485 | // of `data_fn` we only need to look at what it could do with a reference to a | |
486 | // non-upgradeable `Weak`: | |
487 | // - It can *clone* the `Weak`, increasing the weak reference count. | |
488 | // - It can drop those clones, decreasing the weak reference count (but never to zero). | |
489 | // | |
490 | // These side effects do not impact us in any way, and no other side effects are | |
491 | // possible with safe code alone. | |
492 | let prev_value = (*inner).strong.fetch_add(1, Release); | |
493 | debug_assert_eq!(prev_value, 0, "No prior strong references should exist"); | |
3dfed10e | 494 | |
3c0e092e XL |
495 | Arc::from_inner(init_ptr) |
496 | }; | |
3dfed10e XL |
497 | |
498 | // Strong references should collectively own a shared weak reference, | |
499 | // so don't run the destructor for our old weak reference. | |
500 | mem::forget(weak); | |
501 | strong | |
502 | } | |
503 | ||
e1599b0c XL |
504 | /// Constructs a new `Arc` with uninitialized contents. |
505 | /// | |
506 | /// # Examples | |
507 | /// | |
508 | /// ``` | |
509 | /// #![feature(new_uninit)] | |
510 | /// #![feature(get_mut_unchecked)] | |
511 | /// | |
512 | /// use std::sync::Arc; | |
513 | /// | |
514 | /// let mut five = Arc::<u32>::new_uninit(); | |
515 | /// | |
5099ac24 FG |
516 | /// // Deferred initialization: |
517 | /// Arc::get_mut(&mut five).unwrap().write(5); | |
e1599b0c | 518 | /// |
5099ac24 | 519 | /// let five = unsafe { five.assume_init() }; |
e1599b0c XL |
520 | /// |
521 | /// assert_eq!(*five, 5) | |
522 | /// ``` | |
17df50a5 | 523 | #[cfg(not(no_global_oom_handling))] |
49aad941 | 524 | #[inline] |
e1599b0c | 525 | #[unstable(feature = "new_uninit", issue = "63291")] |
c295e0f8 | 526 | #[must_use] |
e1599b0c XL |
527 | pub fn new_uninit() -> Arc<mem::MaybeUninit<T>> { |
528 | unsafe { | |
3dfed10e XL |
529 | Arc::from_ptr(Arc::allocate_for_layout( |
530 | Layout::new::<T>(), | |
fc512014 | 531 | |layout| Global.allocate(layout), |
add651ee | 532 | <*mut u8>::cast, |
3dfed10e | 533 | )) |
e1599b0c XL |
534 | } |
535 | } | |
536 | ||
60c5eb7d XL |
537 | /// Constructs a new `Arc` with uninitialized contents, with the memory |
538 | /// being filled with `0` bytes. | |
539 | /// | |
540 | /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage | |
541 | /// of this method. | |
542 | /// | |
543 | /// # Examples | |
544 | /// | |
545 | /// ``` | |
546 | /// #![feature(new_uninit)] | |
547 | /// | |
548 | /// use std::sync::Arc; | |
549 | /// | |
550 | /// let zero = Arc::<u32>::new_zeroed(); | |
551 | /// let zero = unsafe { zero.assume_init() }; | |
552 | /// | |
553 | /// assert_eq!(*zero, 0) | |
554 | /// ``` | |
555 | /// | |
c295e0f8 | 556 | /// [zeroed]: mem::MaybeUninit::zeroed |
17df50a5 | 557 | #[cfg(not(no_global_oom_handling))] |
49aad941 | 558 | #[inline] |
60c5eb7d | 559 | #[unstable(feature = "new_uninit", issue = "63291")] |
c295e0f8 | 560 | #[must_use] |
60c5eb7d XL |
561 | pub fn new_zeroed() -> Arc<mem::MaybeUninit<T>> { |
562 | unsafe { | |
3dfed10e XL |
563 | Arc::from_ptr(Arc::allocate_for_layout( |
564 | Layout::new::<T>(), | |
fc512014 | 565 | |layout| Global.allocate_zeroed(layout), |
add651ee | 566 | <*mut u8>::cast, |
3dfed10e | 567 | )) |
60c5eb7d XL |
568 | } |
569 | } | |
570 | ||
0731742a XL |
571 | /// Constructs a new `Pin<Arc<T>>`. If `T` does not implement `Unpin`, then |
572 | /// `data` will be pinned in memory and unable to be moved. | |
136023e0 | 573 | #[cfg(not(no_global_oom_handling))] |
0731742a | 574 | #[stable(feature = "pin", since = "1.33.0")] |
c295e0f8 | 575 | #[must_use] |
0731742a | 576 | pub fn pin(data: T) -> Pin<Arc<T>> { |
0bf4aa26 XL |
577 | unsafe { Pin::new_unchecked(Arc::new(data)) } |
578 | } | |
579 | ||
136023e0 XL |
580 | /// Constructs a new `Pin<Arc<T>>`, return an error if allocation fails. |
581 | #[unstable(feature = "allocator_api", issue = "32838")] | |
582 | #[inline] | |
583 | pub fn try_pin(data: T) -> Result<Pin<Arc<T>>, AllocError> { | |
584 | unsafe { Ok(Pin::new_unchecked(Arc::try_new(data)?)) } | |
585 | } | |
586 | ||
5869c6ff XL |
587 | /// Constructs a new `Arc<T>`, returning an error if allocation fails. |
588 | /// | |
589 | /// # Examples | |
590 | /// | |
591 | /// ``` | |
592 | /// #![feature(allocator_api)] | |
593 | /// use std::sync::Arc; | |
594 | /// | |
595 | /// let five = Arc::try_new(5)?; | |
596 | /// # Ok::<(), std::alloc::AllocError>(()) | |
597 | /// ``` | |
598 | #[unstable(feature = "allocator_api", issue = "32838")] | |
599 | #[inline] | |
600 | pub fn try_new(data: T) -> Result<Arc<T>, AllocError> { | |
601 | // Start the weak pointer count as 1 which is the weak pointer that's | |
602 | // held by all the strong pointers (kinda), see std/rc.rs for more info | |
603 | let x: Box<_> = Box::try_new(ArcInner { | |
604 | strong: atomic::AtomicUsize::new(1), | |
605 | weak: atomic::AtomicUsize::new(1), | |
606 | data, | |
607 | })?; | |
3c0e092e | 608 | unsafe { Ok(Self::from_inner(Box::leak(x).into())) } |
5869c6ff XL |
609 | } |
610 | ||
611 | /// Constructs a new `Arc` with uninitialized contents, returning an error | |
612 | /// if allocation fails. | |
613 | /// | |
614 | /// # Examples | |
615 | /// | |
616 | /// ``` | |
617 | /// #![feature(new_uninit, allocator_api)] | |
618 | /// #![feature(get_mut_unchecked)] | |
619 | /// | |
620 | /// use std::sync::Arc; | |
621 | /// | |
622 | /// let mut five = Arc::<u32>::try_new_uninit()?; | |
623 | /// | |
5099ac24 FG |
624 | /// // Deferred initialization: |
625 | /// Arc::get_mut(&mut five).unwrap().write(5); | |
5869c6ff | 626 | /// |
5099ac24 | 627 | /// let five = unsafe { five.assume_init() }; |
5869c6ff XL |
628 | /// |
629 | /// assert_eq!(*five, 5); | |
630 | /// # Ok::<(), std::alloc::AllocError>(()) | |
631 | /// ``` | |
632 | #[unstable(feature = "allocator_api", issue = "32838")] | |
633 | // #[unstable(feature = "new_uninit", issue = "63291")] | |
634 | pub fn try_new_uninit() -> Result<Arc<mem::MaybeUninit<T>>, AllocError> { | |
635 | unsafe { | |
636 | Ok(Arc::from_ptr(Arc::try_allocate_for_layout( | |
637 | Layout::new::<T>(), | |
638 | |layout| Global.allocate(layout), | |
add651ee | 639 | <*mut u8>::cast, |
5869c6ff XL |
640 | )?)) |
641 | } | |
642 | } | |
643 | ||
644 | /// Constructs a new `Arc` with uninitialized contents, with the memory | |
645 | /// being filled with `0` bytes, returning an error if allocation fails. | |
646 | /// | |
647 | /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage | |
648 | /// of this method. | |
649 | /// | |
650 | /// # Examples | |
651 | /// | |
652 | /// ``` | |
653 | /// #![feature(new_uninit, allocator_api)] | |
654 | /// | |
655 | /// use std::sync::Arc; | |
656 | /// | |
657 | /// let zero = Arc::<u32>::try_new_zeroed()?; | |
658 | /// let zero = unsafe { zero.assume_init() }; | |
659 | /// | |
660 | /// assert_eq!(*zero, 0); | |
661 | /// # Ok::<(), std::alloc::AllocError>(()) | |
662 | /// ``` | |
663 | /// | |
664 | /// [zeroed]: mem::MaybeUninit::zeroed | |
665 | #[unstable(feature = "allocator_api", issue = "32838")] | |
666 | // #[unstable(feature = "new_uninit", issue = "63291")] | |
667 | pub fn try_new_zeroed() -> Result<Arc<mem::MaybeUninit<T>>, AllocError> { | |
668 | unsafe { | |
669 | Ok(Arc::from_ptr(Arc::try_allocate_for_layout( | |
670 | Layout::new::<T>(), | |
671 | |layout| Global.allocate_zeroed(layout), | |
add651ee | 672 | <*mut u8>::cast, |
5869c6ff XL |
673 | )?)) |
674 | } | |
675 | } | |
add651ee FG |
676 | } |
677 | ||
678 | impl<T, A: Allocator> Arc<T, A> { | |
679 | /// Returns a reference to the underlying allocator. | |
680 | /// | |
681 | /// Note: this is an associated function, which means that you have | |
682 | /// to call it as `Arc::allocator(&a)` instead of `a.allocator()`. This | |
683 | /// is so that there is no conflict with a method on the inner type. | |
684 | #[inline] | |
685 | #[unstable(feature = "allocator_api", issue = "32838")] | |
686 | pub fn allocator(this: &Self) -> &A { | |
687 | &this.alloc | |
688 | } | |
689 | /// Constructs a new `Arc<T>` in the provided allocator. | |
690 | /// | |
691 | /// # Examples | |
692 | /// | |
693 | /// ``` | |
694 | /// #![feature(allocator_api)] | |
695 | /// | |
696 | /// use std::sync::Arc; | |
697 | /// use std::alloc::System; | |
698 | /// | |
699 | /// let five = Arc::new_in(5, System); | |
700 | /// ``` | |
701 | #[inline] | |
702 | #[cfg(not(no_global_oom_handling))] | |
703 | #[unstable(feature = "allocator_api", issue = "32838")] | |
704 | pub fn new_in(data: T, alloc: A) -> Arc<T, A> { | |
705 | // Start the weak pointer count as 1 which is the weak pointer that's | |
706 | // held by all the strong pointers (kinda), see std/rc.rs for more info | |
707 | let x = Box::new_in( | |
708 | ArcInner { | |
709 | strong: atomic::AtomicUsize::new(1), | |
710 | weak: atomic::AtomicUsize::new(1), | |
711 | data, | |
712 | }, | |
713 | alloc, | |
714 | ); | |
715 | let (ptr, alloc) = Box::into_unique(x); | |
716 | unsafe { Self::from_inner_in(ptr.into(), alloc) } | |
717 | } | |
718 | ||
719 | /// Constructs a new `Arc` with uninitialized contents in the provided allocator. | |
720 | /// | |
721 | /// # Examples | |
722 | /// | |
723 | /// ``` | |
724 | /// #![feature(new_uninit)] | |
725 | /// #![feature(get_mut_unchecked)] | |
726 | /// #![feature(allocator_api)] | |
727 | /// | |
728 | /// use std::sync::Arc; | |
729 | /// use std::alloc::System; | |
730 | /// | |
731 | /// let mut five = Arc::<u32, _>::new_uninit_in(System); | |
732 | /// | |
733 | /// let five = unsafe { | |
734 | /// // Deferred initialization: | |
735 | /// Arc::get_mut_unchecked(&mut five).as_mut_ptr().write(5); | |
736 | /// | |
737 | /// five.assume_init() | |
738 | /// }; | |
739 | /// | |
740 | /// assert_eq!(*five, 5) | |
741 | /// ``` | |
742 | #[cfg(not(no_global_oom_handling))] | |
743 | #[unstable(feature = "allocator_api", issue = "32838")] | |
744 | // #[unstable(feature = "new_uninit", issue = "63291")] | |
745 | #[inline] | |
746 | pub fn new_uninit_in(alloc: A) -> Arc<mem::MaybeUninit<T>, A> { | |
747 | unsafe { | |
748 | Arc::from_ptr_in( | |
749 | Arc::allocate_for_layout( | |
750 | Layout::new::<T>(), | |
751 | |layout| alloc.allocate(layout), | |
752 | <*mut u8>::cast, | |
753 | ), | |
754 | alloc, | |
755 | ) | |
756 | } | |
757 | } | |
758 | ||
759 | /// Constructs a new `Arc` with uninitialized contents, with the memory | |
760 | /// being filled with `0` bytes, in the provided allocator. | |
761 | /// | |
762 | /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage | |
763 | /// of this method. | |
764 | /// | |
765 | /// # Examples | |
766 | /// | |
767 | /// ``` | |
768 | /// #![feature(new_uninit)] | |
769 | /// #![feature(allocator_api)] | |
770 | /// | |
771 | /// use std::sync::Arc; | |
772 | /// use std::alloc::System; | |
773 | /// | |
774 | /// let zero = Arc::<u32, _>::new_zeroed_in(System); | |
775 | /// let zero = unsafe { zero.assume_init() }; | |
776 | /// | |
777 | /// assert_eq!(*zero, 0) | |
778 | /// ``` | |
779 | /// | |
780 | /// [zeroed]: mem::MaybeUninit::zeroed | |
781 | #[cfg(not(no_global_oom_handling))] | |
782 | #[unstable(feature = "allocator_api", issue = "32838")] | |
783 | // #[unstable(feature = "new_uninit", issue = "63291")] | |
784 | #[inline] | |
785 | pub fn new_zeroed_in(alloc: A) -> Arc<mem::MaybeUninit<T>, A> { | |
786 | unsafe { | |
787 | Arc::from_ptr_in( | |
788 | Arc::allocate_for_layout( | |
789 | Layout::new::<T>(), | |
790 | |layout| alloc.allocate_zeroed(layout), | |
791 | <*mut u8>::cast, | |
792 | ), | |
793 | alloc, | |
794 | ) | |
795 | } | |
796 | } | |
797 | ||
798 | /// Constructs a new `Pin<Arc<T, A>>` in the provided allocator. If `T` does not implement `Unpin`, | |
799 | /// then `data` will be pinned in memory and unable to be moved. | |
800 | #[cfg(not(no_global_oom_handling))] | |
801 | #[unstable(feature = "allocator_api", issue = "32838")] | |
802 | #[inline] | |
803 | pub fn pin_in(data: T, alloc: A) -> Pin<Arc<T, A>> { | |
804 | unsafe { Pin::new_unchecked(Arc::new_in(data, alloc)) } | |
805 | } | |
806 | ||
807 | /// Constructs a new `Pin<Arc<T, A>>` in the provided allocator, return an error if allocation | |
808 | /// fails. | |
809 | #[inline] | |
810 | #[unstable(feature = "allocator_api", issue = "32838")] | |
811 | pub fn try_pin_in(data: T, alloc: A) -> Result<Pin<Arc<T, A>>, AllocError> { | |
812 | unsafe { Ok(Pin::new_unchecked(Arc::try_new_in(data, alloc)?)) } | |
813 | } | |
814 | ||
815 | /// Constructs a new `Arc<T, A>` in the provided allocator, returning an error if allocation fails. | |
816 | /// | |
817 | /// # Examples | |
818 | /// | |
819 | /// ``` | |
820 | /// #![feature(allocator_api)] | |
821 | /// | |
822 | /// use std::sync::Arc; | |
823 | /// use std::alloc::System; | |
824 | /// | |
825 | /// let five = Arc::try_new_in(5, System)?; | |
826 | /// # Ok::<(), std::alloc::AllocError>(()) | |
827 | /// ``` | |
828 | #[inline] | |
829 | #[unstable(feature = "allocator_api", issue = "32838")] | |
830 | #[inline] | |
831 | pub fn try_new_in(data: T, alloc: A) -> Result<Arc<T, A>, AllocError> { | |
832 | // Start the weak pointer count as 1 which is the weak pointer that's | |
833 | // held by all the strong pointers (kinda), see std/rc.rs for more info | |
834 | let x = Box::try_new_in( | |
835 | ArcInner { | |
836 | strong: atomic::AtomicUsize::new(1), | |
837 | weak: atomic::AtomicUsize::new(1), | |
838 | data, | |
839 | }, | |
840 | alloc, | |
841 | )?; | |
842 | let (ptr, alloc) = Box::into_unique(x); | |
843 | Ok(unsafe { Self::from_inner_in(ptr.into(), alloc) }) | |
844 | } | |
845 | ||
846 | /// Constructs a new `Arc` with uninitialized contents, in the provided allocator, returning an | |
847 | /// error if allocation fails. | |
848 | /// | |
849 | /// # Examples | |
850 | /// | |
851 | /// ``` | |
852 | /// #![feature(new_uninit, allocator_api)] | |
853 | /// #![feature(get_mut_unchecked)] | |
854 | /// | |
855 | /// use std::sync::Arc; | |
856 | /// use std::alloc::System; | |
857 | /// | |
858 | /// let mut five = Arc::<u32, _>::try_new_uninit_in(System)?; | |
859 | /// | |
860 | /// let five = unsafe { | |
861 | /// // Deferred initialization: | |
862 | /// Arc::get_mut_unchecked(&mut five).as_mut_ptr().write(5); | |
863 | /// | |
864 | /// five.assume_init() | |
865 | /// }; | |
866 | /// | |
867 | /// assert_eq!(*five, 5); | |
868 | /// # Ok::<(), std::alloc::AllocError>(()) | |
869 | /// ``` | |
870 | #[unstable(feature = "allocator_api", issue = "32838")] | |
871 | // #[unstable(feature = "new_uninit", issue = "63291")] | |
872 | #[inline] | |
873 | pub fn try_new_uninit_in(alloc: A) -> Result<Arc<mem::MaybeUninit<T>, A>, AllocError> { | |
874 | unsafe { | |
875 | Ok(Arc::from_ptr_in( | |
876 | Arc::try_allocate_for_layout( | |
877 | Layout::new::<T>(), | |
878 | |layout| alloc.allocate(layout), | |
879 | <*mut u8>::cast, | |
880 | )?, | |
881 | alloc, | |
882 | )) | |
883 | } | |
884 | } | |
885 | ||
886 | /// Constructs a new `Arc` with uninitialized contents, with the memory | |
887 | /// being filled with `0` bytes, in the provided allocator, returning an error if allocation | |
888 | /// fails. | |
889 | /// | |
890 | /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage | |
891 | /// of this method. | |
892 | /// | |
893 | /// # Examples | |
894 | /// | |
895 | /// ``` | |
896 | /// #![feature(new_uninit, allocator_api)] | |
897 | /// | |
898 | /// use std::sync::Arc; | |
899 | /// use std::alloc::System; | |
900 | /// | |
901 | /// let zero = Arc::<u32, _>::try_new_zeroed_in(System)?; | |
902 | /// let zero = unsafe { zero.assume_init() }; | |
903 | /// | |
904 | /// assert_eq!(*zero, 0); | |
905 | /// # Ok::<(), std::alloc::AllocError>(()) | |
906 | /// ``` | |
907 | /// | |
908 | /// [zeroed]: mem::MaybeUninit::zeroed | |
909 | #[unstable(feature = "allocator_api", issue = "32838")] | |
910 | // #[unstable(feature = "new_uninit", issue = "63291")] | |
911 | #[inline] | |
912 | pub fn try_new_zeroed_in(alloc: A) -> Result<Arc<mem::MaybeUninit<T>, A>, AllocError> { | |
913 | unsafe { | |
914 | Ok(Arc::from_ptr_in( | |
915 | Arc::try_allocate_for_layout( | |
916 | Layout::new::<T>(), | |
917 | |layout| alloc.allocate_zeroed(layout), | |
918 | <*mut u8>::cast, | |
919 | )?, | |
920 | alloc, | |
921 | )) | |
922 | } | |
923 | } | |
e74abb32 | 924 | /// Returns the inner value, if the `Arc` has exactly one strong reference. |
e9174d1e | 925 | /// |
3dfed10e | 926 | /// Otherwise, an [`Err`] is returned with the same `Arc` that was |
c30ab7b3 | 927 | /// passed in. |
e9174d1e | 928 | /// |
54a0048b SL |
929 | /// This will succeed even if there are outstanding weak references. |
930 | /// | |
9ffffee4 FG |
931 | /// It is strongly recommended to use [`Arc::into_inner`] instead if you don't |
932 | /// want to keep the `Arc` in the [`Err`] case. | |
933 | /// Immediately dropping the [`Err`] payload, like in the expression | |
934 | /// `Arc::try_unwrap(this).ok()`, can still cause the strong count to | |
935 | /// drop to zero and the inner value of the `Arc` to be dropped: | |
353b0b11 | 936 | /// For instance if two threads each execute this expression in parallel, then |
9ffffee4 FG |
937 | /// there is a race condition. The threads could first both check whether they |
938 | /// have the last clone of their `Arc` via `Arc::try_unwrap`, and then | |
939 | /// both drop their `Arc` in the call to [`ok`][`Result::ok`], | |
940 | /// taking the strong count from two down to zero. | |
941 | /// | |
e9174d1e SL |
942 | /// # Examples |
943 | /// | |
944 | /// ``` | |
945 | /// use std::sync::Arc; | |
946 | /// | |
947 | /// let x = Arc::new(3); | |
948 | /// assert_eq!(Arc::try_unwrap(x), Ok(3)); | |
949 | /// | |
950 | /// let x = Arc::new(4); | |
7cac9316 | 951 | /// let _y = Arc::clone(&x); |
c30ab7b3 | 952 | /// assert_eq!(*Arc::try_unwrap(x).unwrap_err(), 4); |
e9174d1e SL |
953 | /// ``` |
954 | #[inline] | |
955 | #[stable(feature = "arc_unique", since = "1.4.0")] | |
956 | pub fn try_unwrap(this: Self) -> Result<T, Self> { | |
f035d41b | 957 | if this.inner().strong.compare_exchange(1, 0, Relaxed, Relaxed).is_err() { |
92a42be0 | 958 | return Err(this); |
b039eaaf | 959 | } |
e9174d1e | 960 | |
ba9703b0 | 961 | acquire!(this.inner().strong); |
e9174d1e SL |
962 | |
963 | unsafe { | |
7cac9316 | 964 | let elem = ptr::read(&this.ptr.as_ref().data); |
add651ee | 965 | let alloc = ptr::read(&this.alloc); // copy the allocator |
e9174d1e SL |
966 | |
967 | // Make a weak pointer to clean up the implicit strong-weak reference | |
add651ee | 968 | let _weak = Weak { ptr: this.ptr, alloc }; |
e9174d1e SL |
969 | mem::forget(this); |
970 | ||
971 | Ok(elem) | |
972 | } | |
1a4d82fc | 973 | } |
9ffffee4 FG |
974 | |
975 | /// Returns the inner value, if the `Arc` has exactly one strong reference. | |
976 | /// | |
977 | /// Otherwise, [`None`] is returned and the `Arc` is dropped. | |
978 | /// | |
979 | /// This will succeed even if there are outstanding weak references. | |
980 | /// | |
981 | /// If `Arc::into_inner` is called on every clone of this `Arc`, | |
982 | /// it is guaranteed that exactly one of the calls returns the inner value. | |
983 | /// This means in particular that the inner value is not dropped. | |
984 | /// | |
985 | /// The similar expression `Arc::try_unwrap(this).ok()` does not | |
353b0b11 | 986 | /// offer such a guarantee. See the last example below |
9ffffee4 | 987 | /// and the documentation of [`Arc::try_unwrap`]. |
9ffffee4 FG |
988 | /// |
989 | /// # Examples | |
990 | /// | |
991 | /// Minimal example demonstrating the guarantee that `Arc::into_inner` gives. | |
992 | /// ``` | |
9ffffee4 FG |
993 | /// use std::sync::Arc; |
994 | /// | |
995 | /// let x = Arc::new(3); | |
996 | /// let y = Arc::clone(&x); | |
997 | /// | |
998 | /// // Two threads calling `Arc::into_inner` on both clones of an `Arc`: | |
999 | /// let x_thread = std::thread::spawn(|| Arc::into_inner(x)); | |
1000 | /// let y_thread = std::thread::spawn(|| Arc::into_inner(y)); | |
1001 | /// | |
1002 | /// let x_inner_value = x_thread.join().unwrap(); | |
1003 | /// let y_inner_value = y_thread.join().unwrap(); | |
1004 | /// | |
1005 | /// // One of the threads is guaranteed to receive the inner value: | |
1006 | /// assert!(matches!( | |
1007 | /// (x_inner_value, y_inner_value), | |
1008 | /// (None, Some(3)) | (Some(3), None) | |
1009 | /// )); | |
1010 | /// // The result could also be `(None, None)` if the threads called | |
1011 | /// // `Arc::try_unwrap(x).ok()` and `Arc::try_unwrap(y).ok()` instead. | |
1012 | /// ``` | |
1013 | /// | |
1014 | /// A more practical example demonstrating the need for `Arc::into_inner`: | |
1015 | /// ``` | |
9ffffee4 FG |
1016 | /// use std::sync::Arc; |
1017 | /// | |
1018 | /// // Definition of a simple singly linked list using `Arc`: | |
1019 | /// #[derive(Clone)] | |
1020 | /// struct LinkedList<T>(Option<Arc<Node<T>>>); | |
1021 | /// struct Node<T>(T, Option<Arc<Node<T>>>); | |
1022 | /// | |
1023 | /// // Dropping a long `LinkedList<T>` relying on the destructor of `Arc` | |
1024 | /// // can cause a stack overflow. To prevent this, we can provide a | |
1025 | /// // manual `Drop` implementation that does the destruction in a loop: | |
1026 | /// impl<T> Drop for LinkedList<T> { | |
1027 | /// fn drop(&mut self) { | |
1028 | /// let mut link = self.0.take(); | |
1029 | /// while let Some(arc_node) = link.take() { | |
1030 | /// if let Some(Node(_value, next)) = Arc::into_inner(arc_node) { | |
1031 | /// link = next; | |
1032 | /// } | |
1033 | /// } | |
1034 | /// } | |
1035 | /// } | |
1036 | /// | |
1037 | /// // Implementation of `new` and `push` omitted | |
1038 | /// impl<T> LinkedList<T> { | |
1039 | /// /* ... */ | |
1040 | /// # fn new() -> Self { | |
1041 | /// # LinkedList(None) | |
1042 | /// # } | |
1043 | /// # fn push(&mut self, x: T) { | |
1044 | /// # self.0 = Some(Arc::new(Node(x, self.0.take()))); | |
1045 | /// # } | |
1046 | /// } | |
1047 | /// | |
1048 | /// // The following code could have still caused a stack overflow | |
1049 | /// // despite the manual `Drop` impl if that `Drop` impl had used | |
1050 | /// // `Arc::try_unwrap(arc).ok()` instead of `Arc::into_inner(arc)`. | |
1051 | /// | |
1052 | /// // Create a long list and clone it | |
1053 | /// let mut x = LinkedList::new(); | |
1054 | /// for i in 0..100000 { | |
1055 | /// x.push(i); // Adds i to the front of x | |
1056 | /// } | |
1057 | /// let y = x.clone(); | |
1058 | /// | |
1059 | /// // Drop the clones in parallel | |
1060 | /// let x_thread = std::thread::spawn(|| drop(x)); | |
1061 | /// let y_thread = std::thread::spawn(|| drop(y)); | |
1062 | /// x_thread.join().unwrap(); | |
1063 | /// y_thread.join().unwrap(); | |
1064 | /// ``` | |
9ffffee4 | 1065 | #[inline] |
353b0b11 | 1066 | #[stable(feature = "arc_into_inner", since = "1.70.0")] |
9ffffee4 FG |
1067 | pub fn into_inner(this: Self) -> Option<T> { |
1068 | // Make sure that the ordinary `Drop` implementation isn’t called as well | |
1069 | let mut this = mem::ManuallyDrop::new(this); | |
1070 | ||
1071 | // Following the implementation of `drop` and `drop_slow` | |
1072 | if this.inner().strong.fetch_sub(1, Release) != 1 { | |
1073 | return None; | |
1074 | } | |
1075 | ||
1076 | acquire!(this.inner().strong); | |
1077 | ||
1078 | // SAFETY: This mirrors the line | |
1079 | // | |
1080 | // unsafe { ptr::drop_in_place(Self::get_mut_unchecked(self)) }; | |
1081 | // | |
1082 | // in `drop_slow`. Instead of dropping the value behind the pointer, | |
1083 | // it is read and eventually returned; `ptr::read` has the same | |
1084 | // safety conditions as `ptr::drop_in_place`. | |
add651ee | 1085 | |
9ffffee4 | 1086 | let inner = unsafe { ptr::read(Self::get_mut_unchecked(&mut this)) }; |
add651ee | 1087 | let alloc = unsafe { ptr::read(&this.alloc) }; |
9ffffee4 | 1088 | |
add651ee | 1089 | drop(Weak { ptr: this.ptr, alloc }); |
9ffffee4 FG |
1090 | |
1091 | Some(inner) | |
1092 | } | |
ea8adc8c | 1093 | } |
476ff2be | 1094 | |
e1599b0c | 1095 | impl<T> Arc<[T]> { |
3dfed10e | 1096 | /// Constructs a new atomically reference-counted slice with uninitialized contents. |
e1599b0c XL |
1097 | /// |
1098 | /// # Examples | |
1099 | /// | |
1100 | /// ``` | |
1101 | /// #![feature(new_uninit)] | |
1102 | /// #![feature(get_mut_unchecked)] | |
1103 | /// | |
1104 | /// use std::sync::Arc; | |
1105 | /// | |
1106 | /// let mut values = Arc::<[u32]>::new_uninit_slice(3); | |
1107 | /// | |
5099ac24 FG |
1108 | /// // Deferred initialization: |
1109 | /// let data = Arc::get_mut(&mut values).unwrap(); | |
1110 | /// data[0].write(1); | |
1111 | /// data[1].write(2); | |
1112 | /// data[2].write(3); | |
e1599b0c | 1113 | /// |
5099ac24 | 1114 | /// let values = unsafe { values.assume_init() }; |
e1599b0c XL |
1115 | /// |
1116 | /// assert_eq!(*values, [1, 2, 3]) | |
1117 | /// ``` | |
17df50a5 | 1118 | #[cfg(not(no_global_oom_handling))] |
49aad941 | 1119 | #[inline] |
e1599b0c | 1120 | #[unstable(feature = "new_uninit", issue = "63291")] |
c295e0f8 | 1121 | #[must_use] |
e1599b0c | 1122 | pub fn new_uninit_slice(len: usize) -> Arc<[mem::MaybeUninit<T>]> { |
dfeec247 | 1123 | unsafe { Arc::from_ptr(Arc::allocate_for_slice(len)) } |
e1599b0c | 1124 | } |
3dfed10e XL |
1125 | |
1126 | /// Constructs a new atomically reference-counted slice with uninitialized contents, with the memory being | |
1127 | /// filled with `0` bytes. | |
1128 | /// | |
1129 | /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and | |
1130 | /// incorrect usage of this method. | |
1131 | /// | |
1132 | /// # Examples | |
1133 | /// | |
1134 | /// ``` | |
1135 | /// #![feature(new_uninit)] | |
1136 | /// | |
1137 | /// use std::sync::Arc; | |
1138 | /// | |
1139 | /// let values = Arc::<[u32]>::new_zeroed_slice(3); | |
1140 | /// let values = unsafe { values.assume_init() }; | |
1141 | /// | |
1142 | /// assert_eq!(*values, [0, 0, 0]) | |
1143 | /// ``` | |
1144 | /// | |
c295e0f8 | 1145 | /// [zeroed]: mem::MaybeUninit::zeroed |
17df50a5 | 1146 | #[cfg(not(no_global_oom_handling))] |
49aad941 | 1147 | #[inline] |
3dfed10e | 1148 | #[unstable(feature = "new_uninit", issue = "63291")] |
c295e0f8 | 1149 | #[must_use] |
3dfed10e XL |
1150 | pub fn new_zeroed_slice(len: usize) -> Arc<[mem::MaybeUninit<T>]> { |
1151 | unsafe { | |
1152 | Arc::from_ptr(Arc::allocate_for_layout( | |
1153 | Layout::array::<T>(len).unwrap(), | |
fc512014 | 1154 | |layout| Global.allocate_zeroed(layout), |
3dfed10e XL |
1155 | |mem| { |
1156 | ptr::slice_from_raw_parts_mut(mem as *mut T, len) | |
1157 | as *mut ArcInner<[mem::MaybeUninit<T>]> | |
1158 | }, | |
1159 | )) | |
1160 | } | |
1161 | } | |
e1599b0c XL |
1162 | } |
1163 | ||
add651ee FG |
1164 | impl<T, A: Allocator> Arc<[T], A> { |
1165 | /// Constructs a new atomically reference-counted slice with uninitialized contents in the | |
1166 | /// provided allocator. | |
1167 | /// | |
1168 | /// # Examples | |
1169 | /// | |
1170 | /// ``` | |
1171 | /// #![feature(new_uninit)] | |
1172 | /// #![feature(get_mut_unchecked)] | |
1173 | /// #![feature(allocator_api)] | |
1174 | /// | |
1175 | /// use std::sync::Arc; | |
1176 | /// use std::alloc::System; | |
1177 | /// | |
1178 | /// let mut values = Arc::<[u32], _>::new_uninit_slice_in(3, System); | |
1179 | /// | |
1180 | /// let values = unsafe { | |
1181 | /// // Deferred initialization: | |
1182 | /// Arc::get_mut_unchecked(&mut values)[0].as_mut_ptr().write(1); | |
1183 | /// Arc::get_mut_unchecked(&mut values)[1].as_mut_ptr().write(2); | |
1184 | /// Arc::get_mut_unchecked(&mut values)[2].as_mut_ptr().write(3); | |
1185 | /// | |
1186 | /// values.assume_init() | |
1187 | /// }; | |
1188 | /// | |
1189 | /// assert_eq!(*values, [1, 2, 3]) | |
1190 | /// ``` | |
1191 | #[cfg(not(no_global_oom_handling))] | |
1192 | #[unstable(feature = "new_uninit", issue = "63291")] | |
1193 | #[inline] | |
1194 | pub fn new_uninit_slice_in(len: usize, alloc: A) -> Arc<[mem::MaybeUninit<T>], A> { | |
1195 | unsafe { Arc::from_ptr_in(Arc::allocate_for_slice_in(len, &alloc), alloc) } | |
1196 | } | |
1197 | ||
1198 | /// Constructs a new atomically reference-counted slice with uninitialized contents, with the memory being | |
1199 | /// filled with `0` bytes, in the provided allocator. | |
1200 | /// | |
1201 | /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and | |
1202 | /// incorrect usage of this method. | |
1203 | /// | |
1204 | /// # Examples | |
1205 | /// | |
1206 | /// ``` | |
1207 | /// #![feature(new_uninit)] | |
1208 | /// #![feature(allocator_api)] | |
1209 | /// | |
1210 | /// use std::sync::Arc; | |
1211 | /// use std::alloc::System; | |
1212 | /// | |
1213 | /// let values = Arc::<[u32], _>::new_zeroed_slice_in(3, System); | |
1214 | /// let values = unsafe { values.assume_init() }; | |
1215 | /// | |
1216 | /// assert_eq!(*values, [0, 0, 0]) | |
1217 | /// ``` | |
1218 | /// | |
1219 | /// [zeroed]: mem::MaybeUninit::zeroed | |
1220 | #[cfg(not(no_global_oom_handling))] | |
1221 | #[unstable(feature = "new_uninit", issue = "63291")] | |
1222 | #[inline] | |
1223 | pub fn new_zeroed_slice_in(len: usize, alloc: A) -> Arc<[mem::MaybeUninit<T>], A> { | |
1224 | unsafe { | |
1225 | Arc::from_ptr_in( | |
1226 | Arc::allocate_for_layout( | |
1227 | Layout::array::<T>(len).unwrap(), | |
1228 | |layout| alloc.allocate_zeroed(layout), | |
1229 | |mem| { | |
1230 | ptr::slice_from_raw_parts_mut(mem.cast::<T>(), len) | |
1231 | as *mut ArcInner<[mem::MaybeUninit<T>]> | |
1232 | }, | |
1233 | ), | |
1234 | alloc, | |
1235 | ) | |
1236 | } | |
1237 | } | |
1238 | } | |
1239 | ||
1240 | impl<T, A: Allocator> Arc<mem::MaybeUninit<T>, A> { | |
e1599b0c XL |
1241 | /// Converts to `Arc<T>`. |
1242 | /// | |
1243 | /// # Safety | |
1244 | /// | |
1245 | /// As with [`MaybeUninit::assume_init`], | |
e74abb32 | 1246 | /// it is up to the caller to guarantee that the inner value |
e1599b0c XL |
1247 | /// really is in an initialized state. |
1248 | /// Calling this when the content is not yet fully initialized | |
1249 | /// causes immediate undefined behavior. | |
1250 | /// | |
c295e0f8 | 1251 | /// [`MaybeUninit::assume_init`]: mem::MaybeUninit::assume_init |
e1599b0c XL |
1252 | /// |
1253 | /// # Examples | |
1254 | /// | |
1255 | /// ``` | |
1256 | /// #![feature(new_uninit)] | |
1257 | /// #![feature(get_mut_unchecked)] | |
1258 | /// | |
1259 | /// use std::sync::Arc; | |
1260 | /// | |
1261 | /// let mut five = Arc::<u32>::new_uninit(); | |
1262 | /// | |
5099ac24 FG |
1263 | /// // Deferred initialization: |
1264 | /// Arc::get_mut(&mut five).unwrap().write(5); | |
e1599b0c | 1265 | /// |
5099ac24 | 1266 | /// let five = unsafe { five.assume_init() }; |
e1599b0c XL |
1267 | /// |
1268 | /// assert_eq!(*five, 5) | |
1269 | /// ``` | |
1270 | #[unstable(feature = "new_uninit", issue = "63291")] | |
c295e0f8 | 1271 | #[must_use = "`self` will be dropped if the result is not used"] |
e1599b0c | 1272 | #[inline] |
add651ee FG |
1273 | pub unsafe fn assume_init(self) -> Arc<T, A> |
1274 | where | |
1275 | A: Clone, | |
1276 | { | |
1277 | let md_self = mem::ManuallyDrop::new(self); | |
1278 | unsafe { Arc::from_inner_in(md_self.ptr.cast(), md_self.alloc.clone()) } | |
e1599b0c XL |
1279 | } |
1280 | } | |
1281 | ||
add651ee | 1282 | impl<T, A: Allocator> Arc<[mem::MaybeUninit<T>], A> { |
e1599b0c XL |
1283 | /// Converts to `Arc<[T]>`. |
1284 | /// | |
1285 | /// # Safety | |
1286 | /// | |
1287 | /// As with [`MaybeUninit::assume_init`], | |
e74abb32 | 1288 | /// it is up to the caller to guarantee that the inner value |
e1599b0c XL |
1289 | /// really is in an initialized state. |
1290 | /// Calling this when the content is not yet fully initialized | |
1291 | /// causes immediate undefined behavior. | |
1292 | /// | |
c295e0f8 | 1293 | /// [`MaybeUninit::assume_init`]: mem::MaybeUninit::assume_init |
e1599b0c XL |
1294 | /// |
1295 | /// # Examples | |
1296 | /// | |
1297 | /// ``` | |
1298 | /// #![feature(new_uninit)] | |
1299 | /// #![feature(get_mut_unchecked)] | |
1300 | /// | |
1301 | /// use std::sync::Arc; | |
1302 | /// | |
1303 | /// let mut values = Arc::<[u32]>::new_uninit_slice(3); | |
1304 | /// | |
5099ac24 FG |
1305 | /// // Deferred initialization: |
1306 | /// let data = Arc::get_mut(&mut values).unwrap(); | |
1307 | /// data[0].write(1); | |
1308 | /// data[1].write(2); | |
1309 | /// data[2].write(3); | |
e1599b0c | 1310 | /// |
5099ac24 | 1311 | /// let values = unsafe { values.assume_init() }; |
e1599b0c XL |
1312 | /// |
1313 | /// assert_eq!(*values, [1, 2, 3]) | |
1314 | /// ``` | |
1315 | #[unstable(feature = "new_uninit", issue = "63291")] | |
c295e0f8 | 1316 | #[must_use = "`self` will be dropped if the result is not used"] |
e1599b0c | 1317 | #[inline] |
add651ee FG |
1318 | pub unsafe fn assume_init(self) -> Arc<[T], A> |
1319 | where | |
1320 | A: Clone, | |
1321 | { | |
1322 | let md_self = mem::ManuallyDrop::new(self); | |
1323 | unsafe { Arc::from_ptr_in(md_self.ptr.as_ptr() as _, md_self.alloc.clone()) } | |
e1599b0c XL |
1324 | } |
1325 | } | |
1326 | ||
ea8adc8c | 1327 | impl<T: ?Sized> Arc<T> { |
add651ee FG |
1328 | /// Constructs an `Arc<T>` from a raw pointer. |
1329 | /// | |
1330 | /// The raw pointer must have been previously returned by a call to | |
1331 | /// [`Arc<U>::into_raw`][into_raw] where `U` must have the same size and | |
1332 | /// alignment as `T`. This is trivially true if `U` is `T`. | |
1333 | /// Note that if `U` is not `T` but has the same size and alignment, this is | |
1334 | /// basically like transmuting references of different types. See | |
1335 | /// [`mem::transmute`][transmute] for more information on what | |
1336 | /// restrictions apply in this case. | |
1337 | /// | |
1338 | /// The user of `from_raw` has to make sure a specific value of `T` is only | |
1339 | /// dropped once. | |
1340 | /// | |
1341 | /// This function is unsafe because improper use may lead to memory unsafety, | |
1342 | /// even if the returned `Arc<T>` is never accessed. | |
1343 | /// | |
1344 | /// [into_raw]: Arc::into_raw | |
1345 | /// [transmute]: core::mem::transmute | |
1346 | /// | |
1347 | /// # Examples | |
1348 | /// | |
1349 | /// ``` | |
1350 | /// use std::sync::Arc; | |
1351 | /// | |
1352 | /// let x = Arc::new("hello".to_owned()); | |
1353 | /// let x_ptr = Arc::into_raw(x); | |
1354 | /// | |
1355 | /// unsafe { | |
1356 | /// // Convert back to an `Arc` to prevent leak. | |
1357 | /// let x = Arc::from_raw(x_ptr); | |
1358 | /// assert_eq!(&*x, "hello"); | |
1359 | /// | |
1360 | /// // Further calls to `Arc::from_raw(x_ptr)` would be memory-unsafe. | |
1361 | /// } | |
1362 | /// | |
1363 | /// // The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling! | |
1364 | /// ``` | |
1365 | #[inline] | |
1366 | #[stable(feature = "rc_raw", since = "1.17.0")] | |
1367 | pub unsafe fn from_raw(ptr: *const T) -> Self { | |
1368 | unsafe { Arc::from_raw_in(ptr, Global) } | |
1369 | } | |
1370 | ||
1371 | /// Increments the strong reference count on the `Arc<T>` associated with the | |
1372 | /// provided pointer by one. | |
1373 | /// | |
1374 | /// # Safety | |
1375 | /// | |
1376 | /// The pointer must have been obtained through `Arc::into_raw`, and the | |
1377 | /// associated `Arc` instance must be valid (i.e. the strong count must be at | |
1378 | /// least 1) for the duration of this method. | |
1379 | /// | |
1380 | /// # Examples | |
1381 | /// | |
1382 | /// ``` | |
1383 | /// use std::sync::Arc; | |
1384 | /// | |
1385 | /// let five = Arc::new(5); | |
1386 | /// | |
1387 | /// unsafe { | |
1388 | /// let ptr = Arc::into_raw(five); | |
1389 | /// Arc::increment_strong_count(ptr); | |
1390 | /// | |
1391 | /// // This assertion is deterministic because we haven't shared | |
1392 | /// // the `Arc` between threads. | |
1393 | /// let five = Arc::from_raw(ptr); | |
1394 | /// assert_eq!(2, Arc::strong_count(&five)); | |
1395 | /// } | |
1396 | /// ``` | |
1397 | #[inline] | |
1398 | #[stable(feature = "arc_mutate_strong_count", since = "1.51.0")] | |
1399 | pub unsafe fn increment_strong_count(ptr: *const T) { | |
1400 | unsafe { Arc::increment_strong_count_in(ptr, Global) } | |
1401 | } | |
1402 | ||
1403 | /// Decrements the strong reference count on the `Arc<T>` associated with the | |
1404 | /// provided pointer by one. | |
1405 | /// | |
1406 | /// # Safety | |
1407 | /// | |
1408 | /// The pointer must have been obtained through `Arc::into_raw`, and the | |
1409 | /// associated `Arc` instance must be valid (i.e. the strong count must be at | |
1410 | /// least 1) when invoking this method. This method can be used to release the final | |
1411 | /// `Arc` and backing storage, but **should not** be called after the final `Arc` has been | |
1412 | /// released. | |
1413 | /// | |
1414 | /// # Examples | |
1415 | /// | |
1416 | /// ``` | |
1417 | /// use std::sync::Arc; | |
1418 | /// | |
1419 | /// let five = Arc::new(5); | |
1420 | /// | |
1421 | /// unsafe { | |
1422 | /// let ptr = Arc::into_raw(five); | |
1423 | /// Arc::increment_strong_count(ptr); | |
1424 | /// | |
1425 | /// // Those assertions are deterministic because we haven't shared | |
1426 | /// // the `Arc` between threads. | |
1427 | /// let five = Arc::from_raw(ptr); | |
1428 | /// assert_eq!(2, Arc::strong_count(&five)); | |
1429 | /// Arc::decrement_strong_count(ptr); | |
1430 | /// assert_eq!(1, Arc::strong_count(&five)); | |
1431 | /// } | |
1432 | /// ``` | |
1433 | #[inline] | |
1434 | #[stable(feature = "arc_mutate_strong_count", since = "1.51.0")] | |
1435 | pub unsafe fn decrement_strong_count(ptr: *const T) { | |
1436 | unsafe { Arc::decrement_strong_count_in(ptr, Global) } | |
1437 | } | |
1438 | } | |
1439 | ||
1440 | impl<T: ?Sized, A: Allocator> Arc<T, A> { | |
476ff2be SL |
1441 | /// Consumes the `Arc`, returning the wrapped pointer. |
1442 | /// | |
1443 | /// To avoid a memory leak the pointer must be converted back to an `Arc` using | |
3dfed10e | 1444 | /// [`Arc::from_raw`]. |
476ff2be SL |
1445 | /// |
1446 | /// # Examples | |
1447 | /// | |
1448 | /// ``` | |
476ff2be SL |
1449 | /// use std::sync::Arc; |
1450 | /// | |
dc9dc135 | 1451 | /// let x = Arc::new("hello".to_owned()); |
476ff2be | 1452 | /// let x_ptr = Arc::into_raw(x); |
dc9dc135 | 1453 | /// assert_eq!(unsafe { &*x_ptr }, "hello"); |
476ff2be | 1454 | /// ``` |
3c0e092e | 1455 | #[must_use = "losing the pointer will leak memory"] |
8bb4bdeb | 1456 | #[stable(feature = "rc_raw", since = "1.17.0")] |
781aab86 | 1457 | #[cfg_attr(not(bootstrap), rustc_never_returns_null_ptr)] |
8bb4bdeb | 1458 | pub fn into_raw(this: Self) -> *const T { |
ba9703b0 XL |
1459 | let ptr = Self::as_ptr(&this); |
1460 | mem::forget(this); | |
1461 | ptr | |
1462 | } | |
1463 | ||
1464 | /// Provides a raw pointer to the data. | |
1465 | /// | |
3dfed10e | 1466 | /// The counts are not affected in any way and the `Arc` is not consumed. The pointer is valid for |
ba9703b0 XL |
1467 | /// as long as there are strong counts in the `Arc`. |
1468 | /// | |
1469 | /// # Examples | |
1470 | /// | |
1471 | /// ``` | |
ba9703b0 XL |
1472 | /// use std::sync::Arc; |
1473 | /// | |
1474 | /// let x = Arc::new("hello".to_owned()); | |
1475 | /// let y = Arc::clone(&x); | |
1476 | /// let x_ptr = Arc::as_ptr(&x); | |
1477 | /// assert_eq!(x_ptr, Arc::as_ptr(&y)); | |
1478 | /// assert_eq!(unsafe { &*x_ptr }, "hello"); | |
1479 | /// ``` | |
c295e0f8 | 1480 | #[must_use] |
f035d41b | 1481 | #[stable(feature = "rc_as_ptr", since = "1.45.0")] |
781aab86 | 1482 | #[cfg_attr(not(bootstrap), rustc_never_returns_null_ptr)] |
ba9703b0 | 1483 | pub fn as_ptr(this: &Self) -> *const T { |
dfeec247 | 1484 | let ptr: *mut ArcInner<T> = NonNull::as_ptr(this.ptr); |
dfeec247 | 1485 | |
f035d41b XL |
1486 | // SAFETY: This cannot go through Deref::deref or RcBoxPtr::inner because |
1487 | // this is required to retain raw/mut provenance such that e.g. `get_mut` can | |
1488 | // write through the pointer after the Rc is recovered through `from_raw`. | |
5869c6ff | 1489 | unsafe { ptr::addr_of_mut!((*ptr).data) } |
476ff2be SL |
1490 | } |
1491 | ||
add651ee | 1492 | /// Constructs an `Arc<T, A>` from a raw pointer. |
476ff2be | 1493 | /// |
ba9703b0 | 1494 | /// The raw pointer must have been previously returned by a call to |
add651ee | 1495 | /// [`Arc<U, A>::into_raw`][into_raw] where `U` must have the same size and |
ba9703b0 XL |
1496 | /// alignment as `T`. This is trivially true if `U` is `T`. |
1497 | /// Note that if `U` is not `T` but has the same size and alignment, this is | |
1498 | /// basically like transmuting references of different types. See | |
add651ee | 1499 | /// [`mem::transmute`] for more information on what |
ba9703b0 | 1500 | /// restrictions apply in this case. |
476ff2be | 1501 | /// |
add651ee FG |
1502 | /// The raw pointer must point to a block of memory allocated by `alloc` |
1503 | /// | |
ba9703b0 XL |
1504 | /// The user of `from_raw` has to make sure a specific value of `T` is only |
1505 | /// dropped once. | |
1506 | /// | |
1507 | /// This function is unsafe because improper use may lead to memory unsafety, | |
1508 | /// even if the returned `Arc<T>` is never accessed. | |
476ff2be | 1509 | /// |
3dfed10e | 1510 | /// [into_raw]: Arc::into_raw |
476ff2be SL |
1511 | /// |
1512 | /// # Examples | |
1513 | /// | |
1514 | /// ``` | |
add651ee FG |
1515 | /// #![feature(allocator_api)] |
1516 | /// | |
476ff2be | 1517 | /// use std::sync::Arc; |
add651ee | 1518 | /// use std::alloc::System; |
476ff2be | 1519 | /// |
add651ee | 1520 | /// let x = Arc::new_in("hello".to_owned(), System); |
476ff2be SL |
1521 | /// let x_ptr = Arc::into_raw(x); |
1522 | /// | |
1523 | /// unsafe { | |
1524 | /// // Convert back to an `Arc` to prevent leak. | |
add651ee | 1525 | /// let x = Arc::from_raw_in(x_ptr, System); |
dc9dc135 | 1526 | /// assert_eq!(&*x, "hello"); |
476ff2be | 1527 | /// |
e1599b0c | 1528 | /// // Further calls to `Arc::from_raw(x_ptr)` would be memory-unsafe. |
476ff2be SL |
1529 | /// } |
1530 | /// | |
1531 | /// // The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling! | |
1532 | /// ``` | |
add651ee FG |
1533 | #[inline] |
1534 | #[unstable(feature = "allocator_api", issue = "32838")] | |
1535 | pub unsafe fn from_raw_in(ptr: *const T, alloc: A) -> Self { | |
f035d41b XL |
1536 | unsafe { |
1537 | let offset = data_offset(ptr); | |
ea8adc8c | 1538 | |
f035d41b | 1539 | // Reverse the offset to find the original ArcInner. |
064997fb | 1540 | let arc_ptr = ptr.byte_sub(offset) as *mut ArcInner<T>; |
ea8adc8c | 1541 | |
add651ee | 1542 | Self::from_ptr_in(arc_ptr, alloc) |
f035d41b | 1543 | } |
476ff2be | 1544 | } |
1a4d82fc | 1545 | |
3dfed10e | 1546 | /// Creates a new [`Weak`] pointer to this allocation. |
1a4d82fc JJ |
1547 | /// |
1548 | /// # Examples | |
1549 | /// | |
1550 | /// ``` | |
1551 | /// use std::sync::Arc; | |
1552 | /// | |
85aaf69f | 1553 | /// let five = Arc::new(5); |
1a4d82fc | 1554 | /// |
e9174d1e | 1555 | /// let weak_five = Arc::downgrade(&five); |
1a4d82fc | 1556 | /// ``` |
c295e0f8 XL |
1557 | #[must_use = "this returns a new `Weak` pointer, \ |
1558 | without modifying the original `Arc`"] | |
e9174d1e | 1559 | #[stable(feature = "arc_weak", since = "1.4.0")] |
add651ee FG |
1560 | pub fn downgrade(this: &Self) -> Weak<T, A> |
1561 | where | |
1562 | A: Clone, | |
1563 | { | |
54a0048b SL |
1564 | // This Relaxed is OK because we're checking the value in the CAS |
1565 | // below. | |
1566 | let mut cur = this.inner().weak.load(Relaxed); | |
c1a9b12d | 1567 | |
54a0048b | 1568 | loop { |
c1a9b12d | 1569 | // check if the weak counter is currently "locked"; if so, spin. |
b039eaaf | 1570 | if cur == usize::MAX { |
29967ef6 | 1571 | hint::spin_loop(); |
54a0048b | 1572 | cur = this.inner().weak.load(Relaxed); |
92a42be0 | 1573 | continue; |
b039eaaf | 1574 | } |
c1a9b12d | 1575 | |
353b0b11 FG |
1576 | // We can't allow the refcount to increase much past `MAX_REFCOUNT`. |
1577 | assert!(cur <= MAX_REFCOUNT, "{}", INTERNAL_OVERFLOW_ERROR); | |
1578 | ||
c1a9b12d SL |
1579 | // NOTE: this code currently ignores the possibility of overflow |
1580 | // into usize::MAX; in general both Rc and Arc need to be adjusted | |
1581 | // to deal with overflow. | |
1582 | ||
1583 | // Unlike with Clone(), we need this to be an Acquire read to | |
1584 | // synchronize with the write coming from `is_unique`, so that the | |
1585 | // events prior to that write happen before this read. | |
54a0048b | 1586 | match this.inner().weak.compare_exchange_weak(cur, cur + 1, Acquire, Relaxed) { |
8faf50e0 XL |
1587 | Ok(_) => { |
1588 | // Make sure we do not create a dangling Weak | |
5869c6ff | 1589 | debug_assert!(!is_dangling(this.ptr.as_ptr())); |
add651ee | 1590 | return Weak { ptr: this.ptr, alloc: this.alloc.clone() }; |
8faf50e0 | 1591 | } |
54a0048b | 1592 | Err(old) => cur = old, |
c1a9b12d SL |
1593 | } |
1594 | } | |
1a4d82fc | 1595 | } |
1a4d82fc | 1596 | |
3dfed10e | 1597 | /// Gets the number of [`Weak`] pointers to this allocation. |
c30ab7b3 | 1598 | /// |
476ff2be SL |
1599 | /// # Safety |
1600 | /// | |
1601 | /// This method by itself is safe, but using it correctly requires extra care. | |
1602 | /// Another thread can change the weak count at any time, | |
1603 | /// including potentially between calling this method and acting on the result. | |
1604 | /// | |
c30ab7b3 SL |
1605 | /// # Examples |
1606 | /// | |
1607 | /// ``` | |
c30ab7b3 SL |
1608 | /// use std::sync::Arc; |
1609 | /// | |
1610 | /// let five = Arc::new(5); | |
1611 | /// let _weak_five = Arc::downgrade(&five); | |
1612 | /// | |
1613 | /// // This assertion is deterministic because we haven't shared | |
1614 | /// // the `Arc` or `Weak` between threads. | |
1615 | /// assert_eq!(1, Arc::weak_count(&five)); | |
1616 | /// ``` | |
62682a34 | 1617 | #[inline] |
3c0e092e | 1618 | #[must_use] |
476ff2be | 1619 | #[stable(feature = "arc_counts", since = "1.15.0")] |
e9174d1e | 1620 | pub fn weak_count(this: &Self) -> usize { |
781aab86 | 1621 | let cnt = this.inner().weak.load(Relaxed); |
3b2f2976 XL |
1622 | // If the weak count is currently locked, the value of the |
1623 | // count was 0 just before taking the lock. | |
1624 | if cnt == usize::MAX { 0 } else { cnt - 1 } | |
62682a34 SL |
1625 | } |
1626 | ||
e74abb32 | 1627 | /// Gets the number of strong (`Arc`) pointers to this allocation. |
c30ab7b3 | 1628 | /// |
476ff2be SL |
1629 | /// # Safety |
1630 | /// | |
1631 | /// This method by itself is safe, but using it correctly requires extra care. | |
1632 | /// Another thread can change the strong count at any time, | |
1633 | /// including potentially between calling this method and acting on the result. | |
c30ab7b3 SL |
1634 | /// |
1635 | /// # Examples | |
1636 | /// | |
1637 | /// ``` | |
c30ab7b3 SL |
1638 | /// use std::sync::Arc; |
1639 | /// | |
1640 | /// let five = Arc::new(5); | |
7cac9316 | 1641 | /// let _also_five = Arc::clone(&five); |
c30ab7b3 SL |
1642 | /// |
1643 | /// // This assertion is deterministic because we haven't shared | |
1644 | /// // the `Arc` between threads. | |
1645 | /// assert_eq!(2, Arc::strong_count(&five)); | |
1646 | /// ``` | |
62682a34 | 1647 | #[inline] |
3c0e092e | 1648 | #[must_use] |
476ff2be | 1649 | #[stable(feature = "arc_counts", since = "1.15.0")] |
e9174d1e | 1650 | pub fn strong_count(this: &Self) -> usize { |
781aab86 | 1651 | this.inner().strong.load(Relaxed) |
62682a34 SL |
1652 | } |
1653 | ||
f9f354fc XL |
1654 | /// Increments the strong reference count on the `Arc<T>` associated with the |
1655 | /// provided pointer by one. | |
1656 | /// | |
1657 | /// # Safety | |
1658 | /// | |
1659 | /// The pointer must have been obtained through `Arc::into_raw`, and the | |
1660 | /// associated `Arc` instance must be valid (i.e. the strong count must be at | |
add651ee FG |
1661 | /// least 1) for the duration of this method,, and `ptr` must point to a block of memory |
1662 | /// allocated by `alloc`. | |
f9f354fc XL |
1663 | /// |
1664 | /// # Examples | |
1665 | /// | |
1666 | /// ``` | |
add651ee FG |
1667 | /// #![feature(allocator_api)] |
1668 | /// | |
f9f354fc | 1669 | /// use std::sync::Arc; |
add651ee | 1670 | /// use std::alloc::System; |
f9f354fc | 1671 | /// |
add651ee | 1672 | /// let five = Arc::new_in(5, System); |
f9f354fc XL |
1673 | /// |
1674 | /// unsafe { | |
1675 | /// let ptr = Arc::into_raw(five); | |
add651ee | 1676 | /// Arc::increment_strong_count_in(ptr, System); |
f9f354fc XL |
1677 | /// |
1678 | /// // This assertion is deterministic because we haven't shared | |
1679 | /// // the `Arc` between threads. | |
add651ee | 1680 | /// let five = Arc::from_raw_in(ptr, System); |
f9f354fc XL |
1681 | /// assert_eq!(2, Arc::strong_count(&five)); |
1682 | /// } | |
1683 | /// ``` | |
1684 | #[inline] | |
add651ee FG |
1685 | #[unstable(feature = "allocator_api", issue = "32838")] |
1686 | pub unsafe fn increment_strong_count_in(ptr: *const T, alloc: A) | |
1687 | where | |
1688 | A: Clone, | |
1689 | { | |
f9f354fc | 1690 | // Retain Arc, but don't touch refcount by wrapping in ManuallyDrop |
add651ee | 1691 | let arc = unsafe { mem::ManuallyDrop::new(Arc::from_raw_in(ptr, alloc)) }; |
f9f354fc XL |
1692 | // Now increase refcount, but don't drop new refcount either |
1693 | let _arc_clone: mem::ManuallyDrop<_> = arc.clone(); | |
1694 | } | |
1695 | ||
1696 | /// Decrements the strong reference count on the `Arc<T>` associated with the | |
1697 | /// provided pointer by one. | |
1698 | /// | |
1699 | /// # Safety | |
1700 | /// | |
add651ee | 1701 | /// The pointer must have been obtained through `Arc::into_raw`, the |
f9f354fc | 1702 | /// associated `Arc` instance must be valid (i.e. the strong count must be at |
add651ee FG |
1703 | /// least 1) when invoking this method, and `ptr` must point to a block of memory |
1704 | /// allocated by `alloc`. This method can be used to release the final | |
f9f354fc XL |
1705 | /// `Arc` and backing storage, but **should not** be called after the final `Arc` has been |
1706 | /// released. | |
1707 | /// | |
1708 | /// # Examples | |
1709 | /// | |
1710 | /// ``` | |
add651ee FG |
1711 | /// #![feature(allocator_api)] |
1712 | /// | |
f9f354fc | 1713 | /// use std::sync::Arc; |
add651ee | 1714 | /// use std::alloc::System; |
f9f354fc | 1715 | /// |
add651ee | 1716 | /// let five = Arc::new_in(5, System); |
f9f354fc XL |
1717 | /// |
1718 | /// unsafe { | |
1719 | /// let ptr = Arc::into_raw(five); | |
add651ee | 1720 | /// Arc::increment_strong_count_in(ptr, System); |
f9f354fc XL |
1721 | /// |
1722 | /// // Those assertions are deterministic because we haven't shared | |
1723 | /// // the `Arc` between threads. | |
add651ee | 1724 | /// let five = Arc::from_raw_in(ptr, System); |
f9f354fc | 1725 | /// assert_eq!(2, Arc::strong_count(&five)); |
add651ee | 1726 | /// Arc::decrement_strong_count_in(ptr, System); |
f9f354fc XL |
1727 | /// assert_eq!(1, Arc::strong_count(&five)); |
1728 | /// } | |
1729 | /// ``` | |
1730 | #[inline] | |
add651ee FG |
1731 | #[unstable(feature = "allocator_api", issue = "32838")] |
1732 | pub unsafe fn decrement_strong_count_in(ptr: *const T, alloc: A) { | |
1733 | unsafe { drop(Arc::from_raw_in(ptr, alloc)) }; | |
f9f354fc XL |
1734 | } |
1735 | ||
1a4d82fc JJ |
1736 | #[inline] |
1737 | fn inner(&self) -> &ArcInner<T> { | |
c34b1796 AL |
1738 | // This unsafety is ok because while this arc is alive we're guaranteed |
1739 | // that the inner pointer is valid. Furthermore, we know that the | |
1740 | // `ArcInner` structure itself is `Sync` because the inner data is | |
1741 | // `Sync` as well, so we're ok loaning out an immutable pointer to these | |
1742 | // contents. | |
7cac9316 | 1743 | unsafe { self.ptr.as_ref() } |
1a4d82fc | 1744 | } |
c34b1796 AL |
1745 | |
1746 | // Non-inlined part of `drop`. | |
1747 | #[inline(never)] | |
1748 | unsafe fn drop_slow(&mut self) { | |
94222f64 XL |
1749 | // Destroy the data at this time, even though we must not free the box |
1750 | // allocation itself (there might still be weak pointers lying around). | |
f035d41b | 1751 | unsafe { ptr::drop_in_place(Self::get_mut_unchecked(self)) }; |
c34b1796 | 1752 | |
f9f354fc | 1753 | // Drop the weak ref collectively held by all strong references |
add651ee FG |
1754 | // Take a reference to `self.alloc` instead of cloning because 1. it'll |
1755 | // last long enough, and 2. you should be able to drop `Arc`s with | |
1756 | // unclonable allocators | |
1757 | drop(Weak { ptr: self.ptr, alloc: &self.alloc }); | |
c34b1796 | 1758 | } |
9e0c209e | 1759 | |
2b03887a | 1760 | /// Returns `true` if the two `Arc`s point to the same allocation in a vein similar to |
fe692bf9 | 1761 | /// [`ptr::eq`]. This function ignores the metadata of `dyn Trait` pointers. |
9e0c209e SL |
1762 | /// |
1763 | /// # Examples | |
1764 | /// | |
1765 | /// ``` | |
9e0c209e SL |
1766 | /// use std::sync::Arc; |
1767 | /// | |
1768 | /// let five = Arc::new(5); | |
7cac9316 | 1769 | /// let same_five = Arc::clone(&five); |
9e0c209e SL |
1770 | /// let other_five = Arc::new(5); |
1771 | /// | |
1772 | /// assert!(Arc::ptr_eq(&five, &same_five)); | |
1773 | /// assert!(!Arc::ptr_eq(&five, &other_five)); | |
1774 | /// ``` | |
e74abb32 | 1775 | /// |
c295e0f8 | 1776 | /// [`ptr::eq`]: core::ptr::eq "ptr::eq" |
3c0e092e XL |
1777 | #[inline] |
1778 | #[must_use] | |
1779 | #[stable(feature = "ptr_eq", since = "1.17.0")] | |
9e0c209e | 1780 | pub fn ptr_eq(this: &Self, other: &Self) -> bool { |
fe692bf9 | 1781 | this.ptr.as_ptr() as *const () == other.ptr.as_ptr() as *const () |
9e0c209e | 1782 | } |
1a4d82fc JJ |
1783 | } |
1784 | ||
3b2f2976 | 1785 | impl<T: ?Sized> Arc<T> { |
416331ca | 1786 | /// Allocates an `ArcInner<T>` with sufficient space for |
e74abb32 | 1787 | /// a possibly-unsized inner value where the value has the layout provided. |
416331ca XL |
1788 | /// |
1789 | /// The function `mem_to_arcinner` is called with the data pointer | |
1790 | /// and must return back a (potentially fat)-pointer for the `ArcInner<T>`. | |
17df50a5 | 1791 | #[cfg(not(no_global_oom_handling))] |
e1599b0c | 1792 | unsafe fn allocate_for_layout( |
416331ca | 1793 | value_layout: Layout, |
1b1a35ee | 1794 | allocate: impl FnOnce(Layout) -> Result<NonNull<[u8]>, AllocError>, |
dfeec247 | 1795 | mem_to_arcinner: impl FnOnce(*mut u8) -> *mut ArcInner<T>, |
416331ca | 1796 | ) -> *mut ArcInner<T> { |
487cf647 | 1797 | let layout = arcinner_layout_for_value_layout(value_layout); |
49aad941 FG |
1798 | |
1799 | let ptr = allocate(layout).unwrap_or_else(|_| handle_alloc_error(layout)); | |
1800 | ||
1801 | unsafe { Self::initialize_arcinner(ptr, layout, mem_to_arcinner) } | |
5869c6ff XL |
1802 | } |
1803 | ||
1804 | /// Allocates an `ArcInner<T>` with sufficient space for | |
1805 | /// a possibly-unsized inner value where the value has the layout provided, | |
1806 | /// returning an error if allocation fails. | |
1807 | /// | |
1808 | /// The function `mem_to_arcinner` is called with the data pointer | |
1809 | /// and must return back a (potentially fat)-pointer for the `ArcInner<T>`. | |
1810 | unsafe fn try_allocate_for_layout( | |
1811 | value_layout: Layout, | |
1812 | allocate: impl FnOnce(Layout) -> Result<NonNull<[u8]>, AllocError>, | |
1813 | mem_to_arcinner: impl FnOnce(*mut u8) -> *mut ArcInner<T>, | |
1814 | ) -> Result<*mut ArcInner<T>, AllocError> { | |
487cf647 | 1815 | let layout = arcinner_layout_for_value_layout(value_layout); |
3b2f2976 | 1816 | |
5869c6ff | 1817 | let ptr = allocate(layout)?; |
3b2f2976 | 1818 | |
49aad941 FG |
1819 | let inner = unsafe { Self::initialize_arcinner(ptr, layout, mem_to_arcinner) }; |
1820 | ||
1821 | Ok(inner) | |
1822 | } | |
1823 | ||
1824 | unsafe fn initialize_arcinner( | |
1825 | ptr: NonNull<[u8]>, | |
1826 | layout: Layout, | |
1827 | mem_to_arcinner: impl FnOnce(*mut u8) -> *mut ArcInner<T>, | |
1828 | ) -> *mut ArcInner<T> { | |
3dfed10e | 1829 | let inner = mem_to_arcinner(ptr.as_non_null_ptr().as_ptr()); |
f035d41b | 1830 | debug_assert_eq!(unsafe { Layout::for_value(&*inner) }, layout); |
3b2f2976 | 1831 | |
f035d41b XL |
1832 | unsafe { |
1833 | ptr::write(&mut (*inner).strong, atomic::AtomicUsize::new(1)); | |
1834 | ptr::write(&mut (*inner).weak, atomic::AtomicUsize::new(1)); | |
1835 | } | |
3b2f2976 | 1836 | |
49aad941 | 1837 | inner |
3b2f2976 | 1838 | } |
add651ee | 1839 | } |
3b2f2976 | 1840 | |
add651ee | 1841 | impl<T: ?Sized, A: Allocator> Arc<T, A> { |
e74abb32 | 1842 | /// Allocates an `ArcInner<T>` with sufficient space for an unsized inner value. |
add651ee | 1843 | #[inline] |
17df50a5 | 1844 | #[cfg(not(no_global_oom_handling))] |
add651ee | 1845 | unsafe fn allocate_for_ptr_in(ptr: *const T, alloc: &A) -> *mut ArcInner<T> { |
416331ca | 1846 | // Allocate for the `ArcInner<T>` using the given value. |
f035d41b | 1847 | unsafe { |
add651ee | 1848 | Arc::allocate_for_layout( |
3dfed10e | 1849 | Layout::for_value(&*ptr), |
add651ee | 1850 | |layout| alloc.allocate(layout), |
2b03887a | 1851 | |mem| mem.with_metadata_of(ptr as *const ArcInner<T>), |
3dfed10e | 1852 | ) |
f035d41b | 1853 | } |
416331ca XL |
1854 | } |
1855 | ||
17df50a5 | 1856 | #[cfg(not(no_global_oom_handling))] |
add651ee | 1857 | fn from_box_in(src: Box<T, A>) -> Arc<T, A> { |
3b2f2976 | 1858 | unsafe { |
fe692bf9 | 1859 | let value_size = size_of_val(&*src); |
add651ee | 1860 | let ptr = Self::allocate_for_ptr_in(&*src, Box::allocator(&src)); |
3b2f2976 XL |
1861 | |
1862 | // Copy value as bytes | |
1863 | ptr::copy_nonoverlapping( | |
fe692bf9 | 1864 | &*src as *const T as *const u8, |
3b2f2976 | 1865 | &mut (*ptr).data as *mut _ as *mut u8, |
dfeec247 XL |
1866 | value_size, |
1867 | ); | |
3b2f2976 XL |
1868 | |
1869 | // Free the allocation without dropping its contents | |
add651ee FG |
1870 | let (bptr, alloc) = Box::into_raw_with_allocator(src); |
1871 | let src = Box::from_raw(bptr as *mut mem::ManuallyDrop<T>); | |
fe692bf9 | 1872 | drop(src); |
3b2f2976 | 1873 | |
add651ee | 1874 | Self::from_ptr_in(ptr, alloc) |
3b2f2976 XL |
1875 | } |
1876 | } | |
1877 | } | |
1878 | ||
416331ca XL |
1879 | impl<T> Arc<[T]> { |
1880 | /// Allocates an `ArcInner<[T]>` with the given length. | |
17df50a5 | 1881 | #[cfg(not(no_global_oom_handling))] |
416331ca | 1882 | unsafe fn allocate_for_slice(len: usize) -> *mut ArcInner<[T]> { |
f035d41b | 1883 | unsafe { |
3dfed10e XL |
1884 | Self::allocate_for_layout( |
1885 | Layout::array::<T>(len).unwrap(), | |
fc512014 | 1886 | |layout| Global.allocate(layout), |
add651ee | 1887 | |mem| ptr::slice_from_raw_parts_mut(mem.cast::<T>(), len) as *mut ArcInner<[T]>, |
3dfed10e | 1888 | ) |
f035d41b | 1889 | } |
416331ca | 1890 | } |
416331ca | 1891 | |
487cf647 | 1892 | /// Copy elements from slice into newly allocated `Arc<[T]>` |
416331ca XL |
1893 | /// |
1894 | /// Unsafe because the caller must either take ownership or bind `T: Copy`. | |
17df50a5 | 1895 | #[cfg(not(no_global_oom_handling))] |
3b2f2976 | 1896 | unsafe fn copy_from_slice(v: &[T]) -> Arc<[T]> { |
f035d41b XL |
1897 | unsafe { |
1898 | let ptr = Self::allocate_for_slice(v.len()); | |
3b2f2976 | 1899 | |
f035d41b | 1900 | ptr::copy_nonoverlapping(v.as_ptr(), &mut (*ptr).data as *mut [T] as *mut T, v.len()); |
3b2f2976 | 1901 | |
f035d41b XL |
1902 | Self::from_ptr(ptr) |
1903 | } | |
3b2f2976 | 1904 | } |
3b2f2976 | 1905 | |
416331ca XL |
1906 | /// Constructs an `Arc<[T]>` from an iterator known to be of a certain size. |
1907 | /// | |
1908 | /// Behavior is undefined should the size be wrong. | |
17df50a5 | 1909 | #[cfg(not(no_global_oom_handling))] |
353b0b11 | 1910 | unsafe fn from_iter_exact(iter: impl Iterator<Item = T>, len: usize) -> Arc<[T]> { |
3b2f2976 XL |
1911 | // Panic guard while cloning T elements. |
1912 | // In the event of a panic, elements that have been written | |
1913 | // into the new ArcInner will be dropped, then the memory freed. | |
1914 | struct Guard<T> { | |
83c7162d | 1915 | mem: NonNull<u8>, |
3b2f2976 XL |
1916 | elems: *mut T, |
1917 | layout: Layout, | |
1918 | n_elems: usize, | |
1919 | } | |
1920 | ||
1921 | impl<T> Drop for Guard<T> { | |
1922 | fn drop(&mut self) { | |
3b2f2976 XL |
1923 | unsafe { |
1924 | let slice = from_raw_parts_mut(self.elems, self.n_elems); | |
1925 | ptr::drop_in_place(slice); | |
1926 | ||
fc512014 | 1927 | Global.deallocate(self.mem, self.layout); |
3b2f2976 XL |
1928 | } |
1929 | } | |
1930 | } | |
1931 | ||
f035d41b XL |
1932 | unsafe { |
1933 | let ptr = Self::allocate_for_slice(len); | |
3b2f2976 | 1934 | |
f035d41b XL |
1935 | let mem = ptr as *mut _ as *mut u8; |
1936 | let layout = Layout::for_value(&*ptr); | |
3b2f2976 | 1937 | |
f035d41b XL |
1938 | // Pointer to first element |
1939 | let elems = &mut (*ptr).data as *mut [T] as *mut T; | |
3b2f2976 | 1940 | |
f035d41b | 1941 | let mut guard = Guard { mem: NonNull::new_unchecked(mem), elems, layout, n_elems: 0 }; |
3b2f2976 | 1942 | |
f035d41b XL |
1943 | for (i, item) in iter.enumerate() { |
1944 | ptr::write(elems.add(i), item); | |
1945 | guard.n_elems += 1; | |
1946 | } | |
416331ca | 1947 | |
f035d41b XL |
1948 | // All clear. Forget the guard so it doesn't free the new ArcInner. |
1949 | mem::forget(guard); | |
416331ca | 1950 | |
f035d41b XL |
1951 | Self::from_ptr(ptr) |
1952 | } | |
416331ca XL |
1953 | } |
1954 | } | |
3b2f2976 | 1955 | |
add651ee FG |
1956 | impl<T, A: Allocator> Arc<[T], A> { |
1957 | /// Allocates an `ArcInner<[T]>` with the given length. | |
1958 | #[inline] | |
1959 | #[cfg(not(no_global_oom_handling))] | |
1960 | unsafe fn allocate_for_slice_in(len: usize, alloc: &A) -> *mut ArcInner<[T]> { | |
1961 | unsafe { | |
1962 | Arc::allocate_for_layout( | |
1963 | Layout::array::<T>(len).unwrap(), | |
1964 | |layout| alloc.allocate(layout), | |
1965 | |mem| ptr::slice_from_raw_parts_mut(mem.cast::<T>(), len) as *mut ArcInner<[T]>, | |
1966 | ) | |
1967 | } | |
1968 | } | |
1969 | } | |
1970 | ||
416331ca | 1971 | /// Specialization trait used for `From<&[T]>`. |
17df50a5 | 1972 | #[cfg(not(no_global_oom_handling))] |
416331ca XL |
1973 | trait ArcFromSlice<T> { |
1974 | fn from_slice(slice: &[T]) -> Self; | |
1975 | } | |
3b2f2976 | 1976 | |
17df50a5 | 1977 | #[cfg(not(no_global_oom_handling))] |
416331ca XL |
1978 | impl<T: Clone> ArcFromSlice<T> for Arc<[T]> { |
1979 | #[inline] | |
1980 | default fn from_slice(v: &[T]) -> Self { | |
dfeec247 | 1981 | unsafe { Self::from_iter_exact(v.iter().cloned(), v.len()) } |
3b2f2976 XL |
1982 | } |
1983 | } | |
1984 | ||
17df50a5 | 1985 | #[cfg(not(no_global_oom_handling))] |
3b2f2976 XL |
1986 | impl<T: Copy> ArcFromSlice<T> for Arc<[T]> { |
1987 | #[inline] | |
1988 | fn from_slice(v: &[T]) -> Self { | |
1989 | unsafe { Arc::copy_from_slice(v) } | |
1990 | } | |
1991 | } | |
1992 | ||
85aaf69f | 1993 | #[stable(feature = "rust1", since = "1.0.0")] |
add651ee | 1994 | impl<T: ?Sized, A: Allocator + Clone> Clone for Arc<T, A> { |
c30ab7b3 | 1995 | /// Makes a clone of the `Arc` pointer. |
1a4d82fc | 1996 | /// |
e74abb32 | 1997 | /// This creates another pointer to the same allocation, increasing the |
c30ab7b3 | 1998 | /// strong reference count. |
1a4d82fc JJ |
1999 | /// |
2000 | /// # Examples | |
2001 | /// | |
2002 | /// ``` | |
2003 | /// use std::sync::Arc; | |
2004 | /// | |
85aaf69f | 2005 | /// let five = Arc::new(5); |
1a4d82fc | 2006 | /// |
0bf4aa26 | 2007 | /// let _ = Arc::clone(&five); |
1a4d82fc JJ |
2008 | /// ``` |
2009 | #[inline] | |
add651ee | 2010 | fn clone(&self) -> Arc<T, A> { |
c34b1796 AL |
2011 | // Using a relaxed ordering is alright here, as knowledge of the |
2012 | // original reference prevents other threads from erroneously deleting | |
2013 | // the object. | |
1a4d82fc | 2014 | // |
c34b1796 AL |
2015 | // As explained in the [Boost documentation][1], Increasing the |
2016 | // reference counter can always be done with memory_order_relaxed: New | |
2017 | // references to an object can only be formed from an existing | |
2018 | // reference, and passing an existing reference from one thread to | |
2019 | // another must already provide any required synchronization. | |
1a4d82fc JJ |
2020 | // |
2021 | // [1]: (www.boost.org/doc/libs/1_55_0/doc/html/atomic/usage_examples.html) | |
c1a9b12d SL |
2022 | let old_size = self.inner().strong.fetch_add(1, Relaxed); |
2023 | ||
923072b8 FG |
2024 | // However we need to guard against massive refcounts in case someone is `mem::forget`ing |
2025 | // Arcs. If we don't do this the count can overflow and users will use-after free. This | |
2026 | // branch will never be taken in any realistic program. We abort because such a program is | |
2027 | // incredibly degenerate, and we don't care to support it. | |
c1a9b12d | 2028 | // |
923072b8 FG |
2029 | // This check is not 100% water-proof: we error when the refcount grows beyond `isize::MAX`. |
2030 | // But we do that check *after* having done the increment, so there is a chance here that | |
2031 | // the worst already happened and we actually do overflow the `usize` counter. However, that | |
2032 | // requires the counter to grow from `isize::MAX` to `usize::MAX` between the increment | |
2033 | // above and the `abort` below, which seems exceedingly unlikely. | |
353b0b11 FG |
2034 | // |
2035 | // This is a global invariant, and also applies when using a compare-exchange loop to increment | |
2036 | // counters in other methods. | |
2037 | // Otherwise, the counter could be brought to an almost-overflow using a compare-exchange loop, | |
2038 | // and then overflow using a few `fetch_add`s. | |
c1a9b12d | 2039 | if old_size > MAX_REFCOUNT { |
f035d41b | 2040 | abort(); |
c1a9b12d SL |
2041 | } |
2042 | ||
add651ee | 2043 | unsafe { Self::from_inner_in(self.ptr, self.alloc.clone()) } |
1a4d82fc JJ |
2044 | } |
2045 | } | |
2046 | ||
85aaf69f | 2047 | #[stable(feature = "rust1", since = "1.0.0")] |
add651ee | 2048 | impl<T: ?Sized, A: Allocator> Deref for Arc<T, A> { |
1a4d82fc JJ |
2049 | type Target = T; |
2050 | ||
2051 | #[inline] | |
2052 | fn deref(&self) -> &T { | |
2053 | &self.inner().data | |
2054 | } | |
2055 | } | |
2056 | ||
dfeec247 | 2057 | #[unstable(feature = "receiver_trait", issue = "none")] |
0731742a XL |
2058 | impl<T: ?Sized> Receiver for Arc<T> {} |
2059 | ||
add651ee | 2060 | impl<T: Clone, A: Allocator + Clone> Arc<T, A> { |
c30ab7b3 SL |
2061 | /// Makes a mutable reference into the given `Arc`. |
2062 | /// | |
94222f64 XL |
2063 | /// If there are other `Arc` pointers to the same allocation, then `make_mut` will |
2064 | /// [`clone`] the inner value to a new allocation to ensure unique ownership. This is also | |
2065 | /// referred to as clone-on-write. | |
e74abb32 | 2066 | /// |
94222f64 | 2067 | /// However, if there are no other `Arc` pointers to this allocation, but some [`Weak`] |
923072b8 | 2068 | /// pointers, then the [`Weak`] pointers will be dissociated and the inner value will not |
94222f64 | 2069 | /// be cloned. |
1a4d82fc | 2070 | /// |
94222f64 | 2071 | /// See also [`get_mut`], which will fail rather than cloning the inner value |
923072b8 | 2072 | /// or dissociating [`Weak`] pointers. |
c30ab7b3 | 2073 | /// |
94222f64 XL |
2074 | /// [`clone`]: Clone::clone |
2075 | /// [`get_mut`]: Arc::get_mut | |
62682a34 | 2076 | /// |
1a4d82fc JJ |
2077 | /// # Examples |
2078 | /// | |
2079 | /// ``` | |
2080 | /// use std::sync::Arc; | |
2081 | /// | |
e9174d1e SL |
2082 | /// let mut data = Arc::new(5); |
2083 | /// | |
2084 | /// *Arc::make_mut(&mut data) += 1; // Won't clone anything | |
7cac9316 | 2085 | /// let mut other_data = Arc::clone(&data); // Won't clone inner data |
e9174d1e SL |
2086 | /// *Arc::make_mut(&mut data) += 1; // Clones inner data |
2087 | /// *Arc::make_mut(&mut data) += 1; // Won't clone anything | |
2088 | /// *Arc::make_mut(&mut other_data) *= 2; // Won't clone anything | |
2089 | /// | |
e74abb32 | 2090 | /// // Now `data` and `other_data` point to different allocations. |
e9174d1e SL |
2091 | /// assert_eq!(*data, 8); |
2092 | /// assert_eq!(*other_data, 12); | |
1a4d82fc | 2093 | /// ``` |
94222f64 | 2094 | /// |
923072b8 | 2095 | /// [`Weak`] pointers will be dissociated: |
94222f64 XL |
2096 | /// |
2097 | /// ``` | |
2098 | /// use std::sync::Arc; | |
2099 | /// | |
2100 | /// let mut data = Arc::new(75); | |
2101 | /// let weak = Arc::downgrade(&data); | |
2102 | /// | |
2103 | /// assert!(75 == *data); | |
2104 | /// assert!(75 == *weak.upgrade().unwrap()); | |
2105 | /// | |
2106 | /// *Arc::make_mut(&mut data) += 1; | |
2107 | /// | |
2108 | /// assert!(76 == *data); | |
2109 | /// assert!(weak.upgrade().is_none()); | |
2110 | /// ``` | |
17df50a5 | 2111 | #[cfg(not(no_global_oom_handling))] |
1a4d82fc | 2112 | #[inline] |
e9174d1e SL |
2113 | #[stable(feature = "arc_unique", since = "1.4.0")] |
2114 | pub fn make_mut(this: &mut Self) -> &mut T { | |
c1a9b12d SL |
2115 | // Note that we hold both a strong reference and a weak reference. |
2116 | // Thus, releasing our strong reference only will not, by itself, cause | |
2117 | // the memory to be deallocated. | |
62682a34 | 2118 | // |
c1a9b12d SL |
2119 | // Use Acquire to ensure that we see any writes to `weak` that happen |
2120 | // before release writes (i.e., decrements) to `strong`. Since we hold a | |
2121 | // weak count, there's no chance the ArcInner itself could be | |
2122 | // deallocated. | |
54a0048b | 2123 | if this.inner().strong.compare_exchange(1, 0, Acquire, Relaxed).is_err() { |
5869c6ff XL |
2124 | // Another strong pointer exists, so we must clone. |
2125 | // Pre-allocate memory to allow writing the cloned value directly. | |
add651ee | 2126 | let mut arc = Self::new_uninit_in(this.alloc.clone()); |
5869c6ff XL |
2127 | unsafe { |
2128 | let data = Arc::get_mut_unchecked(&mut arc); | |
2129 | (**this).write_clone_into_raw(data.as_mut_ptr()); | |
2130 | *this = arc.assume_init(); | |
2131 | } | |
c1a9b12d SL |
2132 | } else if this.inner().weak.load(Relaxed) != 1 { |
2133 | // Relaxed suffices in the above because this is fundamentally an | |
2134 | // optimization: we are always racing with weak pointers being | |
2135 | // dropped. Worst case, we end up allocated a new Arc unnecessarily. | |
2136 | ||
2137 | // We removed the last strong ref, but there are additional weak | |
2138 | // refs remaining. We'll move the contents to a new Arc, and | |
2139 | // invalidate the other weak refs. | |
2140 | ||
2141 | // Note that it is not possible for the read of `weak` to yield | |
2142 | // usize::MAX (i.e., locked), since the weak count can only be | |
2143 | // locked by a thread with a strong reference. | |
2144 | ||
2145 | // Materialize our own implicit weak pointer, so that it can clean | |
2146 | // up the ArcInner as needed. | |
add651ee | 2147 | let _weak = Weak { ptr: this.ptr, alloc: this.alloc.clone() }; |
c1a9b12d | 2148 | |
5869c6ff | 2149 | // Can just steal the data, all that's left is Weaks |
add651ee | 2150 | let mut arc = Self::new_uninit_in(this.alloc.clone()); |
c1a9b12d | 2151 | unsafe { |
5869c6ff XL |
2152 | let data = Arc::get_mut_unchecked(&mut arc); |
2153 | data.as_mut_ptr().copy_from_nonoverlapping(&**this, 1); | |
2154 | ptr::write(this, arc.assume_init()); | |
c1a9b12d SL |
2155 | } |
2156 | } else { | |
2157 | // We were the sole reference of either kind; bump back up the | |
2158 | // strong ref count. | |
2159 | this.inner().strong.store(1, Release); | |
1a4d82fc | 2160 | } |
c1a9b12d | 2161 | |
9346a6ac | 2162 | // As with `get_mut()`, the unsafety is ok because our reference was |
c34b1796 | 2163 | // either unique to begin with, or became one upon cloning the contents. |
f9f354fc | 2164 | unsafe { Self::get_mut_unchecked(this) } |
1a4d82fc | 2165 | } |
5099ac24 FG |
2166 | |
2167 | /// If we have the only reference to `T` then unwrap it. Otherwise, clone `T` and return the | |
2168 | /// clone. | |
2169 | /// | |
2170 | /// Assuming `arc_t` is of type `Arc<T>`, this function is functionally equivalent to | |
2171 | /// `(*arc_t).clone()`, but will avoid cloning the inner value where possible. | |
2172 | /// | |
2173 | /// # Examples | |
2174 | /// | |
2175 | /// ``` | |
2176 | /// #![feature(arc_unwrap_or_clone)] | |
2177 | /// # use std::{ptr, sync::Arc}; | |
2178 | /// let inner = String::from("test"); | |
2179 | /// let ptr = inner.as_ptr(); | |
2180 | /// | |
2181 | /// let arc = Arc::new(inner); | |
2182 | /// let inner = Arc::unwrap_or_clone(arc); | |
2183 | /// // The inner value was not cloned | |
2184 | /// assert!(ptr::eq(ptr, inner.as_ptr())); | |
2185 | /// | |
2186 | /// let arc = Arc::new(inner); | |
2187 | /// let arc2 = arc.clone(); | |
2188 | /// let inner = Arc::unwrap_or_clone(arc); | |
2189 | /// // Because there were 2 references, we had to clone the inner value. | |
2190 | /// assert!(!ptr::eq(ptr, inner.as_ptr())); | |
2191 | /// // `arc2` is the last reference, so when we unwrap it we get back | |
2192 | /// // the original `String`. | |
2193 | /// let inner = Arc::unwrap_or_clone(arc2); | |
2194 | /// assert!(ptr::eq(ptr, inner.as_ptr())); | |
2195 | /// ``` | |
2196 | #[inline] | |
2197 | #[unstable(feature = "arc_unwrap_or_clone", issue = "93610")] | |
2198 | pub fn unwrap_or_clone(this: Self) -> T { | |
2199 | Arc::try_unwrap(this).unwrap_or_else(|arc| (*arc).clone()) | |
2200 | } | |
1a4d82fc JJ |
2201 | } |
2202 | ||
add651ee | 2203 | impl<T: ?Sized, A: Allocator> Arc<T, A> { |
e74abb32 | 2204 | /// Returns a mutable reference into the given `Arc`, if there are |
3dfed10e | 2205 | /// no other `Arc` or [`Weak`] pointers to the same allocation. |
c30ab7b3 | 2206 | /// |
3dfed10e | 2207 | /// Returns [`None`] otherwise, because it is not safe to |
c30ab7b3 SL |
2208 | /// mutate a shared value. |
2209 | /// | |
2210 | /// See also [`make_mut`][make_mut], which will [`clone`][clone] | |
94222f64 | 2211 | /// the inner value when there are other `Arc` pointers. |
c30ab7b3 | 2212 | /// |
3dfed10e XL |
2213 | /// [make_mut]: Arc::make_mut |
2214 | /// [clone]: Clone::clone | |
c1a9b12d SL |
2215 | /// |
2216 | /// # Examples | |
2217 | /// | |
2218 | /// ``` | |
e9174d1e | 2219 | /// use std::sync::Arc; |
c1a9b12d SL |
2220 | /// |
2221 | /// let mut x = Arc::new(3); | |
2222 | /// *Arc::get_mut(&mut x).unwrap() = 4; | |
2223 | /// assert_eq!(*x, 4); | |
2224 | /// | |
7cac9316 | 2225 | /// let _y = Arc::clone(&x); |
c1a9b12d | 2226 | /// assert!(Arc::get_mut(&mut x).is_none()); |
c1a9b12d SL |
2227 | /// ``` |
2228 | #[inline] | |
e9174d1e SL |
2229 | #[stable(feature = "arc_unique", since = "1.4.0")] |
2230 | pub fn get_mut(this: &mut Self) -> Option<&mut T> { | |
c1a9b12d SL |
2231 | if this.is_unique() { |
2232 | // This unsafety is ok because we're guaranteed that the pointer | |
2233 | // returned is the *only* pointer that will ever be returned to T. Our | |
2234 | // reference count is guaranteed to be 1 at this point, and we required | |
2235 | // the Arc itself to be `mut`, so we're returning the only possible | |
2236 | // reference to the inner data. | |
dfeec247 | 2237 | unsafe { Some(Arc::get_mut_unchecked(this)) } |
c1a9b12d SL |
2238 | } else { |
2239 | None | |
2240 | } | |
2241 | } | |
2242 | ||
e74abb32 | 2243 | /// Returns a mutable reference into the given `Arc`, |
e1599b0c XL |
2244 | /// without any check. |
2245 | /// | |
2246 | /// See also [`get_mut`], which is safe and does appropriate checks. | |
2247 | /// | |
3dfed10e | 2248 | /// [`get_mut`]: Arc::get_mut |
e1599b0c XL |
2249 | /// |
2250 | /// # Safety | |
2251 | /// | |
487cf647 | 2252 | /// If any other `Arc` or [`Weak`] pointers to the same allocation exist, then |
9ffffee4 | 2253 | /// they must not be dereferenced or have active borrows for the duration |
487cf647 FG |
2254 | /// of the returned borrow, and their inner type must be exactly the same as the |
2255 | /// inner type of this Rc (including lifetimes). This is trivially the case if no | |
2256 | /// such pointers exist, for example immediately after `Arc::new`. | |
e1599b0c XL |
2257 | /// |
2258 | /// # Examples | |
2259 | /// | |
2260 | /// ``` | |
2261 | /// #![feature(get_mut_unchecked)] | |
2262 | /// | |
2263 | /// use std::sync::Arc; | |
2264 | /// | |
2265 | /// let mut x = Arc::new(String::new()); | |
2266 | /// unsafe { | |
2267 | /// Arc::get_mut_unchecked(&mut x).push_str("foo") | |
2268 | /// } | |
2269 | /// assert_eq!(*x, "foo"); | |
2270 | /// ``` | |
487cf647 FG |
2271 | /// Other `Arc` pointers to the same allocation must be to the same type. |
2272 | /// ```no_run | |
2273 | /// #![feature(get_mut_unchecked)] | |
2274 | /// | |
2275 | /// use std::sync::Arc; | |
2276 | /// | |
2277 | /// let x: Arc<str> = Arc::from("Hello, world!"); | |
2278 | /// let mut y: Arc<[u8]> = x.clone().into(); | |
2279 | /// unsafe { | |
2280 | /// // this is Undefined Behavior, because x's inner type is str, not [u8] | |
2281 | /// Arc::get_mut_unchecked(&mut y).fill(0xff); // 0xff is invalid in UTF-8 | |
2282 | /// } | |
2283 | /// println!("{}", &*x); // Invalid UTF-8 in a str | |
2284 | /// ``` | |
2285 | /// Other `Arc` pointers to the same allocation must be to the exact same type, including lifetimes. | |
2286 | /// ```no_run | |
2287 | /// #![feature(get_mut_unchecked)] | |
2288 | /// | |
2289 | /// use std::sync::Arc; | |
2290 | /// | |
2291 | /// let x: Arc<&str> = Arc::new("Hello, world!"); | |
2292 | /// { | |
2293 | /// let s = String::from("Oh, no!"); | |
2294 | /// let mut y: Arc<&str> = x.clone().into(); | |
2295 | /// unsafe { | |
2296 | /// // this is Undefined Behavior, because x's inner type | |
2297 | /// // is &'long str, not &'short str | |
2298 | /// *Arc::get_mut_unchecked(&mut y) = &s; | |
2299 | /// } | |
2300 | /// } | |
2301 | /// println!("{}", &*x); // Use-after-free | |
2302 | /// ``` | |
e1599b0c XL |
2303 | #[inline] |
2304 | #[unstable(feature = "get_mut_unchecked", issue = "63292")] | |
2305 | pub unsafe fn get_mut_unchecked(this: &mut Self) -> &mut T { | |
f9f354fc XL |
2306 | // We are careful to *not* create a reference covering the "count" fields, as |
2307 | // this would alias with concurrent access to the reference counts (e.g. by `Weak`). | |
f035d41b | 2308 | unsafe { &mut (*this.ptr.as_ptr()).data } |
e1599b0c XL |
2309 | } |
2310 | ||
c1a9b12d SL |
2311 | /// Determine whether this is the unique reference (including weak refs) to |
2312 | /// the underlying data. | |
2313 | /// | |
2314 | /// Note that this requires locking the weak ref count. | |
2315 | fn is_unique(&mut self) -> bool { | |
2316 | // lock the weak pointer count if we appear to be the sole weak pointer | |
2317 | // holder. | |
2318 | // | |
2319 | // The acquire label here ensures a happens-before relationship with any | |
8faf50e0 | 2320 | // writes to `strong` (in particular in `Weak::upgrade`) prior to decrements |
9c376795 | 2321 | // of the `weak` count (via `Weak::drop`, which uses release). If the upgraded |
8faf50e0 | 2322 | // weak ref was never dropped, the CAS here will fail so we do not care to synchronize. |
54a0048b | 2323 | if self.inner().weak.compare_exchange(1, usize::MAX, Acquire, Relaxed).is_ok() { |
8faf50e0 XL |
2324 | // This needs to be an `Acquire` to synchronize with the decrement of the `strong` |
2325 | // counter in `drop` -- the only access that happens when any but the last reference | |
2326 | // is being dropped. | |
2327 | let unique = self.inner().strong.load(Acquire) == 1; | |
c1a9b12d SL |
2328 | |
2329 | // The release write here synchronizes with a read in `downgrade`, | |
2330 | // effectively preventing the above read of `strong` from happening | |
2331 | // after the write. | |
2332 | self.inner().weak.store(1, Release); // release the lock | |
2333 | unique | |
2334 | } else { | |
2335 | false | |
2336 | } | |
2337 | } | |
2338 | } | |
2339 | ||
85aaf69f | 2340 | #[stable(feature = "rust1", since = "1.0.0")] |
add651ee | 2341 | unsafe impl<#[may_dangle] T: ?Sized, A: Allocator> Drop for Arc<T, A> { |
c30ab7b3 | 2342 | /// Drops the `Arc`. |
1a4d82fc | 2343 | /// |
c34b1796 | 2344 | /// This will decrement the strong reference count. If the strong reference |
c30ab7b3 | 2345 | /// count reaches zero then the only other references (if any) are |
b7449926 | 2346 | /// [`Weak`], so we `drop` the inner value. |
1a4d82fc JJ |
2347 | /// |
2348 | /// # Examples | |
2349 | /// | |
2350 | /// ``` | |
2351 | /// use std::sync::Arc; | |
2352 | /// | |
c30ab7b3 | 2353 | /// struct Foo; |
1a4d82fc | 2354 | /// |
c30ab7b3 SL |
2355 | /// impl Drop for Foo { |
2356 | /// fn drop(&mut self) { | |
2357 | /// println!("dropped!"); | |
2358 | /// } | |
1a4d82fc | 2359 | /// } |
1a4d82fc | 2360 | /// |
c30ab7b3 | 2361 | /// let foo = Arc::new(Foo); |
7cac9316 | 2362 | /// let foo2 = Arc::clone(&foo); |
1a4d82fc | 2363 | /// |
c30ab7b3 SL |
2364 | /// drop(foo); // Doesn't print anything |
2365 | /// drop(foo2); // Prints "dropped!" | |
1a4d82fc | 2366 | /// ``` |
c34b1796 | 2367 | #[inline] |
1a4d82fc | 2368 | fn drop(&mut self) { |
c34b1796 AL |
2369 | // Because `fetch_sub` is already atomic, we do not need to synchronize |
2370 | // with other threads unless we are going to delete the object. This | |
2371 | // same logic applies to the below `fetch_sub` to the `weak` count. | |
b039eaaf | 2372 | if self.inner().strong.fetch_sub(1, Release) != 1 { |
92a42be0 | 2373 | return; |
b039eaaf | 2374 | } |
1a4d82fc | 2375 | |
c34b1796 | 2376 | // This fence is needed to prevent reordering of use of the data and |
9c376795 | 2377 | // deletion of the data. Because it is marked `Release`, the decreasing |
c34b1796 AL |
2378 | // of the reference count synchronizes with this `Acquire` fence. This |
2379 | // means that use of the data happens before decreasing the reference | |
2380 | // count, which happens before this fence, which happens before the | |
2381 | // deletion of the data. | |
1a4d82fc JJ |
2382 | // |
2383 | // As explained in the [Boost documentation][1], | |
2384 | // | |
c34b1796 AL |
2385 | // > It is important to enforce any possible access to the object in one |
2386 | // > thread (through an existing reference) to *happen before* deleting | |
2387 | // > the object in a different thread. This is achieved by a "release" | |
2388 | // > operation after dropping a reference (any access to the object | |
2389 | // > through this reference must obviously happened before), and an | |
2390 | // > "acquire" operation before deleting the object. | |
1a4d82fc | 2391 | // |
7cac9316 XL |
2392 | // In particular, while the contents of an Arc are usually immutable, it's |
2393 | // possible to have interior writes to something like a Mutex<T>. Since a | |
2394 | // Mutex is not acquired when it is deleted, we can't rely on its | |
2395 | // synchronization logic to make writes in thread A visible to a destructor | |
2396 | // running in thread B. | |
2397 | // | |
2398 | // Also note that the Acquire fence here could probably be replaced with an | |
2399 | // Acquire load, which could improve performance in highly-contended | |
2400 | // situations. See [2]. | |
2401 | // | |
1a4d82fc | 2402 | // [1]: (www.boost.org/doc/libs/1_55_0/doc/html/atomic/usage_examples.html) |
7cac9316 | 2403 | // [2]: (https://github.com/rust-lang/rust/pull/41714) |
ba9703b0 | 2404 | acquire!(self.inner().strong); |
1a4d82fc | 2405 | |
c34b1796 | 2406 | unsafe { |
b039eaaf | 2407 | self.drop_slow(); |
1a4d82fc JJ |
2408 | } |
2409 | } | |
2410 | } | |
2411 | ||
add651ee | 2412 | impl<A: Allocator + Clone> Arc<dyn Any + Send + Sync, A> { |
8faf50e0 | 2413 | /// Attempt to downcast the `Arc<dyn Any + Send + Sync>` to a concrete type. |
94b46f34 XL |
2414 | /// |
2415 | /// # Examples | |
2416 | /// | |
2417 | /// ``` | |
94b46f34 XL |
2418 | /// use std::any::Any; |
2419 | /// use std::sync::Arc; | |
2420 | /// | |
8faf50e0 | 2421 | /// fn print_if_string(value: Arc<dyn Any + Send + Sync>) { |
94b46f34 XL |
2422 | /// if let Ok(string) = value.downcast::<String>() { |
2423 | /// println!("String ({}): {}", string.len(), string); | |
2424 | /// } | |
2425 | /// } | |
2426 | /// | |
e74abb32 XL |
2427 | /// let my_string = "Hello World".to_string(); |
2428 | /// print_if_string(Arc::new(my_string)); | |
2429 | /// print_if_string(Arc::new(0i8)); | |
94b46f34 | 2430 | /// ``` |
923072b8 FG |
2431 | #[inline] |
2432 | #[stable(feature = "rc_downcast", since = "1.29.0")] | |
add651ee | 2433 | pub fn downcast<T>(self) -> Result<Arc<T, A>, Self> |
94b46f34 | 2434 | where |
923072b8 | 2435 | T: Any + Send + Sync, |
94b46f34 XL |
2436 | { |
2437 | if (*self).is::<T>() { | |
3c0e092e XL |
2438 | unsafe { |
2439 | let ptr = self.ptr.cast::<ArcInner<T>>(); | |
add651ee | 2440 | let alloc = self.alloc.clone(); |
3c0e092e | 2441 | mem::forget(self); |
add651ee | 2442 | Ok(Arc::from_inner_in(ptr, alloc)) |
3c0e092e | 2443 | } |
94b46f34 XL |
2444 | } else { |
2445 | Err(self) | |
2446 | } | |
2447 | } | |
923072b8 FG |
2448 | |
2449 | /// Downcasts the `Arc<dyn Any + Send + Sync>` to a concrete type. | |
2450 | /// | |
2451 | /// For a safe alternative see [`downcast`]. | |
2452 | /// | |
2453 | /// # Examples | |
2454 | /// | |
2455 | /// ``` | |
2456 | /// #![feature(downcast_unchecked)] | |
2457 | /// | |
2458 | /// use std::any::Any; | |
2459 | /// use std::sync::Arc; | |
2460 | /// | |
2461 | /// let x: Arc<dyn Any + Send + Sync> = Arc::new(1_usize); | |
2462 | /// | |
2463 | /// unsafe { | |
2464 | /// assert_eq!(*x.downcast_unchecked::<usize>(), 1); | |
2465 | /// } | |
2466 | /// ``` | |
2467 | /// | |
2468 | /// # Safety | |
2469 | /// | |
2470 | /// The contained value must be of type `T`. Calling this method | |
2471 | /// with the incorrect type is *undefined behavior*. | |
2472 | /// | |
2473 | /// | |
2474 | /// [`downcast`]: Self::downcast | |
2475 | #[inline] | |
2476 | #[unstable(feature = "downcast_unchecked", issue = "90850")] | |
add651ee | 2477 | pub unsafe fn downcast_unchecked<T>(self) -> Arc<T, A> |
923072b8 FG |
2478 | where |
2479 | T: Any + Send + Sync, | |
2480 | { | |
2481 | unsafe { | |
2482 | let ptr = self.ptr.cast::<ArcInner<T>>(); | |
add651ee | 2483 | let alloc = self.alloc.clone(); |
923072b8 | 2484 | mem::forget(self); |
add651ee | 2485 | Arc::from_inner_in(ptr, alloc) |
923072b8 FG |
2486 | } |
2487 | } | |
94b46f34 XL |
2488 | } |
2489 | ||
a7813a04 | 2490 | impl<T> Weak<T> { |
8faf50e0 XL |
2491 | /// Constructs a new `Weak<T>`, without allocating any memory. |
2492 | /// Calling [`upgrade`] on the return value always gives [`None`]. | |
c30ab7b3 | 2493 | /// |
3dfed10e | 2494 | /// [`upgrade`]: Weak::upgrade |
a7813a04 XL |
2495 | /// |
2496 | /// # Examples | |
2497 | /// | |
2498 | /// ``` | |
2499 | /// use std::sync::Weak; | |
2500 | /// | |
2501 | /// let empty: Weak<i64> = Weak::new(); | |
c30ab7b3 | 2502 | /// assert!(empty.upgrade().is_none()); |
a7813a04 | 2503 | /// ``` |
add651ee | 2504 | #[inline] |
a7813a04 | 2505 | #[stable(feature = "downgraded_weak", since = "1.10.0")] |
add651ee | 2506 | #[rustc_const_stable(feature = "const_weak_new", since = "1.73.0")] |
c295e0f8 | 2507 | #[must_use] |
5e7ed085 | 2508 | pub const fn new() -> Weak<T> { |
add651ee FG |
2509 | Weak { |
2510 | ptr: unsafe { NonNull::new_unchecked(ptr::invalid_mut::<ArcInner<T>>(usize::MAX)) }, | |
2511 | alloc: Global, | |
2512 | } | |
2513 | } | |
2514 | } | |
2515 | ||
2516 | impl<T, A: Allocator> Weak<T, A> { | |
2517 | /// Constructs a new `Weak<T, A>`, without allocating any memory, technically in the provided | |
2518 | /// allocator. | |
2519 | /// Calling [`upgrade`] on the return value always gives [`None`]. | |
2520 | /// | |
2521 | /// [`upgrade`]: Weak::upgrade | |
2522 | /// | |
2523 | /// # Examples | |
2524 | /// | |
2525 | /// ``` | |
2526 | /// #![feature(allocator_api)] | |
2527 | /// | |
2528 | /// use std::sync::Weak; | |
2529 | /// use std::alloc::System; | |
2530 | /// | |
2531 | /// let empty: Weak<i64, _> = Weak::new_in(System); | |
2532 | /// assert!(empty.upgrade().is_none()); | |
2533 | /// ``` | |
2534 | #[inline] | |
2535 | #[unstable(feature = "allocator_api", issue = "32838")] | |
2536 | pub fn new_in(alloc: A) -> Weak<T, A> { | |
2537 | Weak { | |
2538 | ptr: unsafe { NonNull::new_unchecked(ptr::invalid_mut::<ArcInner<T>>(usize::MAX)) }, | |
2539 | alloc, | |
2540 | } | |
a7813a04 | 2541 | } |
29967ef6 XL |
2542 | } |
2543 | ||
2544 | /// Helper type to allow accessing the reference counts without | |
2545 | /// making any assertions about the data field. | |
2546 | struct WeakInner<'a> { | |
2547 | weak: &'a atomic::AtomicUsize, | |
2548 | strong: &'a atomic::AtomicUsize, | |
2549 | } | |
dc9dc135 | 2550 | |
5869c6ff | 2551 | impl<T: ?Sized> Weak<T> { |
add651ee FG |
2552 | /// Converts a raw pointer previously created by [`into_raw`] back into `Weak<T>`. |
2553 | /// | |
2554 | /// This can be used to safely get a strong reference (by calling [`upgrade`] | |
2555 | /// later) or to deallocate the weak count by dropping the `Weak<T>`. | |
2556 | /// | |
2557 | /// It takes ownership of one weak reference (with the exception of pointers created by [`new`], | |
2558 | /// as these don't own anything; the method still works on them). | |
2559 | /// | |
2560 | /// # Safety | |
2561 | /// | |
2562 | /// The pointer must have originated from the [`into_raw`] and must still own its potential | |
2563 | /// weak reference. | |
2564 | /// | |
2565 | /// It is allowed for the strong count to be 0 at the time of calling this. Nevertheless, this | |
2566 | /// takes ownership of one weak reference currently represented as a raw pointer (the weak | |
2567 | /// count is not modified by this operation) and therefore it must be paired with a previous | |
2568 | /// call to [`into_raw`]. | |
2569 | /// # Examples | |
2570 | /// | |
2571 | /// ``` | |
2572 | /// use std::sync::{Arc, Weak}; | |
2573 | /// | |
2574 | /// let strong = Arc::new("hello".to_owned()); | |
2575 | /// | |
2576 | /// let raw_1 = Arc::downgrade(&strong).into_raw(); | |
2577 | /// let raw_2 = Arc::downgrade(&strong).into_raw(); | |
2578 | /// | |
2579 | /// assert_eq!(2, Arc::weak_count(&strong)); | |
2580 | /// | |
2581 | /// assert_eq!("hello", &*unsafe { Weak::from_raw(raw_1) }.upgrade().unwrap()); | |
2582 | /// assert_eq!(1, Arc::weak_count(&strong)); | |
2583 | /// | |
2584 | /// drop(strong); | |
2585 | /// | |
2586 | /// // Decrement the last weak count. | |
2587 | /// assert!(unsafe { Weak::from_raw(raw_2) }.upgrade().is_none()); | |
2588 | /// ``` | |
2589 | /// | |
2590 | /// [`new`]: Weak::new | |
2591 | /// [`into_raw`]: Weak::into_raw | |
2592 | /// [`upgrade`]: Weak::upgrade | |
2593 | #[inline] | |
2594 | #[stable(feature = "weak_into_raw", since = "1.45.0")] | |
2595 | pub unsafe fn from_raw(ptr: *const T) -> Self { | |
2596 | unsafe { Weak::from_raw_in(ptr, Global) } | |
2597 | } | |
2598 | } | |
2599 | ||
2600 | impl<T: ?Sized, A: Allocator> Weak<T, A> { | |
dc9dc135 XL |
2601 | /// Returns a raw pointer to the object `T` pointed to by this `Weak<T>`. |
2602 | /// | |
ba9703b0 XL |
2603 | /// The pointer is valid only if there are some strong references. The pointer may be dangling, |
2604 | /// unaligned or even [`null`] otherwise. | |
dc9dc135 XL |
2605 | /// |
2606 | /// # Examples | |
2607 | /// | |
2608 | /// ``` | |
416331ca | 2609 | /// use std::sync::Arc; |
dc9dc135 XL |
2610 | /// use std::ptr; |
2611 | /// | |
2612 | /// let strong = Arc::new("hello".to_owned()); | |
2613 | /// let weak = Arc::downgrade(&strong); | |
2614 | /// // Both point to the same object | |
ba9703b0 | 2615 | /// assert!(ptr::eq(&*strong, weak.as_ptr())); |
dc9dc135 | 2616 | /// // The strong here keeps it alive, so we can still access the object. |
ba9703b0 | 2617 | /// assert_eq!("hello", unsafe { &*weak.as_ptr() }); |
dc9dc135 XL |
2618 | /// |
2619 | /// drop(strong); | |
ba9703b0 | 2620 | /// // But not any more. We can do weak.as_ptr(), but accessing the pointer would lead to |
dc9dc135 | 2621 | /// // undefined behaviour. |
ba9703b0 | 2622 | /// // assert_eq!("hello", unsafe { &*weak.as_ptr() }); |
dc9dc135 XL |
2623 | /// ``` |
2624 | /// | |
c295e0f8 XL |
2625 | /// [`null`]: core::ptr::null "ptr::null" |
2626 | #[must_use] | |
f9f354fc | 2627 | #[stable(feature = "weak_into_raw", since = "1.45.0")] |
ba9703b0 | 2628 | pub fn as_ptr(&self) -> *const T { |
f035d41b XL |
2629 | let ptr: *mut ArcInner<T> = NonNull::as_ptr(self.ptr); |
2630 | ||
5869c6ff XL |
2631 | if is_dangling(ptr) { |
2632 | // If the pointer is dangling, we return the sentinel directly. This cannot be | |
2633 | // a valid payload address, as the payload is at least as aligned as ArcInner (usize). | |
2634 | ptr as *const T | |
2635 | } else { | |
a2a8927a | 2636 | // SAFETY: if is_dangling returns false, then the pointer is dereferenceable. |
5869c6ff XL |
2637 | // The payload may be dropped at this point, and we have to maintain provenance, |
2638 | // so use raw pointer manipulation. | |
2639 | unsafe { ptr::addr_of_mut!((*ptr).data) } | |
f035d41b | 2640 | } |
dc9dc135 XL |
2641 | } |
2642 | ||
2643 | /// Consumes the `Weak<T>` and turns it into a raw pointer. | |
2644 | /// | |
3dfed10e XL |
2645 | /// This converts the weak pointer into a raw pointer, while still preserving the ownership of |
2646 | /// one weak reference (the weak count is not modified by this operation). It can be turned | |
2647 | /// back into the `Weak<T>` with [`from_raw`]. | |
dc9dc135 XL |
2648 | /// |
2649 | /// The same restrictions of accessing the target of the pointer as with | |
ba9703b0 | 2650 | /// [`as_ptr`] apply. |
dc9dc135 XL |
2651 | /// |
2652 | /// # Examples | |
2653 | /// | |
2654 | /// ``` | |
dc9dc135 XL |
2655 | /// use std::sync::{Arc, Weak}; |
2656 | /// | |
2657 | /// let strong = Arc::new("hello".to_owned()); | |
2658 | /// let weak = Arc::downgrade(&strong); | |
416331ca | 2659 | /// let raw = weak.into_raw(); |
dc9dc135 XL |
2660 | /// |
2661 | /// assert_eq!(1, Arc::weak_count(&strong)); | |
2662 | /// assert_eq!("hello", unsafe { &*raw }); | |
2663 | /// | |
2664 | /// drop(unsafe { Weak::from_raw(raw) }); | |
2665 | /// assert_eq!(0, Arc::weak_count(&strong)); | |
2666 | /// ``` | |
2667 | /// | |
3dfed10e XL |
2668 | /// [`from_raw`]: Weak::from_raw |
2669 | /// [`as_ptr`]: Weak::as_ptr | |
c295e0f8 | 2670 | #[must_use = "`self` will be dropped if the result is not used"] |
f9f354fc | 2671 | #[stable(feature = "weak_into_raw", since = "1.45.0")] |
416331ca | 2672 | pub fn into_raw(self) -> *const T { |
ba9703b0 | 2673 | let result = self.as_ptr(); |
416331ca | 2674 | mem::forget(self); |
dc9dc135 XL |
2675 | result |
2676 | } | |
2677 | ||
add651ee FG |
2678 | /// Converts a raw pointer previously created by [`into_raw`] back into `Weak<T>` in the provided |
2679 | /// allocator. | |
dc9dc135 XL |
2680 | /// |
2681 | /// This can be used to safely get a strong reference (by calling [`upgrade`] | |
2682 | /// later) or to deallocate the weak count by dropping the `Weak<T>`. | |
2683 | /// | |
3dfed10e XL |
2684 | /// It takes ownership of one weak reference (with the exception of pointers created by [`new`], |
2685 | /// as these don't own anything; the method still works on them). | |
dc9dc135 XL |
2686 | /// |
2687 | /// # Safety | |
2688 | /// | |
ba9703b0 | 2689 | /// The pointer must have originated from the [`into_raw`] and must still own its potential |
add651ee | 2690 | /// weak reference, and must point to a block of memory allocated by `alloc`. |
dc9dc135 | 2691 | /// |
3dfed10e XL |
2692 | /// It is allowed for the strong count to be 0 at the time of calling this. Nevertheless, this |
2693 | /// takes ownership of one weak reference currently represented as a raw pointer (the weak | |
2694 | /// count is not modified by this operation) and therefore it must be paired with a previous | |
2695 | /// call to [`into_raw`]. | |
dc9dc135 XL |
2696 | /// # Examples |
2697 | /// | |
2698 | /// ``` | |
dc9dc135 XL |
2699 | /// use std::sync::{Arc, Weak}; |
2700 | /// | |
2701 | /// let strong = Arc::new("hello".to_owned()); | |
2702 | /// | |
416331ca XL |
2703 | /// let raw_1 = Arc::downgrade(&strong).into_raw(); |
2704 | /// let raw_2 = Arc::downgrade(&strong).into_raw(); | |
dc9dc135 XL |
2705 | /// |
2706 | /// assert_eq!(2, Arc::weak_count(&strong)); | |
2707 | /// | |
416331ca | 2708 | /// assert_eq!("hello", &*unsafe { Weak::from_raw(raw_1) }.upgrade().unwrap()); |
dc9dc135 XL |
2709 | /// assert_eq!(1, Arc::weak_count(&strong)); |
2710 | /// | |
2711 | /// drop(strong); | |
2712 | /// | |
2713 | /// // Decrement the last weak count. | |
416331ca | 2714 | /// assert!(unsafe { Weak::from_raw(raw_2) }.upgrade().is_none()); |
dc9dc135 XL |
2715 | /// ``` |
2716 | /// | |
3dfed10e XL |
2717 | /// [`new`]: Weak::new |
2718 | /// [`into_raw`]: Weak::into_raw | |
2719 | /// [`upgrade`]: Weak::upgrade | |
add651ee FG |
2720 | #[inline] |
2721 | #[unstable(feature = "allocator_api", issue = "32838")] | |
2722 | pub unsafe fn from_raw_in(ptr: *const T, alloc: A) -> Self { | |
29967ef6 | 2723 | // See Weak::as_ptr for context on how the input pointer is derived. |
29967ef6 | 2724 | |
5869c6ff XL |
2725 | let ptr = if is_dangling(ptr as *mut T) { |
2726 | // This is a dangling Weak. | |
2727 | ptr as *mut ArcInner<T> | |
2728 | } else { | |
2729 | // Otherwise, we're guaranteed the pointer came from a nondangling Weak. | |
2730 | // SAFETY: data_offset is safe to call, as ptr references a real (potentially dropped) T. | |
2731 | let offset = unsafe { data_offset(ptr) }; | |
2732 | // Thus, we reverse the offset to get the whole RcBox. | |
2733 | // SAFETY: the pointer originated from a Weak, so this offset is safe. | |
064997fb | 2734 | unsafe { ptr.byte_sub(offset) as *mut ArcInner<T> } |
29967ef6 | 2735 | }; |
a7813a04 | 2736 | |
29967ef6 | 2737 | // SAFETY: we now have recovered the original Weak pointer, so can create the Weak. |
add651ee | 2738 | Weak { ptr: unsafe { NonNull::new_unchecked(ptr) }, alloc } |
29967ef6 | 2739 | } |
b9856134 | 2740 | } |
f9f354fc | 2741 | |
add651ee | 2742 | impl<T: ?Sized, A: Allocator> Weak<T, A> { |
e74abb32 XL |
2743 | /// Attempts to upgrade the `Weak` pointer to an [`Arc`], delaying |
2744 | /// dropping of the inner value if successful. | |
1a4d82fc | 2745 | /// |
e74abb32 | 2746 | /// Returns [`None`] if the inner value has since been dropped. |
1a4d82fc | 2747 | /// |
1a4d82fc JJ |
2748 | /// # Examples |
2749 | /// | |
2750 | /// ``` | |
2751 | /// use std::sync::Arc; | |
2752 | /// | |
85aaf69f | 2753 | /// let five = Arc::new(5); |
1a4d82fc | 2754 | /// |
e9174d1e | 2755 | /// let weak_five = Arc::downgrade(&five); |
1a4d82fc JJ |
2756 | /// |
2757 | /// let strong_five: Option<Arc<_>> = weak_five.upgrade(); | |
c30ab7b3 SL |
2758 | /// assert!(strong_five.is_some()); |
2759 | /// | |
2760 | /// // Destroy all strong pointers. | |
2761 | /// drop(strong_five); | |
2762 | /// drop(five); | |
2763 | /// | |
2764 | /// assert!(weak_five.upgrade().is_none()); | |
1a4d82fc | 2765 | /// ``` |
c295e0f8 XL |
2766 | #[must_use = "this returns a new `Arc`, \ |
2767 | without modifying the original weak pointer"] | |
e9174d1e | 2768 | #[stable(feature = "arc_weak", since = "1.4.0")] |
add651ee FG |
2769 | pub fn upgrade(&self) -> Option<Arc<T, A>> |
2770 | where | |
2771 | A: Clone, | |
2772 | { | |
2773 | #[inline] | |
2774 | fn checked_increment(n: usize) -> Option<usize> { | |
2775 | // Any write of 0 we can observe leaves the field in permanently zero state. | |
2776 | if n == 0 { | |
2777 | return None; | |
2778 | } | |
2779 | // See comments in `Arc::clone` for why we do this (for `mem::forget`). | |
2780 | assert!(n <= MAX_REFCOUNT, "{}", INTERNAL_OVERFLOW_ERROR); | |
2781 | Some(n + 1) | |
2782 | } | |
2783 | ||
c34b1796 | 2784 | // We use a CAS loop to increment the strong count instead of a |
3dfed10e XL |
2785 | // fetch_add as this function should never take the reference count |
2786 | // from zero to one. | |
add651ee FG |
2787 | // |
2788 | // Relaxed is fine for the failure case because we don't have any expectations about the new state. | |
2789 | // Acquire is necessary for the success case to synchronise with `Arc::new_cyclic`, when the inner | |
2790 | // value can be initialized after `Weak` references have already been created. In that case, we | |
2791 | // expect to observe the fully initialized value. | |
2792 | if self.inner()?.strong.fetch_update(Acquire, Relaxed, checked_increment).is_ok() { | |
2793 | // SAFETY: pointer is not null, verified in checked_increment | |
2794 | unsafe { Some(Arc::from_inner_in(self.ptr, self.alloc.clone())) } | |
2795 | } else { | |
2796 | None | |
2797 | } | |
1a4d82fc JJ |
2798 | } |
2799 | ||
e74abb32 | 2800 | /// Gets the number of strong (`Arc`) pointers pointing to this allocation. |
9fa01778 XL |
2801 | /// |
2802 | /// If `self` was created using [`Weak::new`], this will return 0. | |
3c0e092e | 2803 | #[must_use] |
60c5eb7d | 2804 | #[stable(feature = "weak_counts", since = "1.41.0")] |
9fa01778 | 2805 | pub fn strong_count(&self) -> usize { |
781aab86 | 2806 | if let Some(inner) = self.inner() { inner.strong.load(Relaxed) } else { 0 } |
9fa01778 XL |
2807 | } |
2808 | ||
2809 | /// Gets an approximation of the number of `Weak` pointers pointing to this | |
e74abb32 | 2810 | /// allocation. |
9fa01778 | 2811 | /// |
60c5eb7d XL |
2812 | /// If `self` was created using [`Weak::new`], or if there are no remaining |
2813 | /// strong pointers, this will return 0. | |
9fa01778 XL |
2814 | /// |
2815 | /// # Accuracy | |
2816 | /// | |
2817 | /// Due to implementation details, the returned value can be off by 1 in | |
2818 | /// either direction when other threads are manipulating any `Arc`s or | |
e74abb32 | 2819 | /// `Weak`s pointing to the same allocation. |
3c0e092e | 2820 | #[must_use] |
60c5eb7d XL |
2821 | #[stable(feature = "weak_counts", since = "1.41.0")] |
2822 | pub fn weak_count(&self) -> usize { | |
add651ee FG |
2823 | if let Some(inner) = self.inner() { |
2824 | let weak = inner.weak.load(Acquire); | |
781aab86 | 2825 | let strong = inner.strong.load(Relaxed); |
add651ee FG |
2826 | if strong == 0 { |
2827 | 0 | |
2828 | } else { | |
2829 | // Since we observed that there was at least one strong pointer | |
2830 | // after reading the weak count, we know that the implicit weak | |
2831 | // reference (present whenever any strong references are alive) | |
2832 | // was still around when we observed the weak count, and can | |
2833 | // therefore safely subtract it. | |
2834 | weak - 1 | |
2835 | } | |
2836 | } else { | |
2837 | 0 | |
2838 | } | |
9fa01778 XL |
2839 | } |
2840 | ||
2841 | /// Returns `None` when the pointer is dangling and there is no allocated `ArcInner`, | |
2842 | /// (i.e., when this `Weak` was created by `Weak::new`). | |
1a4d82fc | 2843 | #[inline] |
f9f354fc | 2844 | fn inner(&self) -> Option<WeakInner<'_>> { |
5869c6ff | 2845 | if is_dangling(self.ptr.as_ptr()) { |
f9f354fc XL |
2846 | None |
2847 | } else { | |
2848 | // We are careful to *not* create a reference covering the "data" field, as | |
2849 | // the field may be mutated concurrently (for example, if the last `Arc` | |
2850 | // is dropped, the data field will be dropped in-place). | |
2851 | Some(unsafe { | |
2852 | let ptr = self.ptr.as_ptr(); | |
2853 | WeakInner { strong: &(*ptr).strong, weak: &(*ptr).weak } | |
2854 | }) | |
2855 | } | |
1a4d82fc | 2856 | } |
0731742a | 2857 | |
2b03887a | 2858 | /// Returns `true` if the two `Weak`s point to the same allocation similar to [`ptr::eq`], or if |
fe692bf9 FG |
2859 | /// both don't point to any allocation (because they were created with `Weak::new()`). However, |
2860 | /// this function ignores the metadata of `dyn Trait` pointers. | |
0731742a XL |
2861 | /// |
2862 | /// # Notes | |
2863 | /// | |
2864 | /// Since this compares pointers it means that `Weak::new()` will equal each | |
e74abb32 | 2865 | /// other, even though they don't point to any allocation. |
0731742a | 2866 | /// |
0731742a XL |
2867 | /// # Examples |
2868 | /// | |
2869 | /// ``` | |
dc9dc135 | 2870 | /// use std::sync::Arc; |
0731742a XL |
2871 | /// |
2872 | /// let first_rc = Arc::new(5); | |
2873 | /// let first = Arc::downgrade(&first_rc); | |
2874 | /// let second = Arc::downgrade(&first_rc); | |
2875 | /// | |
dc9dc135 | 2876 | /// assert!(first.ptr_eq(&second)); |
0731742a XL |
2877 | /// |
2878 | /// let third_rc = Arc::new(5); | |
2879 | /// let third = Arc::downgrade(&third_rc); | |
2880 | /// | |
dc9dc135 | 2881 | /// assert!(!first.ptr_eq(&third)); |
0731742a XL |
2882 | /// ``` |
2883 | /// | |
2884 | /// Comparing `Weak::new`. | |
2885 | /// | |
2886 | /// ``` | |
0731742a XL |
2887 | /// use std::sync::{Arc, Weak}; |
2888 | /// | |
2889 | /// let first = Weak::new(); | |
2890 | /// let second = Weak::new(); | |
dc9dc135 | 2891 | /// assert!(first.ptr_eq(&second)); |
0731742a XL |
2892 | /// |
2893 | /// let third_rc = Arc::new(()); | |
2894 | /// let third = Arc::downgrade(&third_rc); | |
dc9dc135 | 2895 | /// assert!(!first.ptr_eq(&third)); |
0731742a | 2896 | /// ``` |
e74abb32 | 2897 | /// |
c295e0f8 | 2898 | /// [`ptr::eq`]: core::ptr::eq "ptr::eq" |
0731742a | 2899 | #[inline] |
3c0e092e | 2900 | #[must_use] |
e1599b0c | 2901 | #[stable(feature = "weak_ptr_eq", since = "1.39.0")] |
dc9dc135 | 2902 | pub fn ptr_eq(&self, other: &Self) -> bool { |
fe692bf9 | 2903 | ptr::eq(self.ptr.as_ptr() as *const (), other.ptr.as_ptr() as *const ()) |
0731742a | 2904 | } |
1a4d82fc JJ |
2905 | } |
2906 | ||
e9174d1e | 2907 | #[stable(feature = "arc_weak", since = "1.4.0")] |
add651ee | 2908 | impl<T: ?Sized, A: Allocator + Clone> Clone for Weak<T, A> { |
e74abb32 | 2909 | /// Makes a clone of the `Weak` pointer that points to the same allocation. |
1a4d82fc JJ |
2910 | /// |
2911 | /// # Examples | |
2912 | /// | |
2913 | /// ``` | |
7cac9316 | 2914 | /// use std::sync::{Arc, Weak}; |
1a4d82fc | 2915 | /// |
e9174d1e | 2916 | /// let weak_five = Arc::downgrade(&Arc::new(5)); |
1a4d82fc | 2917 | /// |
0bf4aa26 | 2918 | /// let _ = Weak::clone(&weak_five); |
1a4d82fc JJ |
2919 | /// ``` |
2920 | #[inline] | |
add651ee | 2921 | fn clone(&self) -> Weak<T, A> { |
8faf50e0 XL |
2922 | let inner = if let Some(inner) = self.inner() { |
2923 | inner | |
2924 | } else { | |
add651ee | 2925 | return Weak { ptr: self.ptr, alloc: self.alloc.clone() }; |
8faf50e0 | 2926 | }; |
9c376795 | 2927 | // See comments in Arc::clone() for why this is relaxed. This can use a |
c1a9b12d SL |
2928 | // fetch_add (ignoring the lock) because the weak count is only locked |
2929 | // where are *no other* weak pointers in existence. (So we can't be | |
2930 | // running this code in that case). | |
8faf50e0 | 2931 | let old_size = inner.weak.fetch_add(1, Relaxed); |
c1a9b12d SL |
2932 | |
2933 | // See comments in Arc::clone() for why we do this (for mem::forget). | |
2934 | if old_size > MAX_REFCOUNT { | |
f035d41b | 2935 | abort(); |
c1a9b12d SL |
2936 | } |
2937 | ||
add651ee | 2938 | Weak { ptr: self.ptr, alloc: self.alloc.clone() } |
1a4d82fc JJ |
2939 | } |
2940 | } | |
2941 | ||
a7813a04 XL |
2942 | #[stable(feature = "downgraded_weak", since = "1.10.0")] |
2943 | impl<T> Default for Weak<T> { | |
8faf50e0 | 2944 | /// Constructs a new `Weak<T>`, without allocating memory. |
0731742a | 2945 | /// Calling [`upgrade`] on the return value always |
b7449926 | 2946 | /// gives [`None`]. |
c30ab7b3 | 2947 | /// |
3dfed10e | 2948 | /// [`upgrade`]: Weak::upgrade |
c30ab7b3 SL |
2949 | /// |
2950 | /// # Examples | |
2951 | /// | |
2952 | /// ``` | |
2953 | /// use std::sync::Weak; | |
2954 | /// | |
2955 | /// let empty: Weak<i64> = Default::default(); | |
2956 | /// assert!(empty.upgrade().is_none()); | |
2957 | /// ``` | |
a7813a04 XL |
2958 | fn default() -> Weak<T> { |
2959 | Weak::new() | |
2960 | } | |
2961 | } | |
2962 | ||
7453a54e | 2963 | #[stable(feature = "arc_weak", since = "1.4.0")] |
add651ee | 2964 | unsafe impl<#[may_dangle] T: ?Sized, A: Allocator> Drop for Weak<T, A> { |
c30ab7b3 | 2965 | /// Drops the `Weak` pointer. |
1a4d82fc | 2966 | /// |
1a4d82fc JJ |
2967 | /// # Examples |
2968 | /// | |
2969 | /// ``` | |
7cac9316 | 2970 | /// use std::sync::{Arc, Weak}; |
1a4d82fc | 2971 | /// |
c30ab7b3 | 2972 | /// struct Foo; |
1a4d82fc | 2973 | /// |
c30ab7b3 SL |
2974 | /// impl Drop for Foo { |
2975 | /// fn drop(&mut self) { | |
2976 | /// println!("dropped!"); | |
2977 | /// } | |
1a4d82fc | 2978 | /// } |
1a4d82fc | 2979 | /// |
c30ab7b3 SL |
2980 | /// let foo = Arc::new(Foo); |
2981 | /// let weak_foo = Arc::downgrade(&foo); | |
7cac9316 | 2982 | /// let other_weak_foo = Weak::clone(&weak_foo); |
1a4d82fc | 2983 | /// |
c30ab7b3 SL |
2984 | /// drop(weak_foo); // Doesn't print anything |
2985 | /// drop(foo); // Prints "dropped!" | |
2986 | /// | |
2987 | /// assert!(other_weak_foo.upgrade().is_none()); | |
1a4d82fc JJ |
2988 | /// ``` |
2989 | fn drop(&mut self) { | |
c34b1796 AL |
2990 | // If we find out that we were the last weak pointer, then its time to |
2991 | // deallocate the data entirely. See the discussion in Arc::drop() about | |
2992 | // the memory orderings | |
c1a9b12d SL |
2993 | // |
2994 | // It's not necessary to check for the locked state here, because the | |
2995 | // weak count can only be locked if there was precisely one weak ref, | |
2996 | // meaning that drop could only subsequently run ON that remaining weak | |
2997 | // ref, which can only happen after the lock is released. | |
dfeec247 | 2998 | let inner = if let Some(inner) = self.inner() { inner } else { return }; |
8faf50e0 XL |
2999 | |
3000 | if inner.weak.fetch_sub(1, Release) == 1 { | |
ba9703b0 | 3001 | acquire!(inner.weak); |
add651ee FG |
3002 | unsafe { |
3003 | self.alloc.deallocate(self.ptr.cast(), Layout::for_value_raw(self.ptr.as_ptr())) | |
3004 | } | |
1a4d82fc JJ |
3005 | } |
3006 | } | |
3007 | } | |
3008 | ||
0731742a | 3009 | #[stable(feature = "rust1", since = "1.0.0")] |
add651ee FG |
3010 | trait ArcEqIdent<T: ?Sized + PartialEq, A: Allocator> { |
3011 | fn eq(&self, other: &Arc<T, A>) -> bool; | |
3012 | fn ne(&self, other: &Arc<T, A>) -> bool; | |
0731742a XL |
3013 | } |
3014 | ||
3015 | #[stable(feature = "rust1", since = "1.0.0")] | |
add651ee | 3016 | impl<T: ?Sized + PartialEq, A: Allocator> ArcEqIdent<T, A> for Arc<T, A> { |
0731742a | 3017 | #[inline] |
add651ee | 3018 | default fn eq(&self, other: &Arc<T, A>) -> bool { |
0731742a XL |
3019 | **self == **other |
3020 | } | |
3021 | #[inline] | |
add651ee | 3022 | default fn ne(&self, other: &Arc<T, A>) -> bool { |
0731742a XL |
3023 | **self != **other |
3024 | } | |
3025 | } | |
3026 | ||
48663c56 XL |
3027 | /// We're doing this specialization here, and not as a more general optimization on `&T`, because it |
3028 | /// would otherwise add a cost to all equality checks on refs. We assume that `Arc`s are used to | |
3029 | /// store large values, that are slow to clone, but also heavy to check for equality, causing this | |
3030 | /// cost to pay off more easily. It's also more likely to have two `Arc` clones, that point to | |
3031 | /// the same value, than two `&T`s. | |
e74abb32 XL |
3032 | /// |
3033 | /// We can only do this when `T: Eq` as a `PartialEq` might be deliberately irreflexive. | |
0731742a | 3034 | #[stable(feature = "rust1", since = "1.0.0")] |
add651ee | 3035 | impl<T: ?Sized + crate::rc::MarkerEq, A: Allocator> ArcEqIdent<T, A> for Arc<T, A> { |
0731742a | 3036 | #[inline] |
add651ee | 3037 | fn eq(&self, other: &Arc<T, A>) -> bool { |
0731742a XL |
3038 | Arc::ptr_eq(self, other) || **self == **other |
3039 | } | |
3040 | ||
3041 | #[inline] | |
add651ee | 3042 | fn ne(&self, other: &Arc<T, A>) -> bool { |
0731742a XL |
3043 | !Arc::ptr_eq(self, other) && **self != **other |
3044 | } | |
3045 | } | |
3046 | ||
85aaf69f | 3047 | #[stable(feature = "rust1", since = "1.0.0")] |
add651ee | 3048 | impl<T: ?Sized + PartialEq, A: Allocator> PartialEq for Arc<T, A> { |
c30ab7b3 | 3049 | /// Equality for two `Arc`s. |
1a4d82fc | 3050 | /// |
e74abb32 XL |
3051 | /// Two `Arc`s are equal if their inner values are equal, even if they are |
3052 | /// stored in different allocation. | |
1a4d82fc | 3053 | /// |
e74abb32 XL |
3054 | /// If `T` also implements `Eq` (implying reflexivity of equality), |
3055 | /// two `Arc`s that point to the same allocation are always equal. | |
0731742a | 3056 | /// |
1a4d82fc JJ |
3057 | /// # Examples |
3058 | /// | |
3059 | /// ``` | |
3060 | /// use std::sync::Arc; | |
3061 | /// | |
85aaf69f | 3062 | /// let five = Arc::new(5); |
1a4d82fc | 3063 | /// |
c30ab7b3 | 3064 | /// assert!(five == Arc::new(5)); |
1a4d82fc | 3065 | /// ``` |
0731742a | 3066 | #[inline] |
add651ee | 3067 | fn eq(&self, other: &Arc<T, A>) -> bool { |
0731742a | 3068 | ArcEqIdent::eq(self, other) |
b039eaaf | 3069 | } |
1a4d82fc | 3070 | |
c30ab7b3 | 3071 | /// Inequality for two `Arc`s. |
1a4d82fc | 3072 | /// |
353b0b11 | 3073 | /// Two `Arc`s are not equal if their inner values are not equal. |
1a4d82fc | 3074 | /// |
e74abb32 | 3075 | /// If `T` also implements `Eq` (implying reflexivity of equality), |
353b0b11 | 3076 | /// two `Arc`s that point to the same value are always equal. |
0731742a | 3077 | /// |
1a4d82fc JJ |
3078 | /// # Examples |
3079 | /// | |
3080 | /// ``` | |
3081 | /// use std::sync::Arc; | |
3082 | /// | |
85aaf69f | 3083 | /// let five = Arc::new(5); |
1a4d82fc | 3084 | /// |
c30ab7b3 | 3085 | /// assert!(five != Arc::new(6)); |
1a4d82fc | 3086 | /// ``` |
0731742a | 3087 | #[inline] |
add651ee | 3088 | fn ne(&self, other: &Arc<T, A>) -> bool { |
0731742a | 3089 | ArcEqIdent::ne(self, other) |
b039eaaf | 3090 | } |
1a4d82fc | 3091 | } |
0731742a | 3092 | |
85aaf69f | 3093 | #[stable(feature = "rust1", since = "1.0.0")] |
add651ee | 3094 | impl<T: ?Sized + PartialOrd, A: Allocator> PartialOrd for Arc<T, A> { |
c30ab7b3 | 3095 | /// Partial comparison for two `Arc`s. |
1a4d82fc JJ |
3096 | /// |
3097 | /// The two are compared by calling `partial_cmp()` on their inner values. | |
3098 | /// | |
3099 | /// # Examples | |
3100 | /// | |
3101 | /// ``` | |
3102 | /// use std::sync::Arc; | |
c30ab7b3 | 3103 | /// use std::cmp::Ordering; |
1a4d82fc | 3104 | /// |
85aaf69f | 3105 | /// let five = Arc::new(5); |
1a4d82fc | 3106 | /// |
c30ab7b3 | 3107 | /// assert_eq!(Some(Ordering::Less), five.partial_cmp(&Arc::new(6))); |
1a4d82fc | 3108 | /// ``` |
add651ee | 3109 | fn partial_cmp(&self, other: &Arc<T, A>) -> Option<Ordering> { |
1a4d82fc JJ |
3110 | (**self).partial_cmp(&**other) |
3111 | } | |
3112 | ||
c30ab7b3 | 3113 | /// Less-than comparison for two `Arc`s. |
1a4d82fc JJ |
3114 | /// |
3115 | /// The two are compared by calling `<` on their inner values. | |
3116 | /// | |
3117 | /// # Examples | |
3118 | /// | |
3119 | /// ``` | |
3120 | /// use std::sync::Arc; | |
3121 | /// | |
85aaf69f | 3122 | /// let five = Arc::new(5); |
1a4d82fc | 3123 | /// |
c30ab7b3 | 3124 | /// assert!(five < Arc::new(6)); |
1a4d82fc | 3125 | /// ``` |
add651ee | 3126 | fn lt(&self, other: &Arc<T, A>) -> bool { |
b039eaaf SL |
3127 | *(*self) < *(*other) |
3128 | } | |
1a4d82fc | 3129 | |
c30ab7b3 | 3130 | /// 'Less than or equal to' comparison for two `Arc`s. |
1a4d82fc JJ |
3131 | /// |
3132 | /// The two are compared by calling `<=` on their inner values. | |
3133 | /// | |
3134 | /// # Examples | |
3135 | /// | |
3136 | /// ``` | |
3137 | /// use std::sync::Arc; | |
3138 | /// | |
85aaf69f | 3139 | /// let five = Arc::new(5); |
1a4d82fc | 3140 | /// |
c30ab7b3 | 3141 | /// assert!(five <= Arc::new(5)); |
1a4d82fc | 3142 | /// ``` |
add651ee | 3143 | fn le(&self, other: &Arc<T, A>) -> bool { |
b039eaaf SL |
3144 | *(*self) <= *(*other) |
3145 | } | |
1a4d82fc | 3146 | |
c30ab7b3 | 3147 | /// Greater-than comparison for two `Arc`s. |
1a4d82fc JJ |
3148 | /// |
3149 | /// The two are compared by calling `>` on their inner values. | |
3150 | /// | |
3151 | /// # Examples | |
3152 | /// | |
3153 | /// ``` | |
3154 | /// use std::sync::Arc; | |
3155 | /// | |
85aaf69f | 3156 | /// let five = Arc::new(5); |
1a4d82fc | 3157 | /// |
c30ab7b3 | 3158 | /// assert!(five > Arc::new(4)); |
1a4d82fc | 3159 | /// ``` |
add651ee | 3160 | fn gt(&self, other: &Arc<T, A>) -> bool { |
b039eaaf SL |
3161 | *(*self) > *(*other) |
3162 | } | |
1a4d82fc | 3163 | |
c30ab7b3 | 3164 | /// 'Greater than or equal to' comparison for two `Arc`s. |
1a4d82fc JJ |
3165 | /// |
3166 | /// The two are compared by calling `>=` on their inner values. | |
3167 | /// | |
3168 | /// # Examples | |
3169 | /// | |
3170 | /// ``` | |
3171 | /// use std::sync::Arc; | |
3172 | /// | |
85aaf69f | 3173 | /// let five = Arc::new(5); |
1a4d82fc | 3174 | /// |
c30ab7b3 | 3175 | /// assert!(five >= Arc::new(5)); |
1a4d82fc | 3176 | /// ``` |
add651ee | 3177 | fn ge(&self, other: &Arc<T, A>) -> bool { |
b039eaaf SL |
3178 | *(*self) >= *(*other) |
3179 | } | |
1a4d82fc | 3180 | } |
85aaf69f | 3181 | #[stable(feature = "rust1", since = "1.0.0")] |
add651ee | 3182 | impl<T: ?Sized + Ord, A: Allocator> Ord for Arc<T, A> { |
c30ab7b3 SL |
3183 | /// Comparison for two `Arc`s. |
3184 | /// | |
3185 | /// The two are compared by calling `cmp()` on their inner values. | |
3186 | /// | |
3187 | /// # Examples | |
3188 | /// | |
3189 | /// ``` | |
3190 | /// use std::sync::Arc; | |
3191 | /// use std::cmp::Ordering; | |
3192 | /// | |
3193 | /// let five = Arc::new(5); | |
3194 | /// | |
3195 | /// assert_eq!(Ordering::Less, five.cmp(&Arc::new(6))); | |
3196 | /// ``` | |
add651ee | 3197 | fn cmp(&self, other: &Arc<T, A>) -> Ordering { |
b039eaaf SL |
3198 | (**self).cmp(&**other) |
3199 | } | |
1a4d82fc | 3200 | } |
85aaf69f | 3201 | #[stable(feature = "rust1", since = "1.0.0")] |
add651ee | 3202 | impl<T: ?Sized + Eq, A: Allocator> Eq for Arc<T, A> {} |
1a4d82fc | 3203 | |
85aaf69f | 3204 | #[stable(feature = "rust1", since = "1.0.0")] |
add651ee | 3205 | impl<T: ?Sized + fmt::Display, A: Allocator> fmt::Display for Arc<T, A> { |
9fa01778 | 3206 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
85aaf69f | 3207 | fmt::Display::fmt(&**self, f) |
1a4d82fc JJ |
3208 | } |
3209 | } | |
3210 | ||
85aaf69f | 3211 | #[stable(feature = "rust1", since = "1.0.0")] |
add651ee | 3212 | impl<T: ?Sized + fmt::Debug, A: Allocator> fmt::Debug for Arc<T, A> { |
9fa01778 | 3213 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
85aaf69f | 3214 | fmt::Debug::fmt(&**self, f) |
1a4d82fc JJ |
3215 | } |
3216 | } | |
3217 | ||
9346a6ac | 3218 | #[stable(feature = "rust1", since = "1.0.0")] |
add651ee | 3219 | impl<T: ?Sized, A: Allocator> fmt::Pointer for Arc<T, A> { |
9fa01778 | 3220 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
ff7c6d11 | 3221 | fmt::Pointer::fmt(&(&**self as *const T), f) |
9346a6ac AL |
3222 | } |
3223 | } | |
3224 | ||
136023e0 | 3225 | #[cfg(not(no_global_oom_handling))] |
85aaf69f | 3226 | #[stable(feature = "rust1", since = "1.0.0")] |
d9579d0f | 3227 | impl<T: Default> Default for Arc<T> { |
c30ab7b3 SL |
3228 | /// Creates a new `Arc<T>`, with the `Default` value for `T`. |
3229 | /// | |
3230 | /// # Examples | |
3231 | /// | |
3232 | /// ``` | |
3233 | /// use std::sync::Arc; | |
3234 | /// | |
3235 | /// let x: Arc<i32> = Default::default(); | |
3236 | /// assert_eq!(*x, 0); | |
3237 | /// ``` | |
b039eaaf SL |
3238 | fn default() -> Arc<T> { |
3239 | Arc::new(Default::default()) | |
3240 | } | |
1a4d82fc JJ |
3241 | } |
3242 | ||
85aaf69f | 3243 | #[stable(feature = "rust1", since = "1.0.0")] |
add651ee | 3244 | impl<T: ?Sized + Hash, A: Allocator> Hash for Arc<T, A> { |
85aaf69f SL |
3245 | fn hash<H: Hasher>(&self, state: &mut H) { |
3246 | (**self).hash(state) | |
3247 | } | |
3248 | } | |
1a4d82fc | 3249 | |
136023e0 | 3250 | #[cfg(not(no_global_oom_handling))] |
92a42be0 SL |
3251 | #[stable(feature = "from_for_ptrs", since = "1.6.0")] |
3252 | impl<T> From<T> for Arc<T> { | |
136023e0 XL |
3253 | /// Converts a `T` into an `Arc<T>` |
3254 | /// | |
3255 | /// The conversion moves the value into a | |
3256 | /// newly allocated `Arc`. It is equivalent to | |
3257 | /// calling `Arc::new(t)`. | |
3258 | /// | |
3259 | /// # Example | |
3260 | /// ```rust | |
3261 | /// # use std::sync::Arc; | |
3262 | /// let x = 5; | |
3263 | /// let arc = Arc::new(5); | |
3264 | /// | |
3265 | /// assert_eq!(Arc::from(x), arc); | |
3266 | /// ``` | |
92a42be0 SL |
3267 | fn from(t: T) -> Self { |
3268 | Arc::new(t) | |
3269 | } | |
3270 | } | |
3271 | ||
781aab86 FG |
3272 | #[cfg(not(no_global_oom_handling))] |
3273 | #[stable(feature = "shared_from_array", since = "1.74.0")] | |
3274 | impl<T, const N: usize> From<[T; N]> for Arc<[T]> { | |
3275 | /// Converts a [`[T; N]`](prim@array) into an `Arc<[T]>`. | |
3276 | /// | |
3277 | /// The conversion moves the array into a newly allocated `Arc`. | |
3278 | /// | |
3279 | /// # Example | |
3280 | /// | |
3281 | /// ``` | |
3282 | /// # use std::sync::Arc; | |
3283 | /// let original: [i32; 3] = [1, 2, 3]; | |
3284 | /// let shared: Arc<[i32]> = Arc::from(original); | |
3285 | /// assert_eq!(&[1, 2, 3], &shared[..]); | |
3286 | /// ``` | |
3287 | #[inline] | |
3288 | fn from(v: [T; N]) -> Arc<[T]> { | |
3289 | Arc::<[T; N]>::from(v) | |
3290 | } | |
3291 | } | |
3292 | ||
17df50a5 | 3293 | #[cfg(not(no_global_oom_handling))] |
3b2f2976 | 3294 | #[stable(feature = "shared_from_slice", since = "1.21.0")] |
9fa01778 | 3295 | impl<T: Clone> From<&[T]> for Arc<[T]> { |
6a06907d XL |
3296 | /// Allocate a reference-counted slice and fill it by cloning `v`'s items. |
3297 | /// | |
3298 | /// # Example | |
3299 | /// | |
3300 | /// ``` | |
3301 | /// # use std::sync::Arc; | |
3302 | /// let original: &[i32] = &[1, 2, 3]; | |
3303 | /// let shared: Arc<[i32]> = Arc::from(original); | |
3304 | /// assert_eq!(&[1, 2, 3], &shared[..]); | |
3305 | /// ``` | |
3b2f2976 XL |
3306 | #[inline] |
3307 | fn from(v: &[T]) -> Arc<[T]> { | |
3308 | <Self as ArcFromSlice<T>>::from_slice(v) | |
3309 | } | |
3310 | } | |
3311 | ||
17df50a5 | 3312 | #[cfg(not(no_global_oom_handling))] |
3b2f2976 | 3313 | #[stable(feature = "shared_from_slice", since = "1.21.0")] |
9fa01778 | 3314 | impl From<&str> for Arc<str> { |
6a06907d XL |
3315 | /// Allocate a reference-counted `str` and copy `v` into it. |
3316 | /// | |
3317 | /// # Example | |
3318 | /// | |
3319 | /// ``` | |
3320 | /// # use std::sync::Arc; | |
3321 | /// let shared: Arc<str> = Arc::from("eggplant"); | |
3322 | /// assert_eq!("eggplant", &shared[..]); | |
3323 | /// ``` | |
3b2f2976 XL |
3324 | #[inline] |
3325 | fn from(v: &str) -> Arc<str> { | |
ff7c6d11 XL |
3326 | let arc = Arc::<[u8]>::from(v.as_bytes()); |
3327 | unsafe { Arc::from_raw(Arc::into_raw(arc) as *const str) } | |
3b2f2976 XL |
3328 | } |
3329 | } | |
3330 | ||
17df50a5 | 3331 | #[cfg(not(no_global_oom_handling))] |
3b2f2976 XL |
3332 | #[stable(feature = "shared_from_slice", since = "1.21.0")] |
3333 | impl From<String> for Arc<str> { | |
6a06907d XL |
3334 | /// Allocate a reference-counted `str` and copy `v` into it. |
3335 | /// | |
3336 | /// # Example | |
3337 | /// | |
3338 | /// ``` | |
3339 | /// # use std::sync::Arc; | |
3340 | /// let unique: String = "eggplant".to_owned(); | |
3341 | /// let shared: Arc<str> = Arc::from(unique); | |
3342 | /// assert_eq!("eggplant", &shared[..]); | |
3343 | /// ``` | |
3b2f2976 XL |
3344 | #[inline] |
3345 | fn from(v: String) -> Arc<str> { | |
3346 | Arc::from(&v[..]) | |
3347 | } | |
3348 | } | |
3349 | ||
17df50a5 | 3350 | #[cfg(not(no_global_oom_handling))] |
3b2f2976 | 3351 | #[stable(feature = "shared_from_slice", since = "1.21.0")] |
add651ee | 3352 | impl<T: ?Sized, A: Allocator> From<Box<T, A>> for Arc<T, A> { |
6a06907d XL |
3353 | /// Move a boxed object to a new, reference-counted allocation. |
3354 | /// | |
3355 | /// # Example | |
3356 | /// | |
3357 | /// ``` | |
3358 | /// # use std::sync::Arc; | |
3359 | /// let unique: Box<str> = Box::from("eggplant"); | |
3360 | /// let shared: Arc<str> = Arc::from(unique); | |
3361 | /// assert_eq!("eggplant", &shared[..]); | |
3362 | /// ``` | |
3b2f2976 | 3363 | #[inline] |
add651ee FG |
3364 | fn from(v: Box<T, A>) -> Arc<T, A> { |
3365 | Arc::from_box_in(v) | |
3b2f2976 XL |
3366 | } |
3367 | } | |
3368 | ||
17df50a5 | 3369 | #[cfg(not(no_global_oom_handling))] |
3b2f2976 | 3370 | #[stable(feature = "shared_from_slice", since = "1.21.0")] |
add651ee | 3371 | impl<T, A: Allocator + Clone> From<Vec<T, A>> for Arc<[T], A> { |
6a06907d XL |
3372 | /// Allocate a reference-counted slice and move `v`'s items into it. |
3373 | /// | |
3374 | /// # Example | |
3375 | /// | |
3376 | /// ``` | |
3377 | /// # use std::sync::Arc; | |
3378 | /// let unique: Vec<i32> = vec![1, 2, 3]; | |
3379 | /// let shared: Arc<[i32]> = Arc::from(unique); | |
3380 | /// assert_eq!(&[1, 2, 3], &shared[..]); | |
3381 | /// ``` | |
3b2f2976 | 3382 | #[inline] |
add651ee | 3383 | fn from(v: Vec<T, A>) -> Arc<[T], A> { |
3b2f2976 | 3384 | unsafe { |
add651ee FG |
3385 | let (vec_ptr, len, cap, alloc) = v.into_raw_parts_with_alloc(); |
3386 | ||
3387 | let rc_ptr = Self::allocate_for_slice_in(len, &alloc); | |
3388 | ptr::copy_nonoverlapping(vec_ptr, &mut (*rc_ptr).data as *mut [T] as *mut T, len); | |
3389 | ||
3390 | // Create a `Vec<T, &A>` with length 0, to deallocate the buffer | |
3391 | // without dropping its contents or the allocator | |
3392 | let _ = Vec::from_raw_parts_in(vec_ptr, 0, cap, &alloc); | |
3393 | ||
3394 | Self::from_ptr_in(rc_ptr, alloc) | |
3b2f2976 XL |
3395 | } |
3396 | } | |
3397 | } | |
3398 | ||
f9f354fc XL |
3399 | #[stable(feature = "shared_from_cow", since = "1.45.0")] |
3400 | impl<'a, B> From<Cow<'a, B>> for Arc<B> | |
3401 | where | |
3402 | B: ToOwned + ?Sized, | |
3403 | Arc<B>: From<&'a B> + From<B::Owned>, | |
3404 | { | |
17df50a5 XL |
3405 | /// Create an atomically reference-counted pointer from |
3406 | /// a clone-on-write pointer by copying its content. | |
3407 | /// | |
3408 | /// # Example | |
3409 | /// | |
3410 | /// ```rust | |
3411 | /// # use std::sync::Arc; | |
3412 | /// # use std::borrow::Cow; | |
49aad941 | 3413 | /// let cow: Cow<'_, str> = Cow::Borrowed("eggplant"); |
17df50a5 XL |
3414 | /// let shared: Arc<str> = Arc::from(cow); |
3415 | /// assert_eq!("eggplant", &shared[..]); | |
3416 | /// ``` | |
f9f354fc XL |
3417 | #[inline] |
3418 | fn from(cow: Cow<'a, B>) -> Arc<B> { | |
3419 | match cow { | |
3420 | Cow::Borrowed(s) => Arc::from(s), | |
3421 | Cow::Owned(s) => Arc::from(s), | |
3422 | } | |
3423 | } | |
3424 | } | |
3425 | ||
04454e1e FG |
3426 | #[stable(feature = "shared_from_str", since = "1.62.0")] |
3427 | impl From<Arc<str>> for Arc<[u8]> { | |
3428 | /// Converts an atomically reference-counted string slice into a byte slice. | |
3429 | /// | |
3430 | /// # Example | |
3431 | /// | |
3432 | /// ``` | |
3433 | /// # use std::sync::Arc; | |
3434 | /// let string: Arc<str> = Arc::from("eggplant"); | |
3435 | /// let bytes: Arc<[u8]> = Arc::from(string); | |
3436 | /// assert_eq!("eggplant".as_bytes(), bytes.as_ref()); | |
3437 | /// ``` | |
3438 | #[inline] | |
3439 | fn from(rc: Arc<str>) -> Self { | |
3440 | // SAFETY: `str` has the same layout as `[u8]`. | |
3441 | unsafe { Arc::from_raw(Arc::into_raw(rc) as *const [u8]) } | |
3442 | } | |
3443 | } | |
3444 | ||
74b04a01 | 3445 | #[stable(feature = "boxed_slice_try_from", since = "1.43.0")] |
add651ee FG |
3446 | impl<T, A: Allocator + Clone, const N: usize> TryFrom<Arc<[T], A>> for Arc<[T; N], A> { |
3447 | type Error = Arc<[T], A>; | |
1a4d82fc | 3448 | |
add651ee | 3449 | fn try_from(boxed_slice: Arc<[T], A>) -> Result<Self, Self::Error> { |
416331ca | 3450 | if boxed_slice.len() == N { |
add651ee FG |
3451 | let alloc = boxed_slice.alloc.clone(); |
3452 | Ok(unsafe { Arc::from_raw_in(Arc::into_raw(boxed_slice) as *mut [T; N], alloc) }) | |
416331ca XL |
3453 | } else { |
3454 | Err(boxed_slice) | |
3b2f2976 | 3455 | } |
3b2f2976 | 3456 | } |
416331ca | 3457 | } |
3b2f2976 | 3458 | |
17df50a5 | 3459 | #[cfg(not(no_global_oom_handling))] |
416331ca | 3460 | #[stable(feature = "shared_from_iter", since = "1.37.0")] |
353b0b11 | 3461 | impl<T> FromIterator<T> for Arc<[T]> { |
416331ca XL |
3462 | /// Takes each element in the `Iterator` and collects it into an `Arc<[T]>`. |
3463 | /// | |
3464 | /// # Performance characteristics | |
3465 | /// | |
3466 | /// ## The general case | |
3467 | /// | |
3468 | /// In the general case, collecting into `Arc<[T]>` is done by first | |
3469 | /// collecting into a `Vec<T>`. That is, when writing the following: | |
3470 | /// | |
3471 | /// ```rust | |
3472 | /// # use std::sync::Arc; | |
3473 | /// let evens: Arc<[u8]> = (0..10).filter(|&x| x % 2 == 0).collect(); | |
3474 | /// # assert_eq!(&*evens, &[0, 2, 4, 6, 8]); | |
3475 | /// ``` | |
3476 | /// | |
3477 | /// this behaves as if we wrote: | |
3478 | /// | |
3479 | /// ```rust | |
3480 | /// # use std::sync::Arc; | |
3481 | /// let evens: Arc<[u8]> = (0..10).filter(|&x| x % 2 == 0) | |
3482 | /// .collect::<Vec<_>>() // The first set of allocations happens here. | |
3483 | /// .into(); // A second allocation for `Arc<[T]>` happens here. | |
3484 | /// # assert_eq!(&*evens, &[0, 2, 4, 6, 8]); | |
3485 | /// ``` | |
3486 | /// | |
3487 | /// This will allocate as many times as needed for constructing the `Vec<T>` | |
3488 | /// and then it will allocate once for turning the `Vec<T>` into the `Arc<[T]>`. | |
3489 | /// | |
3490 | /// ## Iterators of known length | |
3491 | /// | |
3492 | /// When your `Iterator` implements `TrustedLen` and is of an exact size, | |
3493 | /// a single allocation will be made for the `Arc<[T]>`. For example: | |
3494 | /// | |
3495 | /// ```rust | |
3496 | /// # use std::sync::Arc; | |
3497 | /// let evens: Arc<[u8]> = (0..10).collect(); // Just a single allocation happens here. | |
3498 | /// # assert_eq!(&*evens, &*(0..10).collect::<Vec<_>>()); | |
3499 | /// ``` | |
353b0b11 | 3500 | fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self { |
f9f354fc | 3501 | ToArcSlice::to_arc_slice(iter.into_iter()) |
3b2f2976 | 3502 | } |
416331ca | 3503 | } |
3b2f2976 | 3504 | |
416331ca | 3505 | /// Specialization trait used for collecting into `Arc<[T]>`. |
f9f354fc XL |
3506 | trait ToArcSlice<T>: Iterator<Item = T> + Sized { |
3507 | fn to_arc_slice(self) -> Arc<[T]>; | |
416331ca | 3508 | } |
3b2f2976 | 3509 | |
17df50a5 | 3510 | #[cfg(not(no_global_oom_handling))] |
f9f354fc XL |
3511 | impl<T, I: Iterator<Item = T>> ToArcSlice<T> for I { |
3512 | default fn to_arc_slice(self) -> Arc<[T]> { | |
3513 | self.collect::<Vec<T>>().into() | |
3b2f2976 | 3514 | } |
416331ca | 3515 | } |
3b2f2976 | 3516 | |
17df50a5 | 3517 | #[cfg(not(no_global_oom_handling))] |
f9f354fc XL |
3518 | impl<T, I: iter::TrustedLen<Item = T>> ToArcSlice<T> for I { |
3519 | fn to_arc_slice(self) -> Arc<[T]> { | |
416331ca | 3520 | // This is the case for a `TrustedLen` iterator. |
f9f354fc | 3521 | let (low, high) = self.size_hint(); |
416331ca XL |
3522 | if let Some(high) = high { |
3523 | debug_assert_eq!( | |
dfeec247 XL |
3524 | low, |
3525 | high, | |
416331ca XL |
3526 | "TrustedLen iterator's size hint is not exact: {:?}", |
3527 | (low, high) | |
3528 | ); | |
3b2f2976 | 3529 | |
416331ca XL |
3530 | unsafe { |
3531 | // SAFETY: We need to ensure that the iterator has an exact length and we have. | |
f9f354fc | 3532 | Arc::from_iter_exact(self, low) |
3b2f2976 | 3533 | } |
416331ca | 3534 | } else { |
9ffffee4 | 3535 | // TrustedLen contract guarantees that `upper_bound == None` implies an iterator |
cdc7bbd5 XL |
3536 | // length exceeding `usize::MAX`. |
3537 | // The default implementation would collect into a vec which would panic. | |
3538 | // Thus we panic here immediately without invoking `Vec` code. | |
3539 | panic!("capacity overflow"); | |
3b2f2976 | 3540 | } |
3b2f2976 | 3541 | } |
416331ca | 3542 | } |
3b2f2976 | 3543 | |
92a42be0 | 3544 | #[stable(feature = "rust1", since = "1.0.0")] |
add651ee | 3545 | impl<T: ?Sized, A: Allocator> borrow::Borrow<T> for Arc<T, A> { |
b039eaaf SL |
3546 | fn borrow(&self) -> &T { |
3547 | &**self | |
3548 | } | |
3549 | } | |
3550 | ||
3551 | #[stable(since = "1.5.0", feature = "smart_ptr_as_ref")] | |
add651ee | 3552 | impl<T: ?Sized, A: Allocator> AsRef<T> for Arc<T, A> { |
b039eaaf SL |
3553 | fn as_ref(&self) -> &T { |
3554 | &**self | |
3555 | } | |
e9174d1e | 3556 | } |
b7449926 | 3557 | |
0731742a | 3558 | #[stable(feature = "pin", since = "1.33.0")] |
add651ee | 3559 | impl<T: ?Sized, A: Allocator> Unpin for Arc<T, A> {} |
dc9dc135 | 3560 | |
5869c6ff | 3561 | /// Get the offset within an `ArcInner` for the payload behind a pointer. |
f035d41b XL |
3562 | /// |
3563 | /// # Safety | |
3564 | /// | |
5869c6ff XL |
3565 | /// The pointer must point to (and have valid metadata for) a previously |
3566 | /// valid instance of T, but the T is allowed to be dropped. | |
064997fb | 3567 | unsafe fn data_offset<T: ?Sized>(ptr: *const T) -> usize { |
5869c6ff XL |
3568 | // Align the unsized value to the end of the ArcInner. |
3569 | // Because RcBox is repr(C), it will always be the last field in memory. | |
3570 | // SAFETY: since the only unsized types possible are slices, trait objects, | |
3571 | // and extern types, the input safety requirement is currently enough to | |
3572 | // satisfy the requirements of align_of_val_raw; this is an implementation | |
94222f64 | 3573 | // detail of the language that must not be relied upon outside of std. |
5869c6ff | 3574 | unsafe { data_offset_align(align_of_val_raw(ptr)) } |
416331ca XL |
3575 | } |
3576 | ||
3577 | #[inline] | |
064997fb | 3578 | fn data_offset_align(align: usize) -> usize { |
dc9dc135 | 3579 | let layout = Layout::new::<ArcInner<()>>(); |
064997fb | 3580 | layout.size() + layout.padding_needed_for(align) |
dc9dc135 | 3581 | } |
f2b60f7d | 3582 | |
f2b60f7d FG |
3583 | #[stable(feature = "arc_error", since = "1.52.0")] |
3584 | impl<T: core::error::Error + ?Sized> core::error::Error for Arc<T> { | |
3585 | #[allow(deprecated, deprecated_in_future)] | |
3586 | fn description(&self) -> &str { | |
3587 | core::error::Error::description(&**self) | |
3588 | } | |
3589 | ||
3590 | #[allow(deprecated)] | |
3591 | fn cause(&self) -> Option<&dyn core::error::Error> { | |
3592 | core::error::Error::cause(&**self) | |
3593 | } | |
3594 | ||
3595 | fn source(&self) -> Option<&(dyn core::error::Error + 'static)> { | |
3596 | core::error::Error::source(&**self) | |
3597 | } | |
3598 | ||
add651ee | 3599 | fn provide<'a>(&'a self, req: &mut core::error::Request<'a>) { |
f2b60f7d FG |
3600 | core::error::Error::provide(&**self, req); |
3601 | } | |
3602 | } |