1 | //! Shareable mutable containers. |
2 | //! |
3 | //! Rust memory safety is based on this rule: Given an object `T`, it is only possible to |
4 | //! have one of the following: |
5 | //! |
6 | //! - Several immutable references (`&T`) to the object (also known as **aliasing**). |
7 | //! - One mutable reference (`&mut T`) to the object (also known as **mutability**). |
8 | //! |
9 | //! This is enforced by the Rust compiler. However, there are situations where this rule is not |
10 | //! flexible enough. Sometimes it is required to have multiple references to an object and yet |
11 | //! mutate it. |
12 | //! |
13 | //! Shareable mutable containers exist to permit mutability in a controlled manner, even in the |
14 | //! presence of aliasing. [`Cell<T>`], [`RefCell<T>`], and [`OnceCell<T>`] allow doing this in |
15 | //! a single-threaded way—they do not implement [`Sync`]. (If you need to do aliasing and |
16 | //! mutation among multiple threads, [`Mutex<T>`], [`RwLock<T>`], [`OnceLock<T>`] or [`atomic`] |
17 | //! types are the correct data structures to do so). |
18 | //! |
19 | //! Values of the `Cell<T>`, `RefCell<T>`, and `OnceCell<T>` types may be mutated through shared |
20 | //! references (i.e. the common `&T` type), whereas most Rust types can only be mutated through |
21 | //! unique (`&mut T`) references. We say these cell types provide 'interior mutability' |
22 | //! (mutable via `&T`), in contrast with typical Rust types that exhibit 'inherited mutability' |
23 | //! (mutable only via `&mut T`). |
24 | //! |
25 | //! Cell types come in four flavors: `Cell<T>`, `RefCell<T>`, `OnceCell<T>`, and `LazyCell<T>`. |
26 | //! Each provides a different way of providing safe interior mutability. |
27 | //! |
28 | //! ## `Cell<T>` |
29 | //! |
30 | //! [`Cell<T>`] implements interior mutability by moving values in and out of the cell. That is, an |
31 | //! `&mut T` to the inner value can never be obtained, and the value itself cannot be directly |
32 | //! obtained without replacing it with something else. Both of these rules ensure that there is |
33 | //! never more than one reference pointing to the inner value. This type provides the following |
34 | //! methods: |
35 | //! |
36 | //! - For types that implement [`Copy`], the [`get`](Cell::get) method retrieves the current |
37 | //! interior value by duplicating it. |
38 | //! - For types that implement [`Default`], the [`take`](Cell::take) method replaces the current |
39 | //! interior value with [`Default::default()`] and returns the replaced value. |
40 | //! - All types have: |
41 | //! - [`replace`](Cell::replace): replaces the current interior value and returns the replaced |
42 | //! value. |
43 | //! - [`into_inner`](Cell::into_inner): this method consumes the `Cell<T>` and returns the |
44 | //! interior value. |
45 | //! - [`set`](Cell::set): this method replaces the interior value, dropping the replaced value. |
46 | //! |
47 | //! `Cell<T>` is typically used for more simple types where copying or moving values isn't too |
48 | //! resource intensive (e.g. numbers), and should usually be preferred over other cell types when |
49 | //! possible. For larger and non-copy types, `RefCell` provides some advantages. |
50 | //! |
51 | //! ## `RefCell<T>` |
52 | //! |
53 | //! [`RefCell<T>`] uses Rust's lifetimes to implement "dynamic borrowing", a process whereby one can |
54 | //! claim temporary, exclusive, mutable access to the inner value. Borrows for `RefCell<T>`s are |
55 | //! tracked at _runtime_, unlike Rust's native reference types which are entirely tracked |
56 | //! statically, at compile time. |
57 | //! |
58 | //! An immutable reference to a `RefCell`'s inner value (`&T`) can be obtained with |
59 | //! [`borrow`](`RefCell::borrow`), and a mutable borrow (`&mut T`) can be obtained with |
60 | //! [`borrow_mut`](`RefCell::borrow_mut`). When these functions are called, they first verify that |
61 | //! Rust's borrow rules will be satisfied: any number of immutable borrows are allowed or a |
62 | //! single mutable borrow is allowed, but never both. If a borrow is attempted that would violate |
63 | //! these rules, the thread will panic. |
64 | //! |
65 | //! The corresponding [`Sync`] version of `RefCell<T>` is [`RwLock<T>`]. |
66 | //! |
67 | //! ## `OnceCell<T>` |
68 | //! |
69 | //! [`OnceCell<T>`] is somewhat of a hybrid of `Cell` and `RefCell` that works for values that |
70 | //! typically only need to be set once. This means that a reference `&T` can be obtained without |
71 | //! moving or copying the inner value (unlike `Cell`) but also without runtime checks (unlike |
72 | //! `RefCell`). However, its value can also not be updated once set unless you have a mutable |
73 | //! reference to the `OnceCell`. |
74 | //! |
75 | //! `OnceCell` provides the following methods: |
76 | //! |
77 | //! - [`get`](OnceCell::get): obtain a reference to the inner value |
78 | //! - [`set`](OnceCell::set): set the inner value if it is unset (returns a `Result`) |
79 | //! - [`get_or_init`](OnceCell::get_or_init): return the inner value, initializing it if needed |
80 | //! - [`get_mut`](OnceCell::get_mut): provide a mutable reference to the inner value, only available |
81 | //! if you have a mutable reference to the cell itself. |
82 | //! |
83 | //! The corresponding [`Sync`] version of `OnceCell<T>` is [`OnceLock<T>`]. |
84 | //! |
85 | //! ## `LazyCell<T, F>` |
86 | //! |
87 | //! A common pattern with OnceCell is, for a given OnceCell, to use the same function on every |
88 | //! call to [`OnceCell::get_or_init`] with that cell. This is what is offered by [`LazyCell`], |
89 | //! which pairs cells of `T` with functions of `F`, and always calls `F` before it yields `&T`. |
90 | //! This happens implicitly by simply attempting to dereference the LazyCell to get its contents, |
91 | //! so its use is much more transparent with a place which has been initialized by a constant. |
92 | //! |
93 | //! More complicated patterns that don't fit this description can be built on `OnceCell<T>` instead. |
94 | //! |
95 | //! `LazyCell` works by providing an implementation of `impl Deref` that calls the function, |
96 | //! so you can just use it by dereference (e.g. `*lazy_cell` or `lazy_cell.deref()`). |
97 | //! |
98 | //! The corresponding [`Sync`] version of `LazyCell<T, F>` is [`LazyLock<T, F>`]. |
99 | //! |
100 | //! # When to choose interior mutability |
101 | //! |
102 | //! The more common inherited mutability, where one must have unique access to mutate a value, is |
103 | //! one of the key language elements that enables Rust to reason strongly about pointer aliasing, |
104 | //! statically preventing crash bugs. Because of that, inherited mutability is preferred, and |
105 | //! interior mutability is something of a last resort. Since cell types enable mutation where it |
106 | //! would otherwise be disallowed though, there are occasions when interior mutability might be |
107 | //! appropriate, or even *must* be used, e.g. |
108 | //! |
109 | //! * Introducing mutability 'inside' of something immutable |
110 | //! * Implementation details of logically-immutable methods. |
111 | //! * Mutating implementations of [`Clone`]. |
112 | //! |
113 | //! ## Introducing mutability 'inside' of something immutable |
114 | //! |
115 | //! Many shared smart pointer types, including [`Rc<T>`] and [`Arc<T>`], provide containers that can |
116 | //! be cloned and shared between multiple parties. Because the contained values may be |
117 | //! multiply-aliased, they can only be borrowed with `&`, not `&mut`. Without cells it would be |
118 | //! impossible to mutate data inside of these smart pointers at all. |
119 | //! |
120 | //! It's very common then to put a `RefCell<T>` inside shared pointer types to reintroduce |
121 | //! mutability: |
122 | //! |
123 | //! ``` |
124 | //! use std::cell::{RefCell, RefMut}; |
125 | //! use std::collections::HashMap; |
126 | //! use std::rc::Rc; |
127 | //! |
128 | //! fn main() { |
129 | //! let shared_map: Rc<RefCell<_>> = Rc::new(RefCell::new(HashMap::new())); |
130 | //! // Create a new block to limit the scope of the dynamic borrow |
131 | //! { |
132 | //! let mut map: RefMut<'_, _> = shared_map.borrow_mut(); |
133 | //! map.insert("africa" , 92388); |
134 | //! map.insert("kyoto" , 11837); |
135 | //! map.insert("piccadilly" , 11826); |
136 | //! map.insert("marbles" , 38); |
137 | //! } |
138 | //! |
139 | //! // Note that if we had not let the previous borrow of the cache fall out |
140 | //! // of scope then the subsequent borrow would cause a dynamic thread panic. |
141 | //! // This is the major hazard of using `RefCell`. |
142 | //! let total: i32 = shared_map.borrow().values().sum(); |
143 | //! println!("{total}" ); |
144 | //! } |
145 | //! ``` |
146 | //! |
147 | //! Note that this example uses `Rc<T>` and not `Arc<T>`. `RefCell<T>`s are for single-threaded |
148 | //! scenarios. Consider using [`RwLock<T>`] or [`Mutex<T>`] if you need shared mutability in a |
149 | //! multi-threaded situation. |
150 | //! |
151 | //! ## Implementation details of logically-immutable methods |
152 | //! |
153 | //! Occasionally it may be desirable not to expose in an API that there is mutation happening |
154 | //! "under the hood". This may be because logically the operation is immutable, but e.g., caching |
155 | //! forces the implementation to perform mutation; or because you must employ mutation to implement |
156 | //! a trait method that was originally defined to take `&self`. |
157 | //! |
158 | //! ``` |
159 | //! # #![allow(dead_code)] |
160 | //! use std::cell::OnceCell; |
161 | //! |
162 | //! struct Graph { |
163 | //! edges: Vec<(i32, i32)>, |
164 | //! span_tree_cache: OnceCell<Vec<(i32, i32)>> |
165 | //! } |
166 | //! |
167 | //! impl Graph { |
168 | //! fn minimum_spanning_tree(&self) -> Vec<(i32, i32)> { |
169 | //! self.span_tree_cache |
170 | //! .get_or_init(|| self.calc_span_tree()) |
171 | //! .clone() |
172 | //! } |
173 | //! |
174 | //! fn calc_span_tree(&self) -> Vec<(i32, i32)> { |
175 | //! // Expensive computation goes here |
176 | //! vec![] |
177 | //! } |
178 | //! } |
179 | //! ``` |
180 | //! |
181 | //! ## Mutating implementations of `Clone` |
182 | //! |
183 | //! This is simply a special - but common - case of the previous: hiding mutability for operations |
184 | //! that appear to be immutable. The [`clone`](Clone::clone) method is expected to not change the |
185 | //! source value, and is declared to take `&self`, not `&mut self`. Therefore, any mutation that |
186 | //! happens in the `clone` method must use cell types. For example, [`Rc<T>`] maintains its |
187 | //! reference counts within a `Cell<T>`. |
188 | //! |
189 | //! ``` |
190 | //! use std::cell::Cell; |
191 | //! use std::ptr::NonNull; |
192 | //! use std::process::abort; |
193 | //! use std::marker::PhantomData; |
194 | //! |
195 | //! struct Rc<T: ?Sized> { |
196 | //! ptr: NonNull<RcInner<T>>, |
197 | //! phantom: PhantomData<RcInner<T>>, |
198 | //! } |
199 | //! |
200 | //! struct RcInner<T: ?Sized> { |
201 | //! strong: Cell<usize>, |
202 | //! refcount: Cell<usize>, |
203 | //! value: T, |
204 | //! } |
205 | //! |
206 | //! impl<T: ?Sized> Clone for Rc<T> { |
207 | //! fn clone(&self) -> Rc<T> { |
208 | //! self.inc_strong(); |
209 | //! Rc { |
210 | //! ptr: self.ptr, |
211 | //! phantom: PhantomData, |
212 | //! } |
213 | //! } |
214 | //! } |
215 | //! |
216 | //! trait RcInnerPtr<T: ?Sized> { |
217 | //! |
218 | //! fn inner(&self) -> &RcInner<T>; |
219 | //! |
220 | //! fn strong(&self) -> usize { |
221 | //! self.inner().strong.get() |
222 | //! } |
223 | //! |
224 | //! fn inc_strong(&self) { |
225 | //! self.inner() |
226 | //! .strong |
227 | //! .set(self.strong() |
228 | //! .checked_add(1) |
229 | //! .unwrap_or_else(|| abort() )); |
230 | //! } |
231 | //! } |
232 | //! |
233 | //! impl<T: ?Sized> RcInnerPtr<T> for Rc<T> { |
234 | //! fn inner(&self) -> &RcInner<T> { |
235 | //! unsafe { |
236 | //! self.ptr.as_ref() |
237 | //! } |
238 | //! } |
239 | //! } |
240 | //! ``` |
241 | //! |
242 | //! [`Arc<T>`]: ../../std/sync/struct.Arc.html |
243 | //! [`Rc<T>`]: ../../std/rc/struct.Rc.html |
244 | //! [`RwLock<T>`]: ../../std/sync/struct.RwLock.html |
245 | //! [`Mutex<T>`]: ../../std/sync/struct.Mutex.html |
246 | //! [`OnceLock<T>`]: ../../std/sync/struct.OnceLock.html |
247 | //! [`LazyLock<T, F>`]: ../../std/sync/struct.LazyLock.html |
248 | //! [`Sync`]: ../../std/marker/trait.Sync.html |
249 | //! [`atomic`]: crate::sync::atomic |
250 | |
251 | #![stable (feature = "rust1" , since = "1.0.0" )] |
252 | |
253 | use crate::cmp::Ordering; |
254 | use crate::fmt::{self, Debug, Display}; |
255 | use crate::marker::{PhantomData, PointerLike, Unsize}; |
256 | use crate::mem; |
257 | use crate::ops::{CoerceUnsized, Deref, DerefMut, DerefPure, DispatchFromDyn}; |
258 | use crate::pin::PinCoerceUnsized; |
259 | use crate::ptr::{self, NonNull}; |
260 | |
261 | mod lazy; |
262 | mod once; |
263 | |
264 | #[stable (feature = "lazy_cell" , since = "1.80.0" )] |
265 | pub use lazy::LazyCell; |
266 | #[stable (feature = "once_cell" , since = "1.70.0" )] |
267 | pub use once::OnceCell; |
268 | |
269 | /// A mutable memory location. |
270 | /// |
271 | /// # Memory layout |
272 | /// |
273 | /// `Cell<T>` has the same [memory layout and caveats as |
274 | /// `UnsafeCell<T>`](UnsafeCell#memory-layout). In particular, this means that |
275 | /// `Cell<T>` has the same in-memory representation as its inner type `T`. |
276 | /// |
277 | /// # Examples |
278 | /// |
279 | /// In this example, you can see that `Cell<T>` enables mutation inside an |
280 | /// immutable struct. In other words, it enables "interior mutability". |
281 | /// |
282 | /// ``` |
283 | /// use std::cell::Cell; |
284 | /// |
285 | /// struct SomeStruct { |
286 | /// regular_field: u8, |
287 | /// special_field: Cell<u8>, |
288 | /// } |
289 | /// |
290 | /// let my_struct = SomeStruct { |
291 | /// regular_field: 0, |
292 | /// special_field: Cell::new(1), |
293 | /// }; |
294 | /// |
295 | /// let new_value = 100; |
296 | /// |
297 | /// // ERROR: `my_struct` is immutable |
298 | /// // my_struct.regular_field = new_value; |
299 | /// |
300 | /// // WORKS: although `my_struct` is immutable, `special_field` is a `Cell`, |
301 | /// // which can always be mutated |
302 | /// my_struct.special_field.set(new_value); |
303 | /// assert_eq!(my_struct.special_field.get(), new_value); |
304 | /// ``` |
305 | /// |
306 | /// See the [module-level documentation](self) for more. |
307 | #[rustc_diagnostic_item = "Cell" ] |
308 | #[stable (feature = "rust1" , since = "1.0.0" )] |
309 | #[repr (transparent)] |
310 | #[rustc_pub_transparent] |
311 | pub struct Cell<T: ?Sized> { |
312 | value: UnsafeCell<T>, |
313 | } |
314 | |
315 | #[stable (feature = "rust1" , since = "1.0.0" )] |
316 | unsafe impl<T: ?Sized> Send for Cell<T> where T: Send {} |
317 | |
318 | // Note that this negative impl isn't strictly necessary for correctness, |
319 | // as `Cell` wraps `UnsafeCell`, which is itself `!Sync`. |
320 | // However, given how important `Cell`'s `!Sync`-ness is, |
321 | // having an explicit negative impl is nice for documentation purposes |
322 | // and results in nicer error messages. |
323 | #[stable (feature = "rust1" , since = "1.0.0" )] |
324 | impl<T: ?Sized> !Sync for Cell<T> {} |
325 | |
326 | #[stable (feature = "rust1" , since = "1.0.0" )] |
327 | impl<T: Copy> Clone for Cell<T> { |
328 | #[inline ] |
329 | fn clone(&self) -> Cell<T> { |
330 | Cell::new(self.get()) |
331 | } |
332 | } |
333 | |
334 | #[stable (feature = "rust1" , since = "1.0.0" )] |
335 | impl<T: Default> Default for Cell<T> { |
336 | /// Creates a `Cell<T>`, with the `Default` value for T. |
337 | #[inline ] |
338 | fn default() -> Cell<T> { |
339 | Cell::new(Default::default()) |
340 | } |
341 | } |
342 | |
343 | #[stable (feature = "rust1" , since = "1.0.0" )] |
344 | impl<T: PartialEq + Copy> PartialEq for Cell<T> { |
345 | #[inline ] |
346 | fn eq(&self, other: &Cell<T>) -> bool { |
347 | self.get() == other.get() |
348 | } |
349 | } |
350 | |
351 | #[stable (feature = "cell_eq" , since = "1.2.0" )] |
352 | impl<T: Eq + Copy> Eq for Cell<T> {} |
353 | |
354 | #[stable (feature = "cell_ord" , since = "1.10.0" )] |
355 | impl<T: PartialOrd + Copy> PartialOrd for Cell<T> { |
356 | #[inline ] |
357 | fn partial_cmp(&self, other: &Cell<T>) -> Option<Ordering> { |
358 | self.get().partial_cmp(&other.get()) |
359 | } |
360 | |
361 | #[inline ] |
362 | fn lt(&self, other: &Cell<T>) -> bool { |
363 | self.get() < other.get() |
364 | } |
365 | |
366 | #[inline ] |
367 | fn le(&self, other: &Cell<T>) -> bool { |
368 | self.get() <= other.get() |
369 | } |
370 | |
371 | #[inline ] |
372 | fn gt(&self, other: &Cell<T>) -> bool { |
373 | self.get() > other.get() |
374 | } |
375 | |
376 | #[inline ] |
377 | fn ge(&self, other: &Cell<T>) -> bool { |
378 | self.get() >= other.get() |
379 | } |
380 | } |
381 | |
382 | #[stable (feature = "cell_ord" , since = "1.10.0" )] |
383 | impl<T: Ord + Copy> Ord for Cell<T> { |
384 | #[inline ] |
385 | fn cmp(&self, other: &Cell<T>) -> Ordering { |
386 | self.get().cmp(&other.get()) |
387 | } |
388 | } |
389 | |
390 | #[stable (feature = "cell_from" , since = "1.12.0" )] |
391 | impl<T> From<T> for Cell<T> { |
392 | /// Creates a new `Cell<T>` containing the given value. |
393 | fn from(t: T) -> Cell<T> { |
394 | Cell::new(t) |
395 | } |
396 | } |
397 | |
398 | impl<T> Cell<T> { |
399 | /// Creates a new `Cell` containing the given value. |
400 | /// |
401 | /// # Examples |
402 | /// |
403 | /// ``` |
404 | /// use std::cell::Cell; |
405 | /// |
406 | /// let c = Cell::new(5); |
407 | /// ``` |
408 | #[stable (feature = "rust1" , since = "1.0.0" )] |
409 | #[rustc_const_stable (feature = "const_cell_new" , since = "1.24.0" )] |
410 | #[inline ] |
411 | pub const fn new(value: T) -> Cell<T> { |
412 | Cell { value: UnsafeCell::new(value) } |
413 | } |
414 | |
415 | /// Sets the contained value. |
416 | /// |
417 | /// # Examples |
418 | /// |
419 | /// ``` |
420 | /// use std::cell::Cell; |
421 | /// |
422 | /// let c = Cell::new(5); |
423 | /// |
424 | /// c.set(10); |
425 | /// ``` |
426 | #[inline ] |
427 | #[stable (feature = "rust1" , since = "1.0.0" )] |
428 | pub fn set(&self, val: T) { |
429 | self.replace(val); |
430 | } |
431 | |
432 | /// Swaps the values of two `Cell`s. |
433 | /// |
434 | /// The difference with `std::mem::swap` is that this function doesn't |
435 | /// require a `&mut` reference. |
436 | /// |
437 | /// # Panics |
438 | /// |
439 | /// This function will panic if `self` and `other` are different `Cell`s that partially overlap. |
440 | /// (Using just standard library methods, it is impossible to create such partially overlapping `Cell`s. |
441 | /// However, unsafe code is allowed to e.g. create two `&Cell<[i32; 2]>` that partially overlap.) |
442 | /// |
443 | /// # Examples |
444 | /// |
445 | /// ``` |
446 | /// use std::cell::Cell; |
447 | /// |
448 | /// let c1 = Cell::new(5i32); |
449 | /// let c2 = Cell::new(10i32); |
450 | /// c1.swap(&c2); |
451 | /// assert_eq!(10, c1.get()); |
452 | /// assert_eq!(5, c2.get()); |
453 | /// ``` |
454 | #[inline ] |
455 | #[stable (feature = "move_cell" , since = "1.17.0" )] |
456 | pub fn swap(&self, other: &Self) { |
457 | // This function documents that it *will* panic, and intrinsics::is_nonoverlapping doesn't |
458 | // do the check in const, so trying to use it here would be inviting unnecessary fragility. |
459 | fn is_nonoverlapping<T>(src: *const T, dst: *const T) -> bool { |
460 | let src_usize = src.addr(); |
461 | let dst_usize = dst.addr(); |
462 | let diff = src_usize.abs_diff(dst_usize); |
463 | diff >= size_of::<T>() |
464 | } |
465 | |
466 | if ptr::eq(self, other) { |
467 | // Swapping wouldn't change anything. |
468 | return; |
469 | } |
470 | if !is_nonoverlapping(self, other) { |
471 | // See <https://github.com/rust-lang/rust/issues/80778> for why we need to stop here. |
472 | panic!("`Cell::swap` on overlapping non-identical `Cell`s" ); |
473 | } |
474 | // SAFETY: This can be risky if called from separate threads, but `Cell` |
475 | // is `!Sync` so this won't happen. This also won't invalidate any |
476 | // pointers since `Cell` makes sure nothing else will be pointing into |
477 | // either of these `Cell`s. We also excluded shenanigans like partially overlapping `Cell`s, |
478 | // so `swap` will just properly copy two full values of type `T` back and forth. |
479 | unsafe { |
480 | mem::swap(&mut *self.value.get(), &mut *other.value.get()); |
481 | } |
482 | } |
483 | |
484 | /// Replaces the contained value with `val`, and returns the old contained value. |
485 | /// |
486 | /// # Examples |
487 | /// |
488 | /// ``` |
489 | /// use std::cell::Cell; |
490 | /// |
491 | /// let cell = Cell::new(5); |
492 | /// assert_eq!(cell.get(), 5); |
493 | /// assert_eq!(cell.replace(10), 5); |
494 | /// assert_eq!(cell.get(), 10); |
495 | /// ``` |
496 | #[inline ] |
497 | #[stable (feature = "move_cell" , since = "1.17.0" )] |
498 | #[rustc_const_unstable (feature = "const_cell" , issue = "131283" )] |
499 | #[rustc_confusables ("swap" )] |
500 | pub const fn replace(&self, val: T) -> T { |
501 | // SAFETY: This can cause data races if called from a separate thread, |
502 | // but `Cell` is `!Sync` so this won't happen. |
503 | mem::replace(unsafe { &mut *self.value.get() }, val) |
504 | } |
505 | |
506 | /// Unwraps the value, consuming the cell. |
507 | /// |
508 | /// # Examples |
509 | /// |
510 | /// ``` |
511 | /// use std::cell::Cell; |
512 | /// |
513 | /// let c = Cell::new(5); |
514 | /// let five = c.into_inner(); |
515 | /// |
516 | /// assert_eq!(five, 5); |
517 | /// ``` |
518 | #[stable (feature = "move_cell" , since = "1.17.0" )] |
519 | #[rustc_const_stable (feature = "const_cell_into_inner" , since = "1.83.0" )] |
520 | #[rustc_allow_const_fn_unstable (const_precise_live_drops)] |
521 | pub const fn into_inner(self) -> T { |
522 | self.value.into_inner() |
523 | } |
524 | } |
525 | |
526 | impl<T: Copy> Cell<T> { |
527 | /// Returns a copy of the contained value. |
528 | /// |
529 | /// # Examples |
530 | /// |
531 | /// ``` |
532 | /// use std::cell::Cell; |
533 | /// |
534 | /// let c = Cell::new(5); |
535 | /// |
536 | /// let five = c.get(); |
537 | /// ``` |
538 | #[inline ] |
539 | #[stable (feature = "rust1" , since = "1.0.0" )] |
540 | #[rustc_const_unstable (feature = "const_cell" , issue = "131283" )] |
541 | pub const fn get(&self) -> T { |
542 | // SAFETY: This can cause data races if called from a separate thread, |
543 | // but `Cell` is `!Sync` so this won't happen. |
544 | unsafe { *self.value.get() } |
545 | } |
546 | |
547 | /// Updates the contained value using a function and returns the new value. |
548 | /// |
549 | /// # Examples |
550 | /// |
551 | /// ``` |
552 | /// #![feature(cell_update)] |
553 | /// |
554 | /// use std::cell::Cell; |
555 | /// |
556 | /// let c = Cell::new(5); |
557 | /// let new = c.update(|x| x + 1); |
558 | /// |
559 | /// assert_eq!(new, 6); |
560 | /// assert_eq!(c.get(), 6); |
561 | /// ``` |
562 | #[inline ] |
563 | #[unstable (feature = "cell_update" , issue = "50186" )] |
564 | pub fn update<F>(&self, f: F) -> T |
565 | where |
566 | F: FnOnce(T) -> T, |
567 | { |
568 | let old = self.get(); |
569 | let new = f(old); |
570 | self.set(new); |
571 | new |
572 | } |
573 | } |
574 | |
575 | impl<T: ?Sized> Cell<T> { |
576 | /// Returns a raw pointer to the underlying data in this cell. |
577 | /// |
578 | /// # Examples |
579 | /// |
580 | /// ``` |
581 | /// use std::cell::Cell; |
582 | /// |
583 | /// let c = Cell::new(5); |
584 | /// |
585 | /// let ptr = c.as_ptr(); |
586 | /// ``` |
587 | #[inline ] |
588 | #[stable (feature = "cell_as_ptr" , since = "1.12.0" )] |
589 | #[rustc_const_stable (feature = "const_cell_as_ptr" , since = "1.32.0" )] |
590 | #[rustc_as_ptr] |
591 | #[rustc_never_returns_null_ptr ] |
592 | pub const fn as_ptr(&self) -> *mut T { |
593 | self.value.get() |
594 | } |
595 | |
596 | /// Returns a mutable reference to the underlying data. |
597 | /// |
598 | /// This call borrows `Cell` mutably (at compile-time) which guarantees |
599 | /// that we possess the only reference. |
600 | /// |
601 | /// However be cautious: this method expects `self` to be mutable, which is |
602 | /// generally not the case when using a `Cell`. If you require interior |
603 | /// mutability by reference, consider using `RefCell` which provides |
604 | /// run-time checked mutable borrows through its [`borrow_mut`] method. |
605 | /// |
606 | /// [`borrow_mut`]: RefCell::borrow_mut() |
607 | /// |
608 | /// # Examples |
609 | /// |
610 | /// ``` |
611 | /// use std::cell::Cell; |
612 | /// |
613 | /// let mut c = Cell::new(5); |
614 | /// *c.get_mut() += 1; |
615 | /// |
616 | /// assert_eq!(c.get(), 6); |
617 | /// ``` |
618 | #[inline ] |
619 | #[stable (feature = "cell_get_mut" , since = "1.11.0" )] |
620 | #[rustc_const_unstable (feature = "const_cell" , issue = "131283" )] |
621 | pub const fn get_mut(&mut self) -> &mut T { |
622 | self.value.get_mut() |
623 | } |
624 | |
625 | /// Returns a `&Cell<T>` from a `&mut T` |
626 | /// |
627 | /// # Examples |
628 | /// |
629 | /// ``` |
630 | /// use std::cell::Cell; |
631 | /// |
632 | /// let slice: &mut [i32] = &mut [1, 2, 3]; |
633 | /// let cell_slice: &Cell<[i32]> = Cell::from_mut(slice); |
634 | /// let slice_cell: &[Cell<i32>] = cell_slice.as_slice_of_cells(); |
635 | /// |
636 | /// assert_eq!(slice_cell.len(), 3); |
637 | /// ``` |
638 | #[inline ] |
639 | #[stable (feature = "as_cell" , since = "1.37.0" )] |
640 | #[rustc_const_unstable (feature = "const_cell" , issue = "131283" )] |
641 | pub const fn from_mut(t: &mut T) -> &Cell<T> { |
642 | // SAFETY: `&mut` ensures unique access. |
643 | unsafe { &*(t as *mut T as *const Cell<T>) } |
644 | } |
645 | } |
646 | |
647 | impl<T: Default> Cell<T> { |
648 | /// Takes the value of the cell, leaving `Default::default()` in its place. |
649 | /// |
650 | /// # Examples |
651 | /// |
652 | /// ``` |
653 | /// use std::cell::Cell; |
654 | /// |
655 | /// let c = Cell::new(5); |
656 | /// let five = c.take(); |
657 | /// |
658 | /// assert_eq!(five, 5); |
659 | /// assert_eq!(c.into_inner(), 0); |
660 | /// ``` |
661 | #[stable (feature = "move_cell" , since = "1.17.0" )] |
662 | pub fn take(&self) -> T { |
663 | self.replace(val:Default::default()) |
664 | } |
665 | } |
666 | |
667 | #[unstable (feature = "coerce_unsized" , issue = "18598" )] |
668 | impl<T: CoerceUnsized<U>, U> CoerceUnsized<Cell<U>> for Cell<T> {} |
669 | |
670 | // Allow types that wrap `Cell` to also implement `DispatchFromDyn` |
671 | // and become dyn-compatible method receivers. |
672 | // Note that currently `Cell` itself cannot be a method receiver |
673 | // because it does not implement Deref. |
674 | // In other words: |
675 | // `self: Cell<&Self>` won't work |
676 | // `self: CellWrapper<Self>` becomes possible |
677 | #[unstable (feature = "dispatch_from_dyn" , issue = "none" )] |
678 | impl<T: DispatchFromDyn<U>, U> DispatchFromDyn<Cell<U>> for Cell<T> {} |
679 | |
680 | #[unstable (feature = "pointer_like_trait" , issue = "none" )] |
681 | impl<T: PointerLike> PointerLike for Cell<T> {} |
682 | |
683 | impl<T> Cell<[T]> { |
684 | /// Returns a `&[Cell<T>]` from a `&Cell<[T]>` |
685 | /// |
686 | /// # Examples |
687 | /// |
688 | /// ``` |
689 | /// use std::cell::Cell; |
690 | /// |
691 | /// let slice: &mut [i32] = &mut [1, 2, 3]; |
692 | /// let cell_slice: &Cell<[i32]> = Cell::from_mut(slice); |
693 | /// let slice_cell: &[Cell<i32>] = cell_slice.as_slice_of_cells(); |
694 | /// |
695 | /// assert_eq!(slice_cell.len(), 3); |
696 | /// ``` |
697 | #[stable (feature = "as_cell" , since = "1.37.0" )] |
698 | #[rustc_const_unstable (feature = "const_cell" , issue = "131283" )] |
699 | pub const fn as_slice_of_cells(&self) -> &[Cell<T>] { |
700 | // SAFETY: `Cell<T>` has the same memory layout as `T`. |
701 | unsafe { &*(self as *const Cell<[T]> as *const [Cell<T>]) } |
702 | } |
703 | } |
704 | |
705 | impl<T, const N: usize> Cell<[T; N]> { |
706 | /// Returns a `&[Cell<T>; N]` from a `&Cell<[T; N]>` |
707 | /// |
708 | /// # Examples |
709 | /// |
710 | /// ``` |
711 | /// #![feature(as_array_of_cells)] |
712 | /// use std::cell::Cell; |
713 | /// |
714 | /// let mut array: [i32; 3] = [1, 2, 3]; |
715 | /// let cell_array: &Cell<[i32; 3]> = Cell::from_mut(&mut array); |
716 | /// let array_cell: &[Cell<i32>; 3] = cell_array.as_array_of_cells(); |
717 | /// ``` |
718 | #[unstable (feature = "as_array_of_cells" , issue = "88248" )] |
719 | pub const fn as_array_of_cells(&self) -> &[Cell<T>; N] { |
720 | // SAFETY: `Cell<T>` has the same memory layout as `T`. |
721 | unsafe { &*(self as *const Cell<[T; N]> as *const [Cell<T>; N]) } |
722 | } |
723 | } |
724 | |
725 | /// A mutable memory location with dynamically checked borrow rules |
726 | /// |
727 | /// See the [module-level documentation](self) for more. |
728 | #[rustc_diagnostic_item = "RefCell" ] |
729 | #[stable (feature = "rust1" , since = "1.0.0" )] |
730 | pub struct RefCell<T: ?Sized> { |
731 | borrow: Cell<BorrowFlag>, |
732 | // Stores the location of the earliest currently active borrow. |
733 | // This gets updated whenever we go from having zero borrows |
734 | // to having a single borrow. When a borrow occurs, this gets included |
735 | // in the generated `BorrowError`/`BorrowMutError` |
736 | #[cfg (feature = "debug_refcell" )] |
737 | borrowed_at: Cell<Option<&'static crate::panic::Location<'static>>>, |
738 | value: UnsafeCell<T>, |
739 | } |
740 | |
741 | /// An error returned by [`RefCell::try_borrow`]. |
742 | #[stable (feature = "try_borrow" , since = "1.13.0" )] |
743 | #[non_exhaustive ] |
744 | pub struct BorrowError { |
745 | #[cfg (feature = "debug_refcell" )] |
746 | location: &'static crate::panic::Location<'static>, |
747 | } |
748 | |
749 | #[stable (feature = "try_borrow" , since = "1.13.0" )] |
750 | impl Debug for BorrowError { |
751 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
752 | let mut builder: DebugStruct<'_, '_> = f.debug_struct(name:"BorrowError" ); |
753 | |
754 | #[cfg (feature = "debug_refcell" )] |
755 | builder.field("location" , self.location); |
756 | |
757 | builder.finish() |
758 | } |
759 | } |
760 | |
761 | #[stable (feature = "try_borrow" , since = "1.13.0" )] |
762 | impl Display for BorrowError { |
763 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
764 | Display::fmt(self:"already mutably borrowed" , f) |
765 | } |
766 | } |
767 | |
768 | /// An error returned by [`RefCell::try_borrow_mut`]. |
769 | #[stable (feature = "try_borrow" , since = "1.13.0" )] |
770 | #[non_exhaustive ] |
771 | pub struct BorrowMutError { |
772 | #[cfg (feature = "debug_refcell" )] |
773 | location: &'static crate::panic::Location<'static>, |
774 | } |
775 | |
776 | #[stable (feature = "try_borrow" , since = "1.13.0" )] |
777 | impl Debug for BorrowMutError { |
778 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
779 | let mut builder: DebugStruct<'_, '_> = f.debug_struct(name:"BorrowMutError" ); |
780 | |
781 | #[cfg (feature = "debug_refcell" )] |
782 | builder.field("location" , self.location); |
783 | |
784 | builder.finish() |
785 | } |
786 | } |
787 | |
788 | #[stable (feature = "try_borrow" , since = "1.13.0" )] |
789 | impl Display for BorrowMutError { |
790 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
791 | Display::fmt(self:"already borrowed" , f) |
792 | } |
793 | } |
794 | |
795 | // This ensures the panicking code is outlined from `borrow_mut` for `RefCell`. |
796 | #[cfg_attr (not(feature = "panic_immediate_abort" ), inline(never))] |
797 | #[track_caller ] |
798 | #[cold ] |
799 | fn panic_already_borrowed(err: BorrowMutError) -> ! { |
800 | panic!("already borrowed: {:?}" , err) |
801 | } |
802 | |
803 | // This ensures the panicking code is outlined from `borrow` for `RefCell`. |
804 | #[cfg_attr (not(feature = "panic_immediate_abort" ), inline(never))] |
805 | #[track_caller ] |
806 | #[cold ] |
807 | fn panic_already_mutably_borrowed(err: BorrowError) -> ! { |
808 | panic!("already mutably borrowed: {:?}" , err) |
809 | } |
810 | |
811 | // Positive values represent the number of `Ref` active. Negative values |
812 | // represent the number of `RefMut` active. Multiple `RefMut`s can only be |
813 | // active at a time if they refer to distinct, nonoverlapping components of a |
814 | // `RefCell` (e.g., different ranges of a slice). |
815 | // |
816 | // `Ref` and `RefMut` are both two words in size, and so there will likely never |
817 | // be enough `Ref`s or `RefMut`s in existence to overflow half of the `usize` |
818 | // range. Thus, a `BorrowFlag` will probably never overflow or underflow. |
819 | // However, this is not a guarantee, as a pathological program could repeatedly |
820 | // create and then mem::forget `Ref`s or `RefMut`s. Thus, all code must |
821 | // explicitly check for overflow and underflow in order to avoid unsafety, or at |
822 | // least behave correctly in the event that overflow or underflow happens (e.g., |
823 | // see BorrowRef::new). |
824 | type BorrowFlag = isize; |
825 | const UNUSED: BorrowFlag = 0; |
826 | |
827 | #[inline (always)] |
828 | fn is_writing(x: BorrowFlag) -> bool { |
829 | x < UNUSED |
830 | } |
831 | |
832 | #[inline (always)] |
833 | fn is_reading(x: BorrowFlag) -> bool { |
834 | x > UNUSED |
835 | } |
836 | |
837 | impl<T> RefCell<T> { |
838 | /// Creates a new `RefCell` containing `value`. |
839 | /// |
840 | /// # Examples |
841 | /// |
842 | /// ``` |
843 | /// use std::cell::RefCell; |
844 | /// |
845 | /// let c = RefCell::new(5); |
846 | /// ``` |
847 | #[stable (feature = "rust1" , since = "1.0.0" )] |
848 | #[rustc_const_stable (feature = "const_refcell_new" , since = "1.24.0" )] |
849 | #[inline ] |
850 | pub const fn new(value: T) -> RefCell<T> { |
851 | RefCell { |
852 | value: UnsafeCell::new(value), |
853 | borrow: Cell::new(UNUSED), |
854 | #[cfg (feature = "debug_refcell" )] |
855 | borrowed_at: Cell::new(None), |
856 | } |
857 | } |
858 | |
859 | /// Consumes the `RefCell`, returning the wrapped value. |
860 | /// |
861 | /// # Examples |
862 | /// |
863 | /// ``` |
864 | /// use std::cell::RefCell; |
865 | /// |
866 | /// let c = RefCell::new(5); |
867 | /// |
868 | /// let five = c.into_inner(); |
869 | /// ``` |
870 | #[stable (feature = "rust1" , since = "1.0.0" )] |
871 | #[rustc_const_stable (feature = "const_cell_into_inner" , since = "1.83.0" )] |
872 | #[rustc_allow_const_fn_unstable (const_precise_live_drops)] |
873 | #[inline ] |
874 | pub const fn into_inner(self) -> T { |
875 | // Since this function takes `self` (the `RefCell`) by value, the |
876 | // compiler statically verifies that it is not currently borrowed. |
877 | self.value.into_inner() |
878 | } |
879 | |
880 | /// Replaces the wrapped value with a new one, returning the old value, |
881 | /// without deinitializing either one. |
882 | /// |
883 | /// This function corresponds to [`std::mem::replace`](../mem/fn.replace.html). |
884 | /// |
885 | /// # Panics |
886 | /// |
887 | /// Panics if the value is currently borrowed. |
888 | /// |
889 | /// # Examples |
890 | /// |
891 | /// ``` |
892 | /// use std::cell::RefCell; |
893 | /// let cell = RefCell::new(5); |
894 | /// let old_value = cell.replace(6); |
895 | /// assert_eq!(old_value, 5); |
896 | /// assert_eq!(cell, RefCell::new(6)); |
897 | /// ``` |
898 | #[inline ] |
899 | #[stable (feature = "refcell_replace" , since = "1.24.0" )] |
900 | #[track_caller ] |
901 | #[rustc_confusables ("swap" )] |
902 | pub fn replace(&self, t: T) -> T { |
903 | mem::replace(&mut *self.borrow_mut(), t) |
904 | } |
905 | |
906 | /// Replaces the wrapped value with a new one computed from `f`, returning |
907 | /// the old value, without deinitializing either one. |
908 | /// |
909 | /// # Panics |
910 | /// |
911 | /// Panics if the value is currently borrowed. |
912 | /// |
913 | /// # Examples |
914 | /// |
915 | /// ``` |
916 | /// use std::cell::RefCell; |
917 | /// let cell = RefCell::new(5); |
918 | /// let old_value = cell.replace_with(|&mut old| old + 1); |
919 | /// assert_eq!(old_value, 5); |
920 | /// assert_eq!(cell, RefCell::new(6)); |
921 | /// ``` |
922 | #[inline ] |
923 | #[stable (feature = "refcell_replace_swap" , since = "1.35.0" )] |
924 | #[track_caller ] |
925 | pub fn replace_with<F: FnOnce(&mut T) -> T>(&self, f: F) -> T { |
926 | let mut_borrow = &mut *self.borrow_mut(); |
927 | let replacement = f(mut_borrow); |
928 | mem::replace(mut_borrow, replacement) |
929 | } |
930 | |
931 | /// Swaps the wrapped value of `self` with the wrapped value of `other`, |
932 | /// without deinitializing either one. |
933 | /// |
934 | /// This function corresponds to [`std::mem::swap`](../mem/fn.swap.html). |
935 | /// |
936 | /// # Panics |
937 | /// |
938 | /// Panics if the value in either `RefCell` is currently borrowed, or |
939 | /// if `self` and `other` point to the same `RefCell`. |
940 | /// |
941 | /// # Examples |
942 | /// |
943 | /// ``` |
944 | /// use std::cell::RefCell; |
945 | /// let c = RefCell::new(5); |
946 | /// let d = RefCell::new(6); |
947 | /// c.swap(&d); |
948 | /// assert_eq!(c, RefCell::new(6)); |
949 | /// assert_eq!(d, RefCell::new(5)); |
950 | /// ``` |
951 | #[inline ] |
952 | #[stable (feature = "refcell_swap" , since = "1.24.0" )] |
953 | pub fn swap(&self, other: &Self) { |
954 | mem::swap(&mut *self.borrow_mut(), &mut *other.borrow_mut()) |
955 | } |
956 | } |
957 | |
958 | impl<T: ?Sized> RefCell<T> { |
959 | /// Immutably borrows the wrapped value. |
960 | /// |
961 | /// The borrow lasts until the returned `Ref` exits scope. Multiple |
962 | /// immutable borrows can be taken out at the same time. |
963 | /// |
964 | /// # Panics |
965 | /// |
966 | /// Panics if the value is currently mutably borrowed. For a non-panicking variant, use |
967 | /// [`try_borrow`](#method.try_borrow). |
968 | /// |
969 | /// # Examples |
970 | /// |
971 | /// ``` |
972 | /// use std::cell::RefCell; |
973 | /// |
974 | /// let c = RefCell::new(5); |
975 | /// |
976 | /// let borrowed_five = c.borrow(); |
977 | /// let borrowed_five2 = c.borrow(); |
978 | /// ``` |
979 | /// |
980 | /// An example of panic: |
981 | /// |
982 | /// ```should_panic |
983 | /// use std::cell::RefCell; |
984 | /// |
985 | /// let c = RefCell::new(5); |
986 | /// |
987 | /// let m = c.borrow_mut(); |
988 | /// let b = c.borrow(); // this causes a panic |
989 | /// ``` |
990 | #[stable (feature = "rust1" , since = "1.0.0" )] |
991 | #[inline ] |
992 | #[track_caller ] |
993 | pub fn borrow(&self) -> Ref<'_, T> { |
994 | match self.try_borrow() { |
995 | Ok(b) => b, |
996 | Err(err) => panic_already_mutably_borrowed(err), |
997 | } |
998 | } |
999 | |
1000 | /// Immutably borrows the wrapped value, returning an error if the value is currently mutably |
1001 | /// borrowed. |
1002 | /// |
1003 | /// The borrow lasts until the returned `Ref` exits scope. Multiple immutable borrows can be |
1004 | /// taken out at the same time. |
1005 | /// |
1006 | /// This is the non-panicking variant of [`borrow`](#method.borrow). |
1007 | /// |
1008 | /// # Examples |
1009 | /// |
1010 | /// ``` |
1011 | /// use std::cell::RefCell; |
1012 | /// |
1013 | /// let c = RefCell::new(5); |
1014 | /// |
1015 | /// { |
1016 | /// let m = c.borrow_mut(); |
1017 | /// assert!(c.try_borrow().is_err()); |
1018 | /// } |
1019 | /// |
1020 | /// { |
1021 | /// let m = c.borrow(); |
1022 | /// assert!(c.try_borrow().is_ok()); |
1023 | /// } |
1024 | /// ``` |
1025 | #[stable (feature = "try_borrow" , since = "1.13.0" )] |
1026 | #[inline ] |
1027 | #[cfg_attr (feature = "debug_refcell" , track_caller)] |
1028 | pub fn try_borrow(&self) -> Result<Ref<'_, T>, BorrowError> { |
1029 | match BorrowRef::new(&self.borrow) { |
1030 | Some(b) => { |
1031 | #[cfg (feature = "debug_refcell" )] |
1032 | { |
1033 | // `borrowed_at` is always the *first* active borrow |
1034 | if b.borrow.get() == 1 { |
1035 | self.borrowed_at.set(Some(crate::panic::Location::caller())); |
1036 | } |
1037 | } |
1038 | |
1039 | // SAFETY: `BorrowRef` ensures that there is only immutable access |
1040 | // to the value while borrowed. |
1041 | let value = unsafe { NonNull::new_unchecked(self.value.get()) }; |
1042 | Ok(Ref { value, borrow: b }) |
1043 | } |
1044 | None => Err(BorrowError { |
1045 | // If a borrow occurred, then we must already have an outstanding borrow, |
1046 | // so `borrowed_at` will be `Some` |
1047 | #[cfg (feature = "debug_refcell" )] |
1048 | location: self.borrowed_at.get().unwrap(), |
1049 | }), |
1050 | } |
1051 | } |
1052 | |
1053 | /// Mutably borrows the wrapped value. |
1054 | /// |
1055 | /// The borrow lasts until the returned `RefMut` or all `RefMut`s derived |
1056 | /// from it exit scope. The value cannot be borrowed while this borrow is |
1057 | /// active. |
1058 | /// |
1059 | /// # Panics |
1060 | /// |
1061 | /// Panics if the value is currently borrowed. For a non-panicking variant, use |
1062 | /// [`try_borrow_mut`](#method.try_borrow_mut). |
1063 | /// |
1064 | /// # Examples |
1065 | /// |
1066 | /// ``` |
1067 | /// use std::cell::RefCell; |
1068 | /// |
1069 | /// let c = RefCell::new("hello" .to_owned()); |
1070 | /// |
1071 | /// *c.borrow_mut() = "bonjour" .to_owned(); |
1072 | /// |
1073 | /// assert_eq!(&*c.borrow(), "bonjour" ); |
1074 | /// ``` |
1075 | /// |
1076 | /// An example of panic: |
1077 | /// |
1078 | /// ```should_panic |
1079 | /// use std::cell::RefCell; |
1080 | /// |
1081 | /// let c = RefCell::new(5); |
1082 | /// let m = c.borrow(); |
1083 | /// |
1084 | /// let b = c.borrow_mut(); // this causes a panic |
1085 | /// ``` |
1086 | #[stable (feature = "rust1" , since = "1.0.0" )] |
1087 | #[inline ] |
1088 | #[track_caller ] |
1089 | pub fn borrow_mut(&self) -> RefMut<'_, T> { |
1090 | match self.try_borrow_mut() { |
1091 | Ok(b) => b, |
1092 | Err(err) => panic_already_borrowed(err), |
1093 | } |
1094 | } |
1095 | |
1096 | /// Mutably borrows the wrapped value, returning an error if the value is currently borrowed. |
1097 | /// |
1098 | /// The borrow lasts until the returned `RefMut` or all `RefMut`s derived |
1099 | /// from it exit scope. The value cannot be borrowed while this borrow is |
1100 | /// active. |
1101 | /// |
1102 | /// This is the non-panicking variant of [`borrow_mut`](#method.borrow_mut). |
1103 | /// |
1104 | /// # Examples |
1105 | /// |
1106 | /// ``` |
1107 | /// use std::cell::RefCell; |
1108 | /// |
1109 | /// let c = RefCell::new(5); |
1110 | /// |
1111 | /// { |
1112 | /// let m = c.borrow(); |
1113 | /// assert!(c.try_borrow_mut().is_err()); |
1114 | /// } |
1115 | /// |
1116 | /// assert!(c.try_borrow_mut().is_ok()); |
1117 | /// ``` |
1118 | #[stable (feature = "try_borrow" , since = "1.13.0" )] |
1119 | #[inline ] |
1120 | #[cfg_attr (feature = "debug_refcell" , track_caller)] |
1121 | pub fn try_borrow_mut(&self) -> Result<RefMut<'_, T>, BorrowMutError> { |
1122 | match BorrowRefMut::new(&self.borrow) { |
1123 | Some(b) => { |
1124 | #[cfg (feature = "debug_refcell" )] |
1125 | { |
1126 | self.borrowed_at.set(Some(crate::panic::Location::caller())); |
1127 | } |
1128 | |
1129 | // SAFETY: `BorrowRefMut` guarantees unique access. |
1130 | let value = unsafe { NonNull::new_unchecked(self.value.get()) }; |
1131 | Ok(RefMut { value, borrow: b, marker: PhantomData }) |
1132 | } |
1133 | None => Err(BorrowMutError { |
1134 | // If a borrow occurred, then we must already have an outstanding borrow, |
1135 | // so `borrowed_at` will be `Some` |
1136 | #[cfg (feature = "debug_refcell" )] |
1137 | location: self.borrowed_at.get().unwrap(), |
1138 | }), |
1139 | } |
1140 | } |
1141 | |
1142 | /// Returns a raw pointer to the underlying data in this cell. |
1143 | /// |
1144 | /// # Examples |
1145 | /// |
1146 | /// ``` |
1147 | /// use std::cell::RefCell; |
1148 | /// |
1149 | /// let c = RefCell::new(5); |
1150 | /// |
1151 | /// let ptr = c.as_ptr(); |
1152 | /// ``` |
1153 | #[inline ] |
1154 | #[stable (feature = "cell_as_ptr" , since = "1.12.0" )] |
1155 | #[rustc_as_ptr] |
1156 | #[rustc_never_returns_null_ptr ] |
1157 | pub fn as_ptr(&self) -> *mut T { |
1158 | self.value.get() |
1159 | } |
1160 | |
1161 | /// Returns a mutable reference to the underlying data. |
1162 | /// |
1163 | /// Since this method borrows `RefCell` mutably, it is statically guaranteed |
1164 | /// that no borrows to the underlying data exist. The dynamic checks inherent |
1165 | /// in [`borrow_mut`] and most other methods of `RefCell` are therefore |
1166 | /// unnecessary. |
1167 | /// |
1168 | /// This method can only be called if `RefCell` can be mutably borrowed, |
1169 | /// which in general is only the case directly after the `RefCell` has |
1170 | /// been created. In these situations, skipping the aforementioned dynamic |
1171 | /// borrowing checks may yield better ergonomics and runtime-performance. |
1172 | /// |
1173 | /// In most situations where `RefCell` is used, it can't be borrowed mutably. |
1174 | /// Use [`borrow_mut`] to get mutable access to the underlying data then. |
1175 | /// |
1176 | /// [`borrow_mut`]: RefCell::borrow_mut() |
1177 | /// |
1178 | /// # Examples |
1179 | /// |
1180 | /// ``` |
1181 | /// use std::cell::RefCell; |
1182 | /// |
1183 | /// let mut c = RefCell::new(5); |
1184 | /// *c.get_mut() += 1; |
1185 | /// |
1186 | /// assert_eq!(c, RefCell::new(6)); |
1187 | /// ``` |
1188 | #[inline ] |
1189 | #[stable (feature = "cell_get_mut" , since = "1.11.0" )] |
1190 | pub fn get_mut(&mut self) -> &mut T { |
1191 | self.value.get_mut() |
1192 | } |
1193 | |
1194 | /// Undo the effect of leaked guards on the borrow state of the `RefCell`. |
1195 | /// |
1196 | /// This call is similar to [`get_mut`] but more specialized. It borrows `RefCell` mutably to |
1197 | /// ensure no borrows exist and then resets the state tracking shared borrows. This is relevant |
1198 | /// if some `Ref` or `RefMut` borrows have been leaked. |
1199 | /// |
1200 | /// [`get_mut`]: RefCell::get_mut() |
1201 | /// |
1202 | /// # Examples |
1203 | /// |
1204 | /// ``` |
1205 | /// #![feature(cell_leak)] |
1206 | /// use std::cell::RefCell; |
1207 | /// |
1208 | /// let mut c = RefCell::new(0); |
1209 | /// std::mem::forget(c.borrow_mut()); |
1210 | /// |
1211 | /// assert!(c.try_borrow().is_err()); |
1212 | /// c.undo_leak(); |
1213 | /// assert!(c.try_borrow().is_ok()); |
1214 | /// ``` |
1215 | #[unstable (feature = "cell_leak" , issue = "69099" )] |
1216 | pub fn undo_leak(&mut self) -> &mut T { |
1217 | *self.borrow.get_mut() = UNUSED; |
1218 | self.get_mut() |
1219 | } |
1220 | |
1221 | /// Immutably borrows the wrapped value, returning an error if the value is |
1222 | /// currently mutably borrowed. |
1223 | /// |
1224 | /// # Safety |
1225 | /// |
1226 | /// Unlike `RefCell::borrow`, this method is unsafe because it does not |
1227 | /// return a `Ref`, thus leaving the borrow flag untouched. Mutably |
1228 | /// borrowing the `RefCell` while the reference returned by this method |
1229 | /// is alive is undefined behavior. |
1230 | /// |
1231 | /// # Examples |
1232 | /// |
1233 | /// ``` |
1234 | /// use std::cell::RefCell; |
1235 | /// |
1236 | /// let c = RefCell::new(5); |
1237 | /// |
1238 | /// { |
1239 | /// let m = c.borrow_mut(); |
1240 | /// assert!(unsafe { c.try_borrow_unguarded() }.is_err()); |
1241 | /// } |
1242 | /// |
1243 | /// { |
1244 | /// let m = c.borrow(); |
1245 | /// assert!(unsafe { c.try_borrow_unguarded() }.is_ok()); |
1246 | /// } |
1247 | /// ``` |
1248 | #[stable (feature = "borrow_state" , since = "1.37.0" )] |
1249 | #[inline ] |
1250 | pub unsafe fn try_borrow_unguarded(&self) -> Result<&T, BorrowError> { |
1251 | if !is_writing(self.borrow.get()) { |
1252 | // SAFETY: We check that nobody is actively writing now, but it is |
1253 | // the caller's responsibility to ensure that nobody writes until |
1254 | // the returned reference is no longer in use. |
1255 | // Also, `self.value.get()` refers to the value owned by `self` |
1256 | // and is thus guaranteed to be valid for the lifetime of `self`. |
1257 | Ok(unsafe { &*self.value.get() }) |
1258 | } else { |
1259 | Err(BorrowError { |
1260 | // If a borrow occurred, then we must already have an outstanding borrow, |
1261 | // so `borrowed_at` will be `Some` |
1262 | #[cfg (feature = "debug_refcell" )] |
1263 | location: self.borrowed_at.get().unwrap(), |
1264 | }) |
1265 | } |
1266 | } |
1267 | } |
1268 | |
1269 | impl<T: Default> RefCell<T> { |
1270 | /// Takes the wrapped value, leaving `Default::default()` in its place. |
1271 | /// |
1272 | /// # Panics |
1273 | /// |
1274 | /// Panics if the value is currently borrowed. |
1275 | /// |
1276 | /// # Examples |
1277 | /// |
1278 | /// ``` |
1279 | /// use std::cell::RefCell; |
1280 | /// |
1281 | /// let c = RefCell::new(5); |
1282 | /// let five = c.take(); |
1283 | /// |
1284 | /// assert_eq!(five, 5); |
1285 | /// assert_eq!(c.into_inner(), 0); |
1286 | /// ``` |
1287 | #[stable (feature = "refcell_take" , since = "1.50.0" )] |
1288 | pub fn take(&self) -> T { |
1289 | self.replace(Default::default()) |
1290 | } |
1291 | } |
1292 | |
1293 | #[stable (feature = "rust1" , since = "1.0.0" )] |
1294 | unsafe impl<T: ?Sized> Send for RefCell<T> where T: Send {} |
1295 | |
1296 | #[stable (feature = "rust1" , since = "1.0.0" )] |
1297 | impl<T: ?Sized> !Sync for RefCell<T> {} |
1298 | |
1299 | #[stable (feature = "rust1" , since = "1.0.0" )] |
1300 | impl<T: Clone> Clone for RefCell<T> { |
1301 | /// # Panics |
1302 | /// |
1303 | /// Panics if the value is currently mutably borrowed. |
1304 | #[inline ] |
1305 | #[track_caller ] |
1306 | fn clone(&self) -> RefCell<T> { |
1307 | RefCell::new(self.borrow().clone()) |
1308 | } |
1309 | |
1310 | /// # Panics |
1311 | /// |
1312 | /// Panics if `source` is currently mutably borrowed. |
1313 | #[inline ] |
1314 | #[track_caller ] |
1315 | fn clone_from(&mut self, source: &Self) { |
1316 | self.get_mut().clone_from(&source.borrow()) |
1317 | } |
1318 | } |
1319 | |
1320 | #[stable (feature = "rust1" , since = "1.0.0" )] |
1321 | impl<T: Default> Default for RefCell<T> { |
1322 | /// Creates a `RefCell<T>`, with the `Default` value for T. |
1323 | #[inline ] |
1324 | fn default() -> RefCell<T> { |
1325 | RefCell::new(Default::default()) |
1326 | } |
1327 | } |
1328 | |
1329 | #[stable (feature = "rust1" , since = "1.0.0" )] |
1330 | impl<T: ?Sized + PartialEq> PartialEq for RefCell<T> { |
1331 | /// # Panics |
1332 | /// |
1333 | /// Panics if the value in either `RefCell` is currently mutably borrowed. |
1334 | #[inline ] |
1335 | fn eq(&self, other: &RefCell<T>) -> bool { |
1336 | *self.borrow() == *other.borrow() |
1337 | } |
1338 | } |
1339 | |
1340 | #[stable (feature = "cell_eq" , since = "1.2.0" )] |
1341 | impl<T: ?Sized + Eq> Eq for RefCell<T> {} |
1342 | |
1343 | #[stable (feature = "cell_ord" , since = "1.10.0" )] |
1344 | impl<T: ?Sized + PartialOrd> PartialOrd for RefCell<T> { |
1345 | /// # Panics |
1346 | /// |
1347 | /// Panics if the value in either `RefCell` is currently mutably borrowed. |
1348 | #[inline ] |
1349 | fn partial_cmp(&self, other: &RefCell<T>) -> Option<Ordering> { |
1350 | self.borrow().partial_cmp(&*other.borrow()) |
1351 | } |
1352 | |
1353 | /// # Panics |
1354 | /// |
1355 | /// Panics if the value in either `RefCell` is currently mutably borrowed. |
1356 | #[inline ] |
1357 | fn lt(&self, other: &RefCell<T>) -> bool { |
1358 | *self.borrow() < *other.borrow() |
1359 | } |
1360 | |
1361 | /// # Panics |
1362 | /// |
1363 | /// Panics if the value in either `RefCell` is currently mutably borrowed. |
1364 | #[inline ] |
1365 | fn le(&self, other: &RefCell<T>) -> bool { |
1366 | *self.borrow() <= *other.borrow() |
1367 | } |
1368 | |
1369 | /// # Panics |
1370 | /// |
1371 | /// Panics if the value in either `RefCell` is currently mutably borrowed. |
1372 | #[inline ] |
1373 | fn gt(&self, other: &RefCell<T>) -> bool { |
1374 | *self.borrow() > *other.borrow() |
1375 | } |
1376 | |
1377 | /// # Panics |
1378 | /// |
1379 | /// Panics if the value in either `RefCell` is currently mutably borrowed. |
1380 | #[inline ] |
1381 | fn ge(&self, other: &RefCell<T>) -> bool { |
1382 | *self.borrow() >= *other.borrow() |
1383 | } |
1384 | } |
1385 | |
1386 | #[stable (feature = "cell_ord" , since = "1.10.0" )] |
1387 | impl<T: ?Sized + Ord> Ord for RefCell<T> { |
1388 | /// # Panics |
1389 | /// |
1390 | /// Panics if the value in either `RefCell` is currently mutably borrowed. |
1391 | #[inline ] |
1392 | fn cmp(&self, other: &RefCell<T>) -> Ordering { |
1393 | self.borrow().cmp(&*other.borrow()) |
1394 | } |
1395 | } |
1396 | |
1397 | #[stable (feature = "cell_from" , since = "1.12.0" )] |
1398 | impl<T> From<T> for RefCell<T> { |
1399 | /// Creates a new `RefCell<T>` containing the given value. |
1400 | fn from(t: T) -> RefCell<T> { |
1401 | RefCell::new(t) |
1402 | } |
1403 | } |
1404 | |
1405 | #[unstable (feature = "coerce_unsized" , issue = "18598" )] |
1406 | impl<T: CoerceUnsized<U>, U> CoerceUnsized<RefCell<U>> for RefCell<T> {} |
1407 | |
1408 | struct BorrowRef<'b> { |
1409 | borrow: &'b Cell<BorrowFlag>, |
1410 | } |
1411 | |
1412 | impl<'b> BorrowRef<'b> { |
1413 | #[inline ] |
1414 | fn new(borrow: &'b Cell<BorrowFlag>) -> Option<BorrowRef<'b>> { |
1415 | let b: isize = borrow.get().wrapping_add(1); |
1416 | if !is_reading(b) { |
1417 | // Incrementing borrow can result in a non-reading value (<= 0) in these cases: |
1418 | // 1. It was < 0, i.e. there are writing borrows, so we can't allow a read borrow |
1419 | // due to Rust's reference aliasing rules |
1420 | // 2. It was isize::MAX (the max amount of reading borrows) and it overflowed |
1421 | // into isize::MIN (the max amount of writing borrows) so we can't allow |
1422 | // an additional read borrow because isize can't represent so many read borrows |
1423 | // (this can only happen if you mem::forget more than a small constant amount of |
1424 | // `Ref`s, which is not good practice) |
1425 | None |
1426 | } else { |
1427 | // Incrementing borrow can result in a reading value (> 0) in these cases: |
1428 | // 1. It was = 0, i.e. it wasn't borrowed, and we are taking the first read borrow |
1429 | // 2. It was > 0 and < isize::MAX, i.e. there were read borrows, and isize |
1430 | // is large enough to represent having one more read borrow |
1431 | borrow.set(val:b); |
1432 | Some(BorrowRef { borrow }) |
1433 | } |
1434 | } |
1435 | } |
1436 | |
1437 | impl Drop for BorrowRef<'_> { |
1438 | #[inline ] |
1439 | fn drop(&mut self) { |
1440 | let borrow: isize = self.borrow.get(); |
1441 | debug_assert!(is_reading(borrow)); |
1442 | self.borrow.set(val:borrow - 1); |
1443 | } |
1444 | } |
1445 | |
1446 | impl Clone for BorrowRef<'_> { |
1447 | #[inline ] |
1448 | fn clone(&self) -> Self { |
1449 | // Since this Ref exists, we know the borrow flag |
1450 | // is a reading borrow. |
1451 | let borrow: isize = self.borrow.get(); |
1452 | debug_assert!(is_reading(borrow)); |
1453 | // Prevent the borrow counter from overflowing into |
1454 | // a writing borrow. |
1455 | assert!(borrow != BorrowFlag::MAX); |
1456 | self.borrow.set(val:borrow + 1); |
1457 | BorrowRef { borrow: self.borrow } |
1458 | } |
1459 | } |
1460 | |
1461 | /// Wraps a borrowed reference to a value in a `RefCell` box. |
1462 | /// A wrapper type for an immutably borrowed value from a `RefCell<T>`. |
1463 | /// |
1464 | /// See the [module-level documentation](self) for more. |
1465 | #[stable (feature = "rust1" , since = "1.0.0" )] |
1466 | #[must_not_suspend = "holding a Ref across suspend points can cause BorrowErrors" ] |
1467 | #[rustc_diagnostic_item = "RefCellRef" ] |
1468 | pub struct Ref<'b, T: ?Sized + 'b> { |
1469 | // NB: we use a pointer instead of `&'b T` to avoid `noalias` violations, because a |
1470 | // `Ref` argument doesn't hold immutability for its whole scope, only until it drops. |
1471 | // `NonNull` is also covariant over `T`, just like we would have with `&T`. |
1472 | value: NonNull<T>, |
1473 | borrow: BorrowRef<'b>, |
1474 | } |
1475 | |
1476 | #[stable (feature = "rust1" , since = "1.0.0" )] |
1477 | impl<T: ?Sized> Deref for Ref<'_, T> { |
1478 | type Target = T; |
1479 | |
1480 | #[inline ] |
1481 | fn deref(&self) -> &T { |
1482 | // SAFETY: the value is accessible as long as we hold our borrow. |
1483 | unsafe { self.value.as_ref() } |
1484 | } |
1485 | } |
1486 | |
1487 | #[unstable (feature = "deref_pure_trait" , issue = "87121" )] |
1488 | unsafe impl<T: ?Sized> DerefPure for Ref<'_, T> {} |
1489 | |
1490 | impl<'b, T: ?Sized> Ref<'b, T> { |
1491 | /// Copies a `Ref`. |
1492 | /// |
1493 | /// The `RefCell` is already immutably borrowed, so this cannot fail. |
1494 | /// |
1495 | /// This is an associated function that needs to be used as |
1496 | /// `Ref::clone(...)`. A `Clone` implementation or a method would interfere |
1497 | /// with the widespread use of `r.borrow().clone()` to clone the contents of |
1498 | /// a `RefCell`. |
1499 | #[stable (feature = "cell_extras" , since = "1.15.0" )] |
1500 | #[must_use ] |
1501 | #[inline ] |
1502 | pub fn clone(orig: &Ref<'b, T>) -> Ref<'b, T> { |
1503 | Ref { value: orig.value, borrow: orig.borrow.clone() } |
1504 | } |
1505 | |
1506 | /// Makes a new `Ref` for a component of the borrowed data. |
1507 | /// |
1508 | /// The `RefCell` is already immutably borrowed, so this cannot fail. |
1509 | /// |
1510 | /// This is an associated function that needs to be used as `Ref::map(...)`. |
1511 | /// A method would interfere with methods of the same name on the contents |
1512 | /// of a `RefCell` used through `Deref`. |
1513 | /// |
1514 | /// # Examples |
1515 | /// |
1516 | /// ``` |
1517 | /// use std::cell::{RefCell, Ref}; |
1518 | /// |
1519 | /// let c = RefCell::new((5, 'b' )); |
1520 | /// let b1: Ref<'_, (u32, char)> = c.borrow(); |
1521 | /// let b2: Ref<'_, u32> = Ref::map(b1, |t| &t.0); |
1522 | /// assert_eq!(*b2, 5) |
1523 | /// ``` |
1524 | #[stable (feature = "cell_map" , since = "1.8.0" )] |
1525 | #[inline ] |
1526 | pub fn map<U: ?Sized, F>(orig: Ref<'b, T>, f: F) -> Ref<'b, U> |
1527 | where |
1528 | F: FnOnce(&T) -> &U, |
1529 | { |
1530 | Ref { value: NonNull::from(f(&*orig)), borrow: orig.borrow } |
1531 | } |
1532 | |
1533 | /// Makes a new `Ref` for an optional component of the borrowed data. The |
1534 | /// original guard is returned as an `Err(..)` if the closure returns |
1535 | /// `None`. |
1536 | /// |
1537 | /// The `RefCell` is already immutably borrowed, so this cannot fail. |
1538 | /// |
1539 | /// This is an associated function that needs to be used as |
1540 | /// `Ref::filter_map(...)`. A method would interfere with methods of the same |
1541 | /// name on the contents of a `RefCell` used through `Deref`. |
1542 | /// |
1543 | /// # Examples |
1544 | /// |
1545 | /// ``` |
1546 | /// use std::cell::{RefCell, Ref}; |
1547 | /// |
1548 | /// let c = RefCell::new(vec![1, 2, 3]); |
1549 | /// let b1: Ref<'_, Vec<u32>> = c.borrow(); |
1550 | /// let b2: Result<Ref<'_, u32>, _> = Ref::filter_map(b1, |v| v.get(1)); |
1551 | /// assert_eq!(*b2.unwrap(), 2); |
1552 | /// ``` |
1553 | #[stable (feature = "cell_filter_map" , since = "1.63.0" )] |
1554 | #[inline ] |
1555 | pub fn filter_map<U: ?Sized, F>(orig: Ref<'b, T>, f: F) -> Result<Ref<'b, U>, Self> |
1556 | where |
1557 | F: FnOnce(&T) -> Option<&U>, |
1558 | { |
1559 | match f(&*orig) { |
1560 | Some(value) => Ok(Ref { value: NonNull::from(value), borrow: orig.borrow }), |
1561 | None => Err(orig), |
1562 | } |
1563 | } |
1564 | |
1565 | /// Splits a `Ref` into multiple `Ref`s for different components of the |
1566 | /// borrowed data. |
1567 | /// |
1568 | /// The `RefCell` is already immutably borrowed, so this cannot fail. |
1569 | /// |
1570 | /// This is an associated function that needs to be used as |
1571 | /// `Ref::map_split(...)`. A method would interfere with methods of the same |
1572 | /// name on the contents of a `RefCell` used through `Deref`. |
1573 | /// |
1574 | /// # Examples |
1575 | /// |
1576 | /// ``` |
1577 | /// use std::cell::{Ref, RefCell}; |
1578 | /// |
1579 | /// let cell = RefCell::new([1, 2, 3, 4]); |
1580 | /// let borrow = cell.borrow(); |
1581 | /// let (begin, end) = Ref::map_split(borrow, |slice| slice.split_at(2)); |
1582 | /// assert_eq!(*begin, [1, 2]); |
1583 | /// assert_eq!(*end, [3, 4]); |
1584 | /// ``` |
1585 | #[stable (feature = "refcell_map_split" , since = "1.35.0" )] |
1586 | #[inline ] |
1587 | pub fn map_split<U: ?Sized, V: ?Sized, F>(orig: Ref<'b, T>, f: F) -> (Ref<'b, U>, Ref<'b, V>) |
1588 | where |
1589 | F: FnOnce(&T) -> (&U, &V), |
1590 | { |
1591 | let (a, b) = f(&*orig); |
1592 | let borrow = orig.borrow.clone(); |
1593 | ( |
1594 | Ref { value: NonNull::from(a), borrow }, |
1595 | Ref { value: NonNull::from(b), borrow: orig.borrow }, |
1596 | ) |
1597 | } |
1598 | |
1599 | /// Converts into a reference to the underlying data. |
1600 | /// |
1601 | /// The underlying `RefCell` can never be mutably borrowed from again and will always appear |
1602 | /// already immutably borrowed. It is not a good idea to leak more than a constant number of |
1603 | /// references. The `RefCell` can be immutably borrowed again if only a smaller number of leaks |
1604 | /// have occurred in total. |
1605 | /// |
1606 | /// This is an associated function that needs to be used as |
1607 | /// `Ref::leak(...)`. A method would interfere with methods of the |
1608 | /// same name on the contents of a `RefCell` used through `Deref`. |
1609 | /// |
1610 | /// # Examples |
1611 | /// |
1612 | /// ``` |
1613 | /// #![feature(cell_leak)] |
1614 | /// use std::cell::{RefCell, Ref}; |
1615 | /// let cell = RefCell::new(0); |
1616 | /// |
1617 | /// let value = Ref::leak(cell.borrow()); |
1618 | /// assert_eq!(*value, 0); |
1619 | /// |
1620 | /// assert!(cell.try_borrow().is_ok()); |
1621 | /// assert!(cell.try_borrow_mut().is_err()); |
1622 | /// ``` |
1623 | #[unstable (feature = "cell_leak" , issue = "69099" )] |
1624 | pub fn leak(orig: Ref<'b, T>) -> &'b T { |
1625 | // By forgetting this Ref we ensure that the borrow counter in the RefCell can't go back to |
1626 | // UNUSED within the lifetime `'b`. Resetting the reference tracking state would require a |
1627 | // unique reference to the borrowed RefCell. No further mutable references can be created |
1628 | // from the original cell. |
1629 | mem::forget(orig.borrow); |
1630 | // SAFETY: after forgetting, we can form a reference for the rest of lifetime `'b`. |
1631 | unsafe { orig.value.as_ref() } |
1632 | } |
1633 | } |
1634 | |
1635 | #[unstable (feature = "coerce_unsized" , issue = "18598" )] |
1636 | impl<'b, T: ?Sized + Unsize<U>, U: ?Sized> CoerceUnsized<Ref<'b, U>> for Ref<'b, T> {} |
1637 | |
1638 | #[stable (feature = "std_guard_impls" , since = "1.20.0" )] |
1639 | impl<T: ?Sized + fmt::Display> fmt::Display for Ref<'_, T> { |
1640 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
1641 | (**self).fmt(f) |
1642 | } |
1643 | } |
1644 | |
1645 | impl<'b, T: ?Sized> RefMut<'b, T> { |
1646 | /// Makes a new `RefMut` for a component of the borrowed data, e.g., an enum |
1647 | /// variant. |
1648 | /// |
1649 | /// The `RefCell` is already mutably borrowed, so this cannot fail. |
1650 | /// |
1651 | /// This is an associated function that needs to be used as |
1652 | /// `RefMut::map(...)`. A method would interfere with methods of the same |
1653 | /// name on the contents of a `RefCell` used through `Deref`. |
1654 | /// |
1655 | /// # Examples |
1656 | /// |
1657 | /// ``` |
1658 | /// use std::cell::{RefCell, RefMut}; |
1659 | /// |
1660 | /// let c = RefCell::new((5, 'b' )); |
1661 | /// { |
1662 | /// let b1: RefMut<'_, (u32, char)> = c.borrow_mut(); |
1663 | /// let mut b2: RefMut<'_, u32> = RefMut::map(b1, |t| &mut t.0); |
1664 | /// assert_eq!(*b2, 5); |
1665 | /// *b2 = 42; |
1666 | /// } |
1667 | /// assert_eq!(*c.borrow(), (42, 'b' )); |
1668 | /// ``` |
1669 | #[stable (feature = "cell_map" , since = "1.8.0" )] |
1670 | #[inline ] |
1671 | pub fn map<U: ?Sized, F>(mut orig: RefMut<'b, T>, f: F) -> RefMut<'b, U> |
1672 | where |
1673 | F: FnOnce(&mut T) -> &mut U, |
1674 | { |
1675 | let value = NonNull::from(f(&mut *orig)); |
1676 | RefMut { value, borrow: orig.borrow, marker: PhantomData } |
1677 | } |
1678 | |
1679 | /// Makes a new `RefMut` for an optional component of the borrowed data. The |
1680 | /// original guard is returned as an `Err(..)` if the closure returns |
1681 | /// `None`. |
1682 | /// |
1683 | /// The `RefCell` is already mutably borrowed, so this cannot fail. |
1684 | /// |
1685 | /// This is an associated function that needs to be used as |
1686 | /// `RefMut::filter_map(...)`. A method would interfere with methods of the |
1687 | /// same name on the contents of a `RefCell` used through `Deref`. |
1688 | /// |
1689 | /// # Examples |
1690 | /// |
1691 | /// ``` |
1692 | /// use std::cell::{RefCell, RefMut}; |
1693 | /// |
1694 | /// let c = RefCell::new(vec![1, 2, 3]); |
1695 | /// |
1696 | /// { |
1697 | /// let b1: RefMut<'_, Vec<u32>> = c.borrow_mut(); |
1698 | /// let mut b2: Result<RefMut<'_, u32>, _> = RefMut::filter_map(b1, |v| v.get_mut(1)); |
1699 | /// |
1700 | /// if let Ok(mut b2) = b2 { |
1701 | /// *b2 += 2; |
1702 | /// } |
1703 | /// } |
1704 | /// |
1705 | /// assert_eq!(*c.borrow(), vec![1, 4, 3]); |
1706 | /// ``` |
1707 | #[stable (feature = "cell_filter_map" , since = "1.63.0" )] |
1708 | #[inline ] |
1709 | pub fn filter_map<U: ?Sized, F>(mut orig: RefMut<'b, T>, f: F) -> Result<RefMut<'b, U>, Self> |
1710 | where |
1711 | F: FnOnce(&mut T) -> Option<&mut U>, |
1712 | { |
1713 | // SAFETY: function holds onto an exclusive reference for the duration |
1714 | // of its call through `orig`, and the pointer is only de-referenced |
1715 | // inside of the function call never allowing the exclusive reference to |
1716 | // escape. |
1717 | match f(&mut *orig) { |
1718 | Some(value) => { |
1719 | Ok(RefMut { value: NonNull::from(value), borrow: orig.borrow, marker: PhantomData }) |
1720 | } |
1721 | None => Err(orig), |
1722 | } |
1723 | } |
1724 | |
1725 | /// Splits a `RefMut` into multiple `RefMut`s for different components of the |
1726 | /// borrowed data. |
1727 | /// |
1728 | /// The underlying `RefCell` will remain mutably borrowed until both |
1729 | /// returned `RefMut`s go out of scope. |
1730 | /// |
1731 | /// The `RefCell` is already mutably borrowed, so this cannot fail. |
1732 | /// |
1733 | /// This is an associated function that needs to be used as |
1734 | /// `RefMut::map_split(...)`. A method would interfere with methods of the |
1735 | /// same name on the contents of a `RefCell` used through `Deref`. |
1736 | /// |
1737 | /// # Examples |
1738 | /// |
1739 | /// ``` |
1740 | /// use std::cell::{RefCell, RefMut}; |
1741 | /// |
1742 | /// let cell = RefCell::new([1, 2, 3, 4]); |
1743 | /// let borrow = cell.borrow_mut(); |
1744 | /// let (mut begin, mut end) = RefMut::map_split(borrow, |slice| slice.split_at_mut(2)); |
1745 | /// assert_eq!(*begin, [1, 2]); |
1746 | /// assert_eq!(*end, [3, 4]); |
1747 | /// begin.copy_from_slice(&[4, 3]); |
1748 | /// end.copy_from_slice(&[2, 1]); |
1749 | /// ``` |
1750 | #[stable (feature = "refcell_map_split" , since = "1.35.0" )] |
1751 | #[inline ] |
1752 | pub fn map_split<U: ?Sized, V: ?Sized, F>( |
1753 | mut orig: RefMut<'b, T>, |
1754 | f: F, |
1755 | ) -> (RefMut<'b, U>, RefMut<'b, V>) |
1756 | where |
1757 | F: FnOnce(&mut T) -> (&mut U, &mut V), |
1758 | { |
1759 | let borrow = orig.borrow.clone(); |
1760 | let (a, b) = f(&mut *orig); |
1761 | ( |
1762 | RefMut { value: NonNull::from(a), borrow, marker: PhantomData }, |
1763 | RefMut { value: NonNull::from(b), borrow: orig.borrow, marker: PhantomData }, |
1764 | ) |
1765 | } |
1766 | |
1767 | /// Converts into a mutable reference to the underlying data. |
1768 | /// |
1769 | /// The underlying `RefCell` can not be borrowed from again and will always appear already |
1770 | /// mutably borrowed, making the returned reference the only to the interior. |
1771 | /// |
1772 | /// This is an associated function that needs to be used as |
1773 | /// `RefMut::leak(...)`. A method would interfere with methods of the |
1774 | /// same name on the contents of a `RefCell` used through `Deref`. |
1775 | /// |
1776 | /// # Examples |
1777 | /// |
1778 | /// ``` |
1779 | /// #![feature(cell_leak)] |
1780 | /// use std::cell::{RefCell, RefMut}; |
1781 | /// let cell = RefCell::new(0); |
1782 | /// |
1783 | /// let value = RefMut::leak(cell.borrow_mut()); |
1784 | /// assert_eq!(*value, 0); |
1785 | /// *value = 1; |
1786 | /// |
1787 | /// assert!(cell.try_borrow_mut().is_err()); |
1788 | /// ``` |
1789 | #[unstable (feature = "cell_leak" , issue = "69099" )] |
1790 | pub fn leak(mut orig: RefMut<'b, T>) -> &'b mut T { |
1791 | // By forgetting this BorrowRefMut we ensure that the borrow counter in the RefCell can't |
1792 | // go back to UNUSED within the lifetime `'b`. Resetting the reference tracking state would |
1793 | // require a unique reference to the borrowed RefCell. No further references can be created |
1794 | // from the original cell within that lifetime, making the current borrow the only |
1795 | // reference for the remaining lifetime. |
1796 | mem::forget(orig.borrow); |
1797 | // SAFETY: after forgetting, we can form a reference for the rest of lifetime `'b`. |
1798 | unsafe { orig.value.as_mut() } |
1799 | } |
1800 | } |
1801 | |
1802 | struct BorrowRefMut<'b> { |
1803 | borrow: &'b Cell<BorrowFlag>, |
1804 | } |
1805 | |
1806 | impl Drop for BorrowRefMut<'_> { |
1807 | #[inline ] |
1808 | fn drop(&mut self) { |
1809 | let borrow: isize = self.borrow.get(); |
1810 | debug_assert!(is_writing(borrow)); |
1811 | self.borrow.set(val:borrow + 1); |
1812 | } |
1813 | } |
1814 | |
1815 | impl<'b> BorrowRefMut<'b> { |
1816 | #[inline ] |
1817 | fn new(borrow: &'b Cell<BorrowFlag>) -> Option<BorrowRefMut<'b>> { |
1818 | // NOTE: Unlike BorrowRefMut::clone, new is called to create the initial |
1819 | // mutable reference, and so there must currently be no existing |
1820 | // references. Thus, while clone increments the mutable refcount, here |
1821 | // we explicitly only allow going from UNUSED to UNUSED - 1. |
1822 | match borrow.get() { |
1823 | UNUSED => { |
1824 | borrow.set(UNUSED - 1); |
1825 | Some(BorrowRefMut { borrow }) |
1826 | } |
1827 | _ => None, |
1828 | } |
1829 | } |
1830 | |
1831 | // Clones a `BorrowRefMut`. |
1832 | // |
1833 | // This is only valid if each `BorrowRefMut` is used to track a mutable |
1834 | // reference to a distinct, nonoverlapping range of the original object. |
1835 | // This isn't in a Clone impl so that code doesn't call this implicitly. |
1836 | #[inline ] |
1837 | fn clone(&self) -> BorrowRefMut<'b> { |
1838 | let borrow = self.borrow.get(); |
1839 | debug_assert!(is_writing(borrow)); |
1840 | // Prevent the borrow counter from underflowing. |
1841 | assert!(borrow != BorrowFlag::MIN); |
1842 | self.borrow.set(borrow - 1); |
1843 | BorrowRefMut { borrow: self.borrow } |
1844 | } |
1845 | } |
1846 | |
1847 | /// A wrapper type for a mutably borrowed value from a `RefCell<T>`. |
1848 | /// |
1849 | /// See the [module-level documentation](self) for more. |
1850 | #[stable (feature = "rust1" , since = "1.0.0" )] |
1851 | #[must_not_suspend = "holding a RefMut across suspend points can cause BorrowErrors" ] |
1852 | #[rustc_diagnostic_item = "RefCellRefMut" ] |
1853 | pub struct RefMut<'b, T: ?Sized + 'b> { |
1854 | // NB: we use a pointer instead of `&'b mut T` to avoid `noalias` violations, because a |
1855 | // `RefMut` argument doesn't hold exclusivity for its whole scope, only until it drops. |
1856 | value: NonNull<T>, |
1857 | borrow: BorrowRefMut<'b>, |
1858 | // `NonNull` is covariant over `T`, so we need to reintroduce invariance. |
1859 | marker: PhantomData<&'b mut T>, |
1860 | } |
1861 | |
1862 | #[stable (feature = "rust1" , since = "1.0.0" )] |
1863 | impl<T: ?Sized> Deref for RefMut<'_, T> { |
1864 | type Target = T; |
1865 | |
1866 | #[inline ] |
1867 | fn deref(&self) -> &T { |
1868 | // SAFETY: the value is accessible as long as we hold our borrow. |
1869 | unsafe { self.value.as_ref() } |
1870 | } |
1871 | } |
1872 | |
1873 | #[stable (feature = "rust1" , since = "1.0.0" )] |
1874 | impl<T: ?Sized> DerefMut for RefMut<'_, T> { |
1875 | #[inline ] |
1876 | fn deref_mut(&mut self) -> &mut T { |
1877 | // SAFETY: the value is accessible as long as we hold our borrow. |
1878 | unsafe { self.value.as_mut() } |
1879 | } |
1880 | } |
1881 | |
1882 | #[unstable (feature = "deref_pure_trait" , issue = "87121" )] |
1883 | unsafe impl<T: ?Sized> DerefPure for RefMut<'_, T> {} |
1884 | |
1885 | #[unstable (feature = "coerce_unsized" , issue = "18598" )] |
1886 | impl<'b, T: ?Sized + Unsize<U>, U: ?Sized> CoerceUnsized<RefMut<'b, U>> for RefMut<'b, T> {} |
1887 | |
1888 | #[stable (feature = "std_guard_impls" , since = "1.20.0" )] |
1889 | impl<T: ?Sized + fmt::Display> fmt::Display for RefMut<'_, T> { |
1890 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
1891 | (**self).fmt(f) |
1892 | } |
1893 | } |
1894 | |
1895 | /// The core primitive for interior mutability in Rust. |
1896 | /// |
1897 | /// If you have a reference `&T`, then normally in Rust the compiler performs optimizations based on |
1898 | /// the knowledge that `&T` points to immutable data. Mutating that data, for example through an |
1899 | /// alias or by transmuting a `&T` into a `&mut T`, is considered undefined behavior. |
1900 | /// `UnsafeCell<T>` opts-out of the immutability guarantee for `&T`: a shared reference |
1901 | /// `&UnsafeCell<T>` may point to data that is being mutated. This is called "interior mutability". |
1902 | /// |
1903 | /// All other types that allow internal mutability, such as [`Cell<T>`] and [`RefCell<T>`], internally |
1904 | /// use `UnsafeCell` to wrap their data. |
1905 | /// |
1906 | /// Note that only the immutability guarantee for shared references is affected by `UnsafeCell`. The |
1907 | /// uniqueness guarantee for mutable references is unaffected. There is *no* legal way to obtain |
1908 | /// aliasing `&mut`, not even with `UnsafeCell<T>`. |
1909 | /// |
1910 | /// `UnsafeCell` does nothing to avoid data races; they are still undefined behavior. If multiple |
1911 | /// threads have access to the same `UnsafeCell`, they must follow the usual rules of the |
1912 | /// [concurrent memory model]: conflicting non-synchronized accesses must be done via the APIs in |
1913 | /// [`core::sync::atomic`]. |
1914 | /// |
1915 | /// The `UnsafeCell` API itself is technically very simple: [`.get()`] gives you a raw pointer |
1916 | /// `*mut T` to its contents. It is up to _you_ as the abstraction designer to use that raw pointer |
1917 | /// correctly. |
1918 | /// |
1919 | /// [`.get()`]: `UnsafeCell::get` |
1920 | /// [concurrent memory model]: ../sync/atomic/index.html#memory-model-for-atomic-accesses |
1921 | /// |
1922 | /// The precise Rust aliasing rules are somewhat in flux, but the main points are not contentious: |
1923 | /// |
1924 | /// - If you create a safe reference with lifetime `'a` (either a `&T` or `&mut T` reference), then |
1925 | /// you must not access the data in any way that contradicts that reference for the remainder of |
1926 | /// `'a`. For example, this means that if you take the `*mut T` from an `UnsafeCell<T>` and cast it |
1927 | /// to an `&T`, then the data in `T` must remain immutable (modulo any `UnsafeCell` data found |
1928 | /// within `T`, of course) until that reference's lifetime expires. Similarly, if you create a `&mut |
1929 | /// T` reference that is released to safe code, then you must not access the data within the |
1930 | /// `UnsafeCell` until that reference expires. |
1931 | /// |
1932 | /// - For both `&T` without `UnsafeCell<_>` and `&mut T`, you must also not deallocate the data |
1933 | /// until the reference expires. As a special exception, given an `&T`, any part of it that is |
1934 | /// inside an `UnsafeCell<_>` may be deallocated during the lifetime of the reference, after the |
1935 | /// last time the reference is used (dereferenced or reborrowed). Since you cannot deallocate a part |
1936 | /// of what a reference points to, this means the memory an `&T` points to can be deallocated only if |
1937 | /// *every part of it* (including padding) is inside an `UnsafeCell`. |
1938 | /// |
1939 | /// However, whenever a `&UnsafeCell<T>` is constructed or dereferenced, it must still point to |
1940 | /// live memory and the compiler is allowed to insert spurious reads if it can prove that this |
1941 | /// memory has not yet been deallocated. |
1942 | /// |
1943 | /// To assist with proper design, the following scenarios are explicitly declared legal |
1944 | /// for single-threaded code: |
1945 | /// |
1946 | /// 1. A `&T` reference can be released to safe code and there it can co-exist with other `&T` |
1947 | /// references, but not with a `&mut T` |
1948 | /// |
1949 | /// 2. A `&mut T` reference may be released to safe code provided neither other `&mut T` nor `&T` |
1950 | /// co-exist with it. A `&mut T` must always be unique. |
1951 | /// |
1952 | /// Note that whilst mutating the contents of an `&UnsafeCell<T>` (even while other |
1953 | /// `&UnsafeCell<T>` references alias the cell) is |
1954 | /// ok (provided you enforce the above invariants some other way), it is still undefined behavior |
1955 | /// to have multiple `&mut UnsafeCell<T>` aliases. That is, `UnsafeCell` is a wrapper |
1956 | /// designed to have a special interaction with _shared_ accesses (_i.e._, through an |
1957 | /// `&UnsafeCell<_>` reference); there is no magic whatsoever when dealing with _exclusive_ |
1958 | /// accesses (_e.g._, through a `&mut UnsafeCell<_>`): neither the cell nor the wrapped value |
1959 | /// may be aliased for the duration of that `&mut` borrow. |
1960 | /// This is showcased by the [`.get_mut()`] accessor, which is a _safe_ getter that yields |
1961 | /// a `&mut T`. |
1962 | /// |
1963 | /// [`.get_mut()`]: `UnsafeCell::get_mut` |
1964 | /// |
1965 | /// # Memory layout |
1966 | /// |
1967 | /// `UnsafeCell<T>` has the same in-memory representation as its inner type `T`. A consequence |
1968 | /// of this guarantee is that it is possible to convert between `T` and `UnsafeCell<T>`. |
1969 | /// Special care has to be taken when converting a nested `T` inside of an `Outer<T>` type |
1970 | /// to an `Outer<UnsafeCell<T>>` type: this is not sound when the `Outer<T>` type enables [niche] |
1971 | /// optimizations. For example, the type `Option<NonNull<u8>>` is typically 8 bytes large on |
1972 | /// 64-bit platforms, but the type `Option<UnsafeCell<NonNull<u8>>>` takes up 16 bytes of space. |
1973 | /// Therefore this is not a valid conversion, despite `NonNull<u8>` and `UnsafeCell<NonNull<u8>>>` |
1974 | /// having the same memory layout. This is because `UnsafeCell` disables niche optimizations in |
1975 | /// order to avoid its interior mutability property from spreading from `T` into the `Outer` type, |
1976 | /// thus this can cause distortions in the type size in these cases. |
1977 | /// |
1978 | /// Note that the only valid way to obtain a `*mut T` pointer to the contents of a |
1979 | /// _shared_ `UnsafeCell<T>` is through [`.get()`] or [`.raw_get()`]. A `&mut T` reference |
1980 | /// can be obtained by either dereferencing this pointer or by calling [`.get_mut()`] |
1981 | /// on an _exclusive_ `UnsafeCell<T>`. Even though `T` and `UnsafeCell<T>` have the |
1982 | /// same memory layout, the following is not allowed and undefined behavior: |
1983 | /// |
1984 | /// ```rust,compile_fail |
1985 | /// # use std::cell::UnsafeCell; |
1986 | /// unsafe fn not_allowed<T>(ptr: &UnsafeCell<T>) -> &mut T { |
1987 | /// let t = ptr as *const UnsafeCell<T> as *mut T; |
1988 | /// // This is undefined behavior, because the `*mut T` pointer |
1989 | /// // was not obtained through `.get()` nor `.raw_get()`: |
1990 | /// unsafe { &mut *t } |
1991 | /// } |
1992 | /// ``` |
1993 | /// |
1994 | /// Instead, do this: |
1995 | /// |
1996 | /// ```rust |
1997 | /// # use std::cell::UnsafeCell; |
1998 | /// // Safety: the caller must ensure that there are no references that |
1999 | /// // point to the *contents* of the `UnsafeCell`. |
2000 | /// unsafe fn get_mut<T>(ptr: &UnsafeCell<T>) -> &mut T { |
2001 | /// unsafe { &mut *ptr.get() } |
2002 | /// } |
2003 | /// ``` |
2004 | /// |
2005 | /// Converting in the other direction from a `&mut T` |
2006 | /// to an `&UnsafeCell<T>` is allowed: |
2007 | /// |
2008 | /// ```rust |
2009 | /// # use std::cell::UnsafeCell; |
2010 | /// fn get_shared<T>(ptr: &mut T) -> &UnsafeCell<T> { |
2011 | /// let t = ptr as *mut T as *const UnsafeCell<T>; |
2012 | /// // SAFETY: `T` and `UnsafeCell<T>` have the same memory layout |
2013 | /// unsafe { &*t } |
2014 | /// } |
2015 | /// ``` |
2016 | /// |
2017 | /// [niche]: https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#niche |
2018 | /// [`.raw_get()`]: `UnsafeCell::raw_get` |
2019 | /// |
2020 | /// # Examples |
2021 | /// |
2022 | /// Here is an example showcasing how to soundly mutate the contents of an `UnsafeCell<_>` despite |
2023 | /// there being multiple references aliasing the cell: |
2024 | /// |
2025 | /// ``` |
2026 | /// use std::cell::UnsafeCell; |
2027 | /// |
2028 | /// let x: UnsafeCell<i32> = 42.into(); |
2029 | /// // Get multiple / concurrent / shared references to the same `x`. |
2030 | /// let (p1, p2): (&UnsafeCell<i32>, &UnsafeCell<i32>) = (&x, &x); |
2031 | /// |
2032 | /// unsafe { |
2033 | /// // SAFETY: within this scope there are no other references to `x`'s contents, |
2034 | /// // so ours is effectively unique. |
2035 | /// let p1_exclusive: &mut i32 = &mut *p1.get(); // -- borrow --+ |
2036 | /// *p1_exclusive += 27; // | |
2037 | /// } // <---------- cannot go beyond this point -------------------+ |
2038 | /// |
2039 | /// unsafe { |
2040 | /// // SAFETY: within this scope nobody expects to have exclusive access to `x`'s contents, |
2041 | /// // so we can have multiple shared accesses concurrently. |
2042 | /// let p2_shared: &i32 = &*p2.get(); |
2043 | /// assert_eq!(*p2_shared, 42 + 27); |
2044 | /// let p1_shared: &i32 = &*p1.get(); |
2045 | /// assert_eq!(*p1_shared, *p2_shared); |
2046 | /// } |
2047 | /// ``` |
2048 | /// |
2049 | /// The following example showcases the fact that exclusive access to an `UnsafeCell<T>` |
2050 | /// implies exclusive access to its `T`: |
2051 | /// |
2052 | /// ```rust |
2053 | /// #![forbid(unsafe_code)] // with exclusive accesses, |
2054 | /// // `UnsafeCell` is a transparent no-op wrapper, |
2055 | /// // so no need for `unsafe` here. |
2056 | /// use std::cell::UnsafeCell; |
2057 | /// |
2058 | /// let mut x: UnsafeCell<i32> = 42.into(); |
2059 | /// |
2060 | /// // Get a compile-time-checked unique reference to `x`. |
2061 | /// let p_unique: &mut UnsafeCell<i32> = &mut x; |
2062 | /// // With an exclusive reference, we can mutate the contents for free. |
2063 | /// *p_unique.get_mut() = 0; |
2064 | /// // Or, equivalently: |
2065 | /// x = UnsafeCell::new(0); |
2066 | /// |
2067 | /// // When we own the value, we can extract the contents for free. |
2068 | /// let contents: i32 = x.into_inner(); |
2069 | /// assert_eq!(contents, 0); |
2070 | /// ``` |
2071 | #[lang = "unsafe_cell" ] |
2072 | #[stable (feature = "rust1" , since = "1.0.0" )] |
2073 | #[repr (transparent)] |
2074 | #[rustc_pub_transparent] |
2075 | pub struct UnsafeCell<T: ?Sized> { |
2076 | value: T, |
2077 | } |
2078 | |
2079 | #[stable (feature = "rust1" , since = "1.0.0" )] |
2080 | impl<T: ?Sized> !Sync for UnsafeCell<T> {} |
2081 | |
2082 | impl<T> UnsafeCell<T> { |
2083 | /// Constructs a new instance of `UnsafeCell` which will wrap the specified |
2084 | /// value. |
2085 | /// |
2086 | /// All access to the inner value through `&UnsafeCell<T>` requires `unsafe` code. |
2087 | /// |
2088 | /// # Examples |
2089 | /// |
2090 | /// ``` |
2091 | /// use std::cell::UnsafeCell; |
2092 | /// |
2093 | /// let uc = UnsafeCell::new(5); |
2094 | /// ``` |
2095 | #[stable (feature = "rust1" , since = "1.0.0" )] |
2096 | #[rustc_const_stable (feature = "const_unsafe_cell_new" , since = "1.32.0" )] |
2097 | #[inline (always)] |
2098 | pub const fn new(value: T) -> UnsafeCell<T> { |
2099 | UnsafeCell { value } |
2100 | } |
2101 | |
2102 | /// Unwraps the value, consuming the cell. |
2103 | /// |
2104 | /// # Examples |
2105 | /// |
2106 | /// ``` |
2107 | /// use std::cell::UnsafeCell; |
2108 | /// |
2109 | /// let uc = UnsafeCell::new(5); |
2110 | /// |
2111 | /// let five = uc.into_inner(); |
2112 | /// ``` |
2113 | #[inline (always)] |
2114 | #[stable (feature = "rust1" , since = "1.0.0" )] |
2115 | #[rustc_const_stable (feature = "const_cell_into_inner" , since = "1.83.0" )] |
2116 | #[rustc_allow_const_fn_unstable (const_precise_live_drops)] |
2117 | pub const fn into_inner(self) -> T { |
2118 | self.value |
2119 | } |
2120 | |
2121 | /// Replace the value in this `UnsafeCell` and return the old value. |
2122 | /// |
2123 | /// # Safety |
2124 | /// |
2125 | /// The caller must take care to avoid aliasing and data races. |
2126 | /// |
2127 | /// - It is Undefined Behavior to allow calls to race with |
2128 | /// any other access to the wrapped value. |
2129 | /// - It is Undefined Behavior to call this while any other |
2130 | /// reference(s) to the wrapped value are alive. |
2131 | /// |
2132 | /// # Examples |
2133 | /// |
2134 | /// ``` |
2135 | /// #![feature(unsafe_cell_access)] |
2136 | /// use std::cell::UnsafeCell; |
2137 | /// |
2138 | /// let uc = UnsafeCell::new(5); |
2139 | /// |
2140 | /// let old = unsafe { uc.replace(10) }; |
2141 | /// assert_eq!(old, 5); |
2142 | /// ``` |
2143 | #[inline ] |
2144 | #[unstable (feature = "unsafe_cell_access" , issue = "136327" )] |
2145 | pub const unsafe fn replace(&self, value: T) -> T { |
2146 | // SAFETY: pointer comes from `&self` so naturally satisfies invariants. |
2147 | unsafe { ptr::replace(self.get(), value) } |
2148 | } |
2149 | } |
2150 | |
2151 | impl<T: ?Sized> UnsafeCell<T> { |
2152 | /// Converts from `&mut T` to `&mut UnsafeCell<T>`. |
2153 | /// |
2154 | /// # Examples |
2155 | /// |
2156 | /// ``` |
2157 | /// use std::cell::UnsafeCell; |
2158 | /// |
2159 | /// let mut val = 42; |
2160 | /// let uc = UnsafeCell::from_mut(&mut val); |
2161 | /// |
2162 | /// *uc.get_mut() -= 1; |
2163 | /// assert_eq!(*uc.get_mut(), 41); |
2164 | /// ``` |
2165 | #[inline (always)] |
2166 | #[stable (feature = "unsafe_cell_from_mut" , since = "1.84.0" )] |
2167 | #[rustc_const_stable (feature = "unsafe_cell_from_mut" , since = "1.84.0" )] |
2168 | pub const fn from_mut(value: &mut T) -> &mut UnsafeCell<T> { |
2169 | // SAFETY: `UnsafeCell<T>` has the same memory layout as `T` due to #[repr(transparent)]. |
2170 | unsafe { &mut *(value as *mut T as *mut UnsafeCell<T>) } |
2171 | } |
2172 | |
2173 | /// Gets a mutable pointer to the wrapped value. |
2174 | /// |
2175 | /// This can be cast to a pointer of any kind. |
2176 | /// Ensure that the access is unique (no active references, mutable or not) |
2177 | /// when casting to `&mut T`, and ensure that there are no mutations |
2178 | /// or mutable aliases going on when casting to `&T` |
2179 | /// |
2180 | /// # Examples |
2181 | /// |
2182 | /// ``` |
2183 | /// use std::cell::UnsafeCell; |
2184 | /// |
2185 | /// let uc = UnsafeCell::new(5); |
2186 | /// |
2187 | /// let five = uc.get(); |
2188 | /// ``` |
2189 | #[inline (always)] |
2190 | #[stable (feature = "rust1" , since = "1.0.0" )] |
2191 | #[rustc_const_stable (feature = "const_unsafecell_get" , since = "1.32.0" )] |
2192 | #[rustc_as_ptr] |
2193 | #[rustc_never_returns_null_ptr ] |
2194 | pub const fn get(&self) -> *mut T { |
2195 | // We can just cast the pointer from `UnsafeCell<T>` to `T` because of |
2196 | // #[repr(transparent)]. This exploits std's special status, there is |
2197 | // no guarantee for user code that this will work in future versions of the compiler! |
2198 | self as *const UnsafeCell<T> as *const T as *mut T |
2199 | } |
2200 | |
2201 | /// Returns a mutable reference to the underlying data. |
2202 | /// |
2203 | /// This call borrows the `UnsafeCell` mutably (at compile-time) which |
2204 | /// guarantees that we possess the only reference. |
2205 | /// |
2206 | /// # Examples |
2207 | /// |
2208 | /// ``` |
2209 | /// use std::cell::UnsafeCell; |
2210 | /// |
2211 | /// let mut c = UnsafeCell::new(5); |
2212 | /// *c.get_mut() += 1; |
2213 | /// |
2214 | /// assert_eq!(*c.get_mut(), 6); |
2215 | /// ``` |
2216 | #[inline (always)] |
2217 | #[stable (feature = "unsafe_cell_get_mut" , since = "1.50.0" )] |
2218 | #[rustc_const_stable (feature = "const_unsafecell_get_mut" , since = "1.83.0" )] |
2219 | pub const fn get_mut(&mut self) -> &mut T { |
2220 | &mut self.value |
2221 | } |
2222 | |
2223 | /// Gets a mutable pointer to the wrapped value. |
2224 | /// The difference from [`get`] is that this function accepts a raw pointer, |
2225 | /// which is useful to avoid the creation of temporary references. |
2226 | /// |
2227 | /// The result can be cast to a pointer of any kind. |
2228 | /// Ensure that the access is unique (no active references, mutable or not) |
2229 | /// when casting to `&mut T`, and ensure that there are no mutations |
2230 | /// or mutable aliases going on when casting to `&T`. |
2231 | /// |
2232 | /// [`get`]: UnsafeCell::get() |
2233 | /// |
2234 | /// # Examples |
2235 | /// |
2236 | /// Gradual initialization of an `UnsafeCell` requires `raw_get`, as |
2237 | /// calling `get` would require creating a reference to uninitialized data: |
2238 | /// |
2239 | /// ``` |
2240 | /// use std::cell::UnsafeCell; |
2241 | /// use std::mem::MaybeUninit; |
2242 | /// |
2243 | /// let m = MaybeUninit::<UnsafeCell<i32>>::uninit(); |
2244 | /// unsafe { UnsafeCell::raw_get(m.as_ptr()).write(5); } |
2245 | /// // avoid below which references to uninitialized data |
2246 | /// // unsafe { UnsafeCell::get(&*m.as_ptr()).write(5); } |
2247 | /// let uc = unsafe { m.assume_init() }; |
2248 | /// |
2249 | /// assert_eq!(uc.into_inner(), 5); |
2250 | /// ``` |
2251 | #[inline (always)] |
2252 | #[stable (feature = "unsafe_cell_raw_get" , since = "1.56.0" )] |
2253 | #[rustc_const_stable (feature = "unsafe_cell_raw_get" , since = "1.56.0" )] |
2254 | #[rustc_diagnostic_item = "unsafe_cell_raw_get" ] |
2255 | pub const fn raw_get(this: *const Self) -> *mut T { |
2256 | // We can just cast the pointer from `UnsafeCell<T>` to `T` because of |
2257 | // #[repr(transparent)]. This exploits std's special status, there is |
2258 | // no guarantee for user code that this will work in future versions of the compiler! |
2259 | this as *const T as *mut T |
2260 | } |
2261 | |
2262 | /// Get a shared reference to the value within the `UnsafeCell`. |
2263 | /// |
2264 | /// # Safety |
2265 | /// |
2266 | /// - It is Undefined Behavior to call this while any mutable |
2267 | /// reference to the wrapped value is alive. |
2268 | /// - Mutating the wrapped value while the returned |
2269 | /// reference is alive is Undefined Behavior. |
2270 | /// |
2271 | /// # Examples |
2272 | /// |
2273 | /// ``` |
2274 | /// #![feature(unsafe_cell_access)] |
2275 | /// use std::cell::UnsafeCell; |
2276 | /// |
2277 | /// let uc = UnsafeCell::new(5); |
2278 | /// |
2279 | /// let val = unsafe { uc.as_ref_unchecked() }; |
2280 | /// assert_eq!(val, &5); |
2281 | /// ``` |
2282 | #[inline ] |
2283 | #[unstable (feature = "unsafe_cell_access" , issue = "136327" )] |
2284 | pub const unsafe fn as_ref_unchecked(&self) -> &T { |
2285 | // SAFETY: pointer comes from `&self` so naturally satisfies ptr-to-ref invariants. |
2286 | unsafe { self.get().as_ref_unchecked() } |
2287 | } |
2288 | |
2289 | /// Get an exclusive reference to the value within the `UnsafeCell`. |
2290 | /// |
2291 | /// # Safety |
2292 | /// |
2293 | /// - It is Undefined Behavior to call this while any other |
2294 | /// reference(s) to the wrapped value are alive. |
2295 | /// - Mutating the wrapped value through other means while the |
2296 | /// returned reference is alive is Undefined Behavior. |
2297 | /// |
2298 | /// # Examples |
2299 | /// |
2300 | /// ``` |
2301 | /// #![feature(unsafe_cell_access)] |
2302 | /// use std::cell::UnsafeCell; |
2303 | /// |
2304 | /// let uc = UnsafeCell::new(5); |
2305 | /// |
2306 | /// unsafe { *uc.as_mut_unchecked() += 1; } |
2307 | /// assert_eq!(uc.into_inner(), 6); |
2308 | /// ``` |
2309 | #[inline ] |
2310 | #[unstable (feature = "unsafe_cell_access" , issue = "136327" )] |
2311 | #[allow (clippy::mut_from_ref)] |
2312 | pub const unsafe fn as_mut_unchecked(&self) -> &mut T { |
2313 | // SAFETY: pointer comes from `&self` so naturally satisfies ptr-to-ref invariants. |
2314 | unsafe { self.get().as_mut_unchecked() } |
2315 | } |
2316 | } |
2317 | |
2318 | #[stable (feature = "unsafe_cell_default" , since = "1.10.0" )] |
2319 | impl<T: Default> Default for UnsafeCell<T> { |
2320 | /// Creates an `UnsafeCell`, with the `Default` value for T. |
2321 | fn default() -> UnsafeCell<T> { |
2322 | UnsafeCell::new(Default::default()) |
2323 | } |
2324 | } |
2325 | |
2326 | #[stable (feature = "cell_from" , since = "1.12.0" )] |
2327 | impl<T> From<T> for UnsafeCell<T> { |
2328 | /// Creates a new `UnsafeCell<T>` containing the given value. |
2329 | fn from(t: T) -> UnsafeCell<T> { |
2330 | UnsafeCell::new(t) |
2331 | } |
2332 | } |
2333 | |
2334 | #[unstable (feature = "coerce_unsized" , issue = "18598" )] |
2335 | impl<T: CoerceUnsized<U>, U> CoerceUnsized<UnsafeCell<U>> for UnsafeCell<T> {} |
2336 | |
2337 | // Allow types that wrap `UnsafeCell` to also implement `DispatchFromDyn` |
2338 | // and become dyn-compatible method receivers. |
2339 | // Note that currently `UnsafeCell` itself cannot be a method receiver |
2340 | // because it does not implement Deref. |
2341 | // In other words: |
2342 | // `self: UnsafeCell<&Self>` won't work |
2343 | // `self: UnsafeCellWrapper<Self>` becomes possible |
2344 | #[unstable (feature = "dispatch_from_dyn" , issue = "none" )] |
2345 | impl<T: DispatchFromDyn<U>, U> DispatchFromDyn<UnsafeCell<U>> for UnsafeCell<T> {} |
2346 | |
2347 | #[unstable (feature = "pointer_like_trait" , issue = "none" )] |
2348 | impl<T: PointerLike> PointerLike for UnsafeCell<T> {} |
2349 | |
2350 | /// [`UnsafeCell`], but [`Sync`]. |
2351 | /// |
2352 | /// This is just an `UnsafeCell`, except it implements `Sync` |
2353 | /// if `T` implements `Sync`. |
2354 | /// |
2355 | /// `UnsafeCell` doesn't implement `Sync`, to prevent accidental mis-use. |
2356 | /// You can use `SyncUnsafeCell` instead of `UnsafeCell` to allow it to be |
2357 | /// shared between threads, if that's intentional. |
2358 | /// Providing proper synchronization is still the task of the user, |
2359 | /// making this type just as unsafe to use. |
2360 | /// |
2361 | /// See [`UnsafeCell`] for details. |
2362 | #[unstable (feature = "sync_unsafe_cell" , issue = "95439" )] |
2363 | #[repr (transparent)] |
2364 | #[rustc_diagnostic_item = "SyncUnsafeCell" ] |
2365 | #[rustc_pub_transparent] |
2366 | pub struct SyncUnsafeCell<T: ?Sized> { |
2367 | value: UnsafeCell<T>, |
2368 | } |
2369 | |
2370 | #[unstable (feature = "sync_unsafe_cell" , issue = "95439" )] |
2371 | unsafe impl<T: ?Sized + Sync> Sync for SyncUnsafeCell<T> {} |
2372 | |
2373 | #[unstable (feature = "sync_unsafe_cell" , issue = "95439" )] |
2374 | impl<T> SyncUnsafeCell<T> { |
2375 | /// Constructs a new instance of `SyncUnsafeCell` which will wrap the specified value. |
2376 | #[inline ] |
2377 | pub const fn new(value: T) -> Self { |
2378 | Self { value: UnsafeCell { value } } |
2379 | } |
2380 | |
2381 | /// Unwraps the value, consuming the cell. |
2382 | #[inline ] |
2383 | #[rustc_const_unstable (feature = "sync_unsafe_cell" , issue = "95439" )] |
2384 | pub const fn into_inner(self) -> T { |
2385 | self.value.into_inner() |
2386 | } |
2387 | } |
2388 | |
2389 | #[unstable (feature = "sync_unsafe_cell" , issue = "95439" )] |
2390 | impl<T: ?Sized> SyncUnsafeCell<T> { |
2391 | /// Gets a mutable pointer to the wrapped value. |
2392 | /// |
2393 | /// This can be cast to a pointer of any kind. |
2394 | /// Ensure that the access is unique (no active references, mutable or not) |
2395 | /// when casting to `&mut T`, and ensure that there are no mutations |
2396 | /// or mutable aliases going on when casting to `&T` |
2397 | #[inline ] |
2398 | #[rustc_as_ptr] |
2399 | #[rustc_never_returns_null_ptr ] |
2400 | pub const fn get(&self) -> *mut T { |
2401 | self.value.get() |
2402 | } |
2403 | |
2404 | /// Returns a mutable reference to the underlying data. |
2405 | /// |
2406 | /// This call borrows the `SyncUnsafeCell` mutably (at compile-time) which |
2407 | /// guarantees that we possess the only reference. |
2408 | #[inline ] |
2409 | pub const fn get_mut(&mut self) -> &mut T { |
2410 | self.value.get_mut() |
2411 | } |
2412 | |
2413 | /// Gets a mutable pointer to the wrapped value. |
2414 | /// |
2415 | /// See [`UnsafeCell::get`] for details. |
2416 | #[inline ] |
2417 | pub const fn raw_get(this: *const Self) -> *mut T { |
2418 | // We can just cast the pointer from `SyncUnsafeCell<T>` to `T` because |
2419 | // of #[repr(transparent)] on both SyncUnsafeCell and UnsafeCell. |
2420 | // See UnsafeCell::raw_get. |
2421 | this as *const T as *mut T |
2422 | } |
2423 | } |
2424 | |
2425 | #[unstable (feature = "sync_unsafe_cell" , issue = "95439" )] |
2426 | impl<T: Default> Default for SyncUnsafeCell<T> { |
2427 | /// Creates an `SyncUnsafeCell`, with the `Default` value for T. |
2428 | fn default() -> SyncUnsafeCell<T> { |
2429 | SyncUnsafeCell::new(Default::default()) |
2430 | } |
2431 | } |
2432 | |
2433 | #[unstable (feature = "sync_unsafe_cell" , issue = "95439" )] |
2434 | impl<T> From<T> for SyncUnsafeCell<T> { |
2435 | /// Creates a new `SyncUnsafeCell<T>` containing the given value. |
2436 | fn from(t: T) -> SyncUnsafeCell<T> { |
2437 | SyncUnsafeCell::new(t) |
2438 | } |
2439 | } |
2440 | |
2441 | #[unstable (feature = "coerce_unsized" , issue = "18598" )] |
2442 | //#[unstable(feature = "sync_unsafe_cell", issue = "95439")] |
2443 | impl<T: CoerceUnsized<U>, U> CoerceUnsized<SyncUnsafeCell<U>> for SyncUnsafeCell<T> {} |
2444 | |
2445 | // Allow types that wrap `SyncUnsafeCell` to also implement `DispatchFromDyn` |
2446 | // and become dyn-compatible method receivers. |
2447 | // Note that currently `SyncUnsafeCell` itself cannot be a method receiver |
2448 | // because it does not implement Deref. |
2449 | // In other words: |
2450 | // `self: SyncUnsafeCell<&Self>` won't work |
2451 | // `self: SyncUnsafeCellWrapper<Self>` becomes possible |
2452 | #[unstable (feature = "dispatch_from_dyn" , issue = "none" )] |
2453 | //#[unstable(feature = "sync_unsafe_cell", issue = "95439")] |
2454 | impl<T: DispatchFromDyn<U>, U> DispatchFromDyn<SyncUnsafeCell<U>> for SyncUnsafeCell<T> {} |
2455 | |
2456 | #[unstable (feature = "pointer_like_trait" , issue = "none" )] |
2457 | impl<T: PointerLike> PointerLike for SyncUnsafeCell<T> {} |
2458 | |
2459 | #[allow (unused)] |
2460 | fn assert_coerce_unsized( |
2461 | a: UnsafeCell<&i32>, |
2462 | b: SyncUnsafeCell<&i32>, |
2463 | c: Cell<&i32>, |
2464 | d: RefCell<&i32>, |
2465 | ) { |
2466 | let _: UnsafeCell<&dyn Send> = a; |
2467 | let _: SyncUnsafeCell<&dyn Send> = b; |
2468 | let _: Cell<&dyn Send> = c; |
2469 | let _: RefCell<&dyn Send> = d; |
2470 | } |
2471 | |
2472 | #[unstable (feature = "pin_coerce_unsized_trait" , issue = "123430" )] |
2473 | unsafe impl<T: ?Sized> PinCoerceUnsized for UnsafeCell<T> {} |
2474 | |
2475 | #[unstable (feature = "pin_coerce_unsized_trait" , issue = "123430" )] |
2476 | unsafe impl<T: ?Sized> PinCoerceUnsized for SyncUnsafeCell<T> {} |
2477 | |
2478 | #[unstable (feature = "pin_coerce_unsized_trait" , issue = "123430" )] |
2479 | unsafe impl<T: ?Sized> PinCoerceUnsized for Cell<T> {} |
2480 | |
2481 | #[unstable (feature = "pin_coerce_unsized_trait" , issue = "123430" )] |
2482 | unsafe impl<T: ?Sized> PinCoerceUnsized for RefCell<T> {} |
2483 | |
2484 | #[unstable (feature = "pin_coerce_unsized_trait" , issue = "123430" )] |
2485 | unsafe impl<'b, T: ?Sized> PinCoerceUnsized for Ref<'b, T> {} |
2486 | |
2487 | #[unstable (feature = "pin_coerce_unsized_trait" , issue = "123430" )] |
2488 | unsafe impl<'b, T: ?Sized> PinCoerceUnsized for RefMut<'b, T> {} |
2489 | |