1 //! Lazy values and one-time initialization of static data.
3 use crate::cell
::{Cell, UnsafeCell}
;
8 /// A cell which can be written to only once.
10 /// Unlike `RefCell`, a `OnceCell` only provides shared `&T` references to its value.
11 /// Unlike `Cell`, a `OnceCell` doesn't require copying or replacing the value to access it.
16 /// #![feature(once_cell)]
18 /// use std::lazy::OnceCell;
20 /// let cell = OnceCell::new();
21 /// assert!(cell.get().is_none());
23 /// let value: &String = cell.get_or_init(|| {
24 /// "Hello, World!".to_string()
26 /// assert_eq!(value, "Hello, World!");
27 /// assert!(cell.get().is_some());
29 #[unstable(feature = "once_cell", issue = "74465")]
30 pub struct OnceCell
<T
> {
31 // Invariant: written to at most once.
32 inner
: UnsafeCell
<Option
<T
>>,
35 #[unstable(feature = "once_cell", issue = "74465")]
36 impl<T
> Default
for OnceCell
<T
> {
37 fn default() -> Self {
42 #[unstable(feature = "once_cell", issue = "74465")]
43 impl<T
: fmt
::Debug
> fmt
::Debug
for OnceCell
<T
> {
44 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
46 Some(v
) => f
.debug_tuple("OnceCell").field(v
).finish(),
47 None
=> f
.write_str("OnceCell(Uninit)"),
52 #[unstable(feature = "once_cell", issue = "74465")]
53 impl<T
: Clone
> Clone
for OnceCell
<T
> {
54 fn clone(&self) -> OnceCell
<T
> {
55 let res
= OnceCell
::new();
56 if let Some(value
) = self.get() {
57 match res
.set(value
.clone()) {
59 Err(_
) => unreachable
!(),
66 #[unstable(feature = "once_cell", issue = "74465")]
67 impl<T
: PartialEq
> PartialEq
for OnceCell
<T
> {
68 fn eq(&self, other
: &Self) -> bool
{
69 self.get() == other
.get()
73 #[unstable(feature = "once_cell", issue = "74465")]
74 impl<T
: Eq
> Eq
for OnceCell
<T
> {}
76 #[unstable(feature = "once_cell", issue = "74465")]
77 impl<T
> From
<T
> for OnceCell
<T
> {
78 fn from(value
: T
) -> Self {
79 OnceCell { inner: UnsafeCell::new(Some(value)) }
84 /// Creates a new empty cell.
85 #[unstable(feature = "once_cell", issue = "74465")]
86 pub const fn new() -> OnceCell
<T
> {
87 OnceCell { inner: UnsafeCell::new(None) }
90 /// Gets the reference to the underlying value.
92 /// Returns `None` if the cell is empty.
93 #[unstable(feature = "once_cell", issue = "74465")]
94 pub fn get(&self) -> Option
<&T
> {
95 // SAFETY: Safe due to `inner`'s invariant
96 unsafe { &*self.inner.get() }
.as_ref()
99 /// Gets the mutable reference to the underlying value.
101 /// Returns `None` if the cell is empty.
102 #[unstable(feature = "once_cell", issue = "74465")]
103 pub fn get_mut(&mut self) -> Option
<&mut T
> {
104 // SAFETY: Safe because we have unique access
105 unsafe { &mut *self.inner.get() }
.as_mut()
108 /// Sets the contents of the cell to `value`.
112 /// This method returns `Ok(())` if the cell was empty and `Err(value)` if
118 /// #![feature(once_cell)]
120 /// use std::lazy::OnceCell;
122 /// let cell = OnceCell::new();
123 /// assert!(cell.get().is_none());
125 /// assert_eq!(cell.set(92), Ok(()));
126 /// assert_eq!(cell.set(62), Err(62));
128 /// assert!(cell.get().is_some());
130 #[unstable(feature = "once_cell", issue = "74465")]
131 pub fn set(&self, value
: T
) -> Result
<(), T
> {
132 // SAFETY: Safe because we cannot have overlapping mutable borrows
133 let slot
= unsafe { &*self.inner.get() }
;
138 // SAFETY: This is the only place where we set the slot, no races
139 // due to reentrancy/concurrency are possible, and we've
140 // checked that slot is currently `None`, so this write
141 // maintains the `inner`'s invariant.
142 let slot
= unsafe { &mut *self.inner.get() }
;
147 /// Gets the contents of the cell, initializing it with `f`
148 /// if the cell was empty.
152 /// If `f` panics, the panic is propagated to the caller, and the cell
153 /// remains uninitialized.
155 /// It is an error to reentrantly initialize the cell from `f`. Doing
156 /// so results in a panic.
161 /// #![feature(once_cell)]
163 /// use std::lazy::OnceCell;
165 /// let cell = OnceCell::new();
166 /// let value = cell.get_or_init(|| 92);
167 /// assert_eq!(value, &92);
168 /// let value = cell.get_or_init(|| unreachable!());
169 /// assert_eq!(value, &92);
171 #[unstable(feature = "once_cell", issue = "74465")]
172 pub fn get_or_init
<F
>(&self, f
: F
) -> &T
176 match self.get_or_try_init(|| Ok
::<T
, !>(f())) {
181 /// Gets the contents of the cell, initializing it with `f` if
182 /// the cell was empty. If the cell was empty and `f` failed, an
183 /// error is returned.
187 /// If `f` panics, the panic is propagated to the caller, and the cell
188 /// remains uninitialized.
190 /// It is an error to reentrantly initialize the cell from `f`. Doing
191 /// so results in a panic.
196 /// #![feature(once_cell)]
198 /// use std::lazy::OnceCell;
200 /// let cell = OnceCell::new();
201 /// assert_eq!(cell.get_or_try_init(|| Err(())), Err(()));
202 /// assert!(cell.get().is_none());
203 /// let value = cell.get_or_try_init(|| -> Result<i32, ()> {
206 /// assert_eq!(value, Ok(&92));
207 /// assert_eq!(cell.get(), Some(&92))
209 #[unstable(feature = "once_cell", issue = "74465")]
210 pub fn get_or_try_init
<F
, E
>(&self, f
: F
) -> Result
<&T
, E
>
212 F
: FnOnce() -> Result
<T
, E
>,
214 if let Some(val
) = self.get() {
218 // Note that *some* forms of reentrant initialization might lead to
219 // UB (see `reentrant_init` test). I believe that just removing this
220 // `assert`, while keeping `set/get` would be sound, but it seems
221 // better to panic, rather than to silently use an old value.
222 assert
!(self.set(val
).is_ok(), "reentrant init");
223 Ok(self.get().unwrap())
226 /// Consumes the cell, returning the wrapped value.
228 /// Returns `None` if the cell was empty.
233 /// #![feature(once_cell)]
235 /// use std::lazy::OnceCell;
237 /// let cell: OnceCell<String> = OnceCell::new();
238 /// assert_eq!(cell.into_inner(), None);
240 /// let cell = OnceCell::new();
241 /// cell.set("hello".to_string()).unwrap();
242 /// assert_eq!(cell.into_inner(), Some("hello".to_string()));
244 #[unstable(feature = "once_cell", issue = "74465")]
245 pub fn into_inner(self) -> Option
<T
> {
246 // Because `into_inner` takes `self` by value, the compiler statically verifies
247 // that it is not currently borrowed. So it is safe to move out `Option<T>`.
248 self.inner
.into_inner()
251 /// Takes the value out of this `OnceCell`, moving it back to an uninitialized state.
253 /// Has no effect and returns `None` if the `OnceCell` hasn't been initialized.
255 /// Safety is guaranteed by requiring a mutable reference.
260 /// #![feature(once_cell)]
262 /// use std::lazy::OnceCell;
264 /// let mut cell: OnceCell<String> = OnceCell::new();
265 /// assert_eq!(cell.take(), None);
267 /// let mut cell = OnceCell::new();
268 /// cell.set("hello".to_string()).unwrap();
269 /// assert_eq!(cell.take(), Some("hello".to_string()));
270 /// assert_eq!(cell.get(), None);
272 #[unstable(feature = "once_cell", issue = "74465")]
273 pub fn take(&mut self) -> Option
<T
> {
274 mem
::take(self).into_inner()
278 /// A value which is initialized on the first access.
283 /// #![feature(once_cell)]
285 /// use std::lazy::Lazy;
287 /// let lazy: Lazy<i32> = Lazy::new(|| {
288 /// println!("initializing");
291 /// println!("ready");
292 /// println!("{}", *lazy);
293 /// println!("{}", *lazy);
301 #[unstable(feature = "once_cell", issue = "74465")]
302 pub struct Lazy
<T
, F
= fn() -> T
> {
304 init
: Cell
<Option
<F
>>,
307 #[unstable(feature = "once_cell", issue = "74465")]
308 impl<T
: fmt
::Debug
, F
> fmt
::Debug
for Lazy
<T
, F
> {
309 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
310 f
.debug_struct("Lazy").field("cell", &self.cell
).field("init", &"..").finish()
314 impl<T
, F
> Lazy
<T
, F
> {
315 /// Creates a new lazy value with the given initializing function.
320 /// #![feature(once_cell)]
323 /// use std::lazy::Lazy;
325 /// let hello = "Hello, World!".to_string();
327 /// let lazy = Lazy::new(|| hello.to_uppercase());
329 /// assert_eq!(&*lazy, "HELLO, WORLD!");
332 #[unstable(feature = "once_cell", issue = "74465")]
333 pub const fn new(init
: F
) -> Lazy
<T
, F
> {
334 Lazy { cell: OnceCell::new(), init: Cell::new(Some(init)) }
338 impl<T
, F
: FnOnce() -> T
> Lazy
<T
, F
> {
339 /// Forces the evaluation of this lazy value and returns a reference to
342 /// This is equivalent to the `Deref` impl, but is explicit.
347 /// #![feature(once_cell)]
349 /// use std::lazy::Lazy;
351 /// let lazy = Lazy::new(|| 92);
353 /// assert_eq!(Lazy::force(&lazy), &92);
354 /// assert_eq!(&*lazy, &92);
356 #[unstable(feature = "once_cell", issue = "74465")]
357 pub fn force(this
: &Lazy
<T
, F
>) -> &T
{
358 this
.cell
.get_or_init(|| match this
.init
.take() {
360 None
=> panic
!("`Lazy` instance has previously been poisoned"),
365 #[unstable(feature = "once_cell", issue = "74465")]
366 impl<T
, F
: FnOnce() -> T
> Deref
for Lazy
<T
, F
> {
368 fn deref(&self) -> &T
{
373 #[unstable(feature = "once_cell", issue = "74465")]
374 impl<T
: Default
> Default
for Lazy
<T
> {
375 /// Creates a new lazy value using `Default` as the initializing function.
376 fn default() -> Lazy
<T
> {
377 Lazy
::new(T
::default)