1 use crate::cell::UnsafeCell;
5 /// A cell which can be written to only once.
7 /// Unlike [`RefCell`], a `OnceCell` only provides shared `&T` references to its value.
8 /// Unlike [`Cell`], a `OnceCell` doesn't require copying or replacing the value to access it.
10 /// For a thread-safe version of this struct, see [`std::sync::OnceLock`].
12 /// [`RefCell`]: crate::cell::RefCell
13 /// [`Cell`]: crate::cell::Cell
14 /// [`std::sync::OnceLock`]: ../../std/sync/struct.OnceLock.html
19 /// #![feature(once_cell)]
21 /// use std::cell::OnceCell;
23 /// let cell = OnceCell::new();
24 /// assert!(cell.get().is_none());
26 /// let value: &String = cell.get_or_init(|| {
27 /// "Hello, World!".to_string()
29 /// assert_eq!(value, "Hello, World!");
30 /// assert!(cell.get().is_some());
32 #[unstable(feature = "once_cell", issue = "74465")]
33 pub struct OnceCell<T> {
34 // Invariant: written to at most once.
35 inner: UnsafeCell<Option<T>>,
39 /// Creates a new empty cell.
40 #[unstable(feature = "once_cell", issue = "74465")]
42 pub const fn new() -> OnceCell<T> {
43 OnceCell { inner: UnsafeCell::new(None) }
46 /// Gets the reference to the underlying value.
48 /// Returns `None` if the cell is empty.
49 #[unstable(feature = "once_cell", issue = "74465")]
50 pub fn get(&self) -> Option<&T> {
51 // SAFETY: Safe due to `inner`'s invariant
52 unsafe { &*self.inner.get() }.as_ref()
55 /// Gets the mutable reference to the underlying value.
57 /// Returns `None` if the cell is empty.
58 #[unstable(feature = "once_cell", issue = "74465")]
59 pub fn get_mut(&mut self) -> Option<&mut T> {
60 self.inner.get_mut().as_mut()
63 /// Sets the contents of the cell to `value`.
67 /// This method returns `Ok(())` if the cell was empty and `Err(value)` if
73 /// #![feature(once_cell)]
75 /// use std::cell::OnceCell;
77 /// let cell = OnceCell::new();
78 /// assert!(cell.get().is_none());
80 /// assert_eq!(cell.set(92), Ok(()));
81 /// assert_eq!(cell.set(62), Err(62));
83 /// assert!(cell.get().is_some());
85 #[unstable(feature = "once_cell", issue = "74465")]
86 pub fn set(&self, value: T) -> Result<(), T> {
87 // SAFETY: Safe because we cannot have overlapping mutable borrows
88 let slot = unsafe { &*self.inner.get() };
93 // SAFETY: This is the only place where we set the slot, no races
94 // due to reentrancy/concurrency are possible, and we've
95 // checked that slot is currently `None`, so this write
96 // maintains the `inner`'s invariant.
97 let slot = unsafe { &mut *self.inner.get() };
102 /// Gets the contents of the cell, initializing it with `f`
103 /// if the cell was empty.
107 /// If `f` panics, the panic is propagated to the caller, and the cell
108 /// remains uninitialized.
110 /// It is an error to reentrantly initialize the cell from `f`. Doing
111 /// so results in a panic.
116 /// #![feature(once_cell)]
118 /// use std::cell::OnceCell;
120 /// let cell = OnceCell::new();
121 /// let value = cell.get_or_init(|| 92);
122 /// assert_eq!(value, &92);
123 /// let value = cell.get_or_init(|| unreachable!());
124 /// assert_eq!(value, &92);
126 #[unstable(feature = "once_cell", issue = "74465")]
127 pub fn get_or_init<F>(&self, f: F) -> &T
131 match self.get_or_try_init(|| Ok::<T, !>(f())) {
136 /// Gets the contents of the cell, initializing it with `f` if
137 /// the cell was empty. If the cell was empty and `f` failed, an
138 /// error is returned.
142 /// If `f` panics, the panic is propagated to the caller, and the cell
143 /// remains uninitialized.
145 /// It is an error to reentrantly initialize the cell from `f`. Doing
146 /// so results in a panic.
151 /// #![feature(once_cell)]
153 /// use std::cell::OnceCell;
155 /// let cell = OnceCell::new();
156 /// assert_eq!(cell.get_or_try_init(|| Err(())), Err(()));
157 /// assert!(cell.get().is_none());
158 /// let value = cell.get_or_try_init(|| -> Result<i32, ()> {
161 /// assert_eq!(value, Ok(&92));
162 /// assert_eq!(cell.get(), Some(&92))
164 #[unstable(feature = "once_cell", issue = "74465")]
165 pub fn get_or_try_init<F, E>(&self, f: F) -> Result<&T, E>
167 F: FnOnce() -> Result<T, E>,
169 if let Some(val) = self.get() {
172 /// Avoid inlining the initialization closure into the common path that fetches
173 /// the already initialized value
175 fn outlined_call<F, T, E>(f: F) -> Result<T, E>
177 F: FnOnce() -> Result<T, E>,
181 let val = outlined_call(f)?;
182 // Note that *some* forms of reentrant initialization might lead to
183 // UB (see `reentrant_init` test). I believe that just removing this
184 // `assert`, while keeping `set/get` would be sound, but it seems
185 // better to panic, rather than to silently use an old value.
186 assert!(self.set(val).is_ok(), "reentrant init");
187 Ok(self.get().unwrap())
190 /// Consumes the cell, returning the wrapped value.
192 /// Returns `None` if the cell was empty.
197 /// #![feature(once_cell)]
199 /// use std::cell::OnceCell;
201 /// let cell: OnceCell<String> = OnceCell::new();
202 /// assert_eq!(cell.into_inner(), None);
204 /// let cell = OnceCell::new();
205 /// cell.set("hello".to_string()).unwrap();
206 /// assert_eq!(cell.into_inner(), Some("hello".to_string()));
208 #[unstable(feature = "once_cell", issue = "74465")]
209 pub fn into_inner(self) -> Option<T> {
210 // Because `into_inner` takes `self` by value, the compiler statically verifies
211 // that it is not currently borrowed. So it is safe to move out `Option<T>`.
212 self.inner.into_inner()
215 /// Takes the value out of this `OnceCell`, moving it back to an uninitialized state.
217 /// Has no effect and returns `None` if the `OnceCell` hasn't been initialized.
219 /// Safety is guaranteed by requiring a mutable reference.
224 /// #![feature(once_cell)]
226 /// use std::cell::OnceCell;
228 /// let mut cell: OnceCell<String> = OnceCell::new();
229 /// assert_eq!(cell.take(), None);
231 /// let mut cell = OnceCell::new();
232 /// cell.set("hello".to_string()).unwrap();
233 /// assert_eq!(cell.take(), Some("hello".to_string()));
234 /// assert_eq!(cell.get(), None);
236 #[unstable(feature = "once_cell", issue = "74465")]
237 pub fn take(&mut self) -> Option<T> {
238 mem::take(self).into_inner()
242 #[unstable(feature = "once_cell", issue = "74465")]
243 impl<T> Default for OnceCell<T> {
244 fn default() -> Self {
249 #[unstable(feature = "once_cell", issue = "74465")]
250 impl<T: fmt::Debug> fmt::Debug for OnceCell<T> {
251 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
253 Some(v) => f.debug_tuple("OnceCell").field(v).finish(),
254 None => f.write_str("OnceCell(Uninit)"),
259 #[unstable(feature = "once_cell", issue = "74465")]
260 impl<T: Clone> Clone for OnceCell<T> {
261 fn clone(&self) -> OnceCell<T> {
262 let res = OnceCell::new();
263 if let Some(value) = self.get() {
264 match res.set(value.clone()) {
266 Err(_) => unreachable!(),
273 #[unstable(feature = "once_cell", issue = "74465")]
274 impl<T: PartialEq> PartialEq for OnceCell<T> {
275 fn eq(&self, other: &Self) -> bool {
276 self.get() == other.get()
280 #[unstable(feature = "once_cell", issue = "74465")]
281 impl<T: Eq> Eq for OnceCell<T> {}
283 #[unstable(feature = "once_cell", issue = "74465")]
284 impl<T> const From<T> for OnceCell<T> {
285 /// Creates a new `OnceCell<T>` which already contains the given `value`.
286 fn from(value: T) -> Self {
287 OnceCell { inner: UnsafeCell::new(Some(value)) }