1use crate::cell::UnsafeCell;
2use crate::fmt;
3use crate::marker::PhantomData;
4use crate::mem::MaybeUninit;
5use crate::panic::{RefUnwindSafe, UnwindSafe};
6use crate::sync::Once;
7
8/// A synchronization primitive which can nominally be written to only once.
9///
10/// This type is a thread-safe [`OnceCell`], and can be used in statics.
11/// In many simple cases, you can use [`LazyLock<T, F>`] instead to get the benefits of this type
12/// with less effort: `LazyLock<T, F>` "looks like" `&T` because it initializes with `F` on deref!
13/// Where OnceLock shines is when LazyLock is too simple to support a given case, as LazyLock
14/// doesn't allow additional inputs to its function after you call [`LazyLock::new(|| ...)`].
15///
16/// A `OnceLock` can be thought of as a safe abstraction over uninitialized data that becomes
17/// initialized once written.
18///
19/// [`OnceCell`]: crate::cell::OnceCell
20/// [`LazyLock<T, F>`]: crate::sync::LazyLock
21/// [`LazyLock::new(|| ...)`]: crate::sync::LazyLock::new
22///
23/// # Examples
24///
25/// Writing to a `OnceLock` from a separate thread:
26///
27/// ```
28/// use std::sync::OnceLock;
29///
30/// static CELL: OnceLock<usize> = OnceLock::new();
31///
32/// // `OnceLock` has not been written to yet.
33/// assert!(CELL.get().is_none());
34///
35/// // Spawn a thread and write to `OnceLock`.
36/// std::thread::spawn(|| {
37/// let value = CELL.get_or_init(|| 12345);
38/// assert_eq!(value, &12345);
39/// })
40/// .join()
41/// .unwrap();
42///
43/// // `OnceLock` now contains the value.
44/// assert_eq!(
45/// CELL.get(),
46/// Some(&12345),
47/// );
48/// ```
49///
50/// You can use `OnceLock` to implement a type that requires "append-only" logic:
51///
52/// ```
53/// use std::sync::{OnceLock, atomic::{AtomicU32, Ordering}};
54/// use std::thread;
55///
56/// struct OnceList<T> {
57/// data: OnceLock<T>,
58/// next: OnceLock<Box<OnceList<T>>>,
59/// }
60/// impl<T> OnceList<T> {
61/// const fn new() -> OnceList<T> {
62/// OnceList { data: OnceLock::new(), next: OnceLock::new() }
63/// }
64/// fn push(&self, value: T) {
65/// // FIXME: this impl is concise, but is also slow for long lists or many threads.
66/// // as an exercise, consider how you might improve on it while preserving the behavior
67/// if let Err(value) = self.data.set(value) {
68/// let next = self.next.get_or_init(|| Box::new(OnceList::new()));
69/// next.push(value)
70/// };
71/// }
72/// fn contains(&self, example: &T) -> bool
73/// where
74/// T: PartialEq,
75/// {
76/// self.data.get().map(|item| item == example).filter(|v| *v).unwrap_or_else(|| {
77/// self.next.get().map(|next| next.contains(example)).unwrap_or(false)
78/// })
79/// }
80/// }
81///
82/// // Let's exercise this new Sync append-only list by doing a little counting
83/// static LIST: OnceList<u32> = OnceList::new();
84/// static COUNTER: AtomicU32 = AtomicU32::new(0);
85///
86/// # const LEN: u32 = if cfg!(miri) { 50 } else { 1000 };
87/// # /*
88/// const LEN: u32 = 1000;
89/// # */
90/// thread::scope(|s| {
91/// for _ in 0..thread::available_parallelism().unwrap().get() {
92/// s.spawn(|| {
93/// while let i @ 0..LEN = COUNTER.fetch_add(1, Ordering::Relaxed) {
94/// LIST.push(i);
95/// }
96/// });
97/// }
98/// });
99///
100/// for i in 0..LEN {
101/// assert!(LIST.contains(&i));
102/// }
103///
104/// ```
105#[stable(feature = "once_cell", since = "1.70.0")]
106pub struct OnceLock<T> {
107 // FIXME(nonpoison_once): switch to nonpoison version once it is available
108 once: Once,
109 // Whether or not the value is initialized is tracked by `once.is_completed()`.
110 value: UnsafeCell<MaybeUninit<T>>,
111 /// `PhantomData` to make sure dropck understands we're dropping T in our Drop impl.
112 ///
113 /// ```compile_fail,E0597
114 /// use std::sync::OnceLock;
115 ///
116 /// struct A<'a>(&'a str);
117 ///
118 /// impl<'a> Drop for A<'a> {
119 /// fn drop(&mut self) {}
120 /// }
121 ///
122 /// let cell = OnceLock::new();
123 /// {
124 /// let s = String::new();
125 /// let _ = cell.set(A(&s));
126 /// }
127 /// ```
128 _marker: PhantomData<T>,
129}
130
131impl<T> OnceLock<T> {
132 /// Creates a new uninitialized cell.
133 #[inline]
134 #[must_use]
135 #[stable(feature = "once_cell", since = "1.70.0")]
136 #[rustc_const_stable(feature = "once_cell", since = "1.70.0")]
137 pub const fn new() -> OnceLock<T> {
138 OnceLock {
139 once: Once::new(),
140 value: UnsafeCell::new(MaybeUninit::uninit()),
141 _marker: PhantomData,
142 }
143 }
144
145 /// Gets the reference to the underlying value.
146 ///
147 /// Returns `None` if the cell is uninitialized, or being initialized.
148 /// This method never blocks.
149 #[inline]
150 #[stable(feature = "once_cell", since = "1.70.0")]
151 pub fn get(&self) -> Option<&T> {
152 if self.is_initialized() {
153 // Safe b/c checked is_initialized
154 Some(unsafe { self.get_unchecked() })
155 } else {
156 None
157 }
158 }
159
160 /// Gets the mutable reference to the underlying value.
161 ///
162 /// Returns `None` if the cell is uninitialized.
163 ///
164 /// This method never blocks. Since it borrows the `OnceLock` mutably,
165 /// it is statically guaranteed that no active borrows to the `OnceLock`
166 /// exist, including from other threads.
167 #[inline]
168 #[stable(feature = "once_cell", since = "1.70.0")]
169 pub fn get_mut(&mut self) -> Option<&mut T> {
170 if self.is_initialized() {
171 // Safe b/c checked is_initialized and we have a unique access
172 Some(unsafe { self.get_unchecked_mut() })
173 } else {
174 None
175 }
176 }
177
178 /// Blocks the current thread until the cell is initialized.
179 ///
180 /// # Example
181 ///
182 /// Waiting for a computation on another thread to finish:
183 /// ```rust
184 /// use std::thread;
185 /// use std::sync::OnceLock;
186 ///
187 /// let value = OnceLock::new();
188 ///
189 /// thread::scope(|s| {
190 /// s.spawn(|| value.set(1 + 1));
191 ///
192 /// let result = value.wait();
193 /// assert_eq!(result, &2);
194 /// })
195 /// ```
196 #[inline]
197 #[stable(feature = "once_wait", since = "1.86.0")]
198 pub fn wait(&self) -> &T {
199 self.once.wait_force();
200
201 unsafe { self.get_unchecked() }
202 }
203
204 /// Initializes the contents of the cell to `value`.
205 ///
206 /// May block if another thread is currently attempting to initialize the cell. The cell is
207 /// guaranteed to contain a value when `set` returns, though not necessarily the one provided.
208 ///
209 /// Returns `Ok(())` if the cell was uninitialized and
210 /// `Err(value)` if the cell was already initialized.
211 ///
212 /// # Examples
213 ///
214 /// ```
215 /// use std::sync::OnceLock;
216 ///
217 /// static CELL: OnceLock<i32> = OnceLock::new();
218 ///
219 /// fn main() {
220 /// assert!(CELL.get().is_none());
221 ///
222 /// std::thread::spawn(|| {
223 /// assert_eq!(CELL.set(92), Ok(()));
224 /// }).join().unwrap();
225 ///
226 /// assert_eq!(CELL.set(62), Err(62));
227 /// assert_eq!(CELL.get(), Some(&92));
228 /// }
229 /// ```
230 #[inline]
231 #[stable(feature = "once_cell", since = "1.70.0")]
232 pub fn set(&self, value: T) -> Result<(), T> {
233 match self.try_insert(value) {
234 Ok(_) => Ok(()),
235 Err((_, value)) => Err(value),
236 }
237 }
238
239 /// Initializes the contents of the cell to `value` if the cell was uninitialized,
240 /// then returns a reference to it.
241 ///
242 /// May block if another thread is currently attempting to initialize the cell. The cell is
243 /// guaranteed to contain a value when `try_insert` returns, though not necessarily the
244 /// one provided.
245 ///
246 /// Returns `Ok(&value)` if the cell was uninitialized and
247 /// `Err((&current_value, value))` if it was already initialized.
248 ///
249 /// # Examples
250 ///
251 /// ```
252 /// #![feature(once_cell_try_insert)]
253 ///
254 /// use std::sync::OnceLock;
255 ///
256 /// static CELL: OnceLock<i32> = OnceLock::new();
257 ///
258 /// fn main() {
259 /// assert!(CELL.get().is_none());
260 ///
261 /// std::thread::spawn(|| {
262 /// assert_eq!(CELL.try_insert(92), Ok(&92));
263 /// }).join().unwrap();
264 ///
265 /// assert_eq!(CELL.try_insert(62), Err((&92, 62)));
266 /// assert_eq!(CELL.get(), Some(&92));
267 /// }
268 /// ```
269 #[inline]
270 #[unstable(feature = "once_cell_try_insert", issue = "116693")]
271 pub fn try_insert(&self, value: T) -> Result<&T, (&T, T)> {
272 let mut value = Some(value);
273 let res = self.get_or_init(|| value.take().unwrap());
274 match value {
275 None => Ok(res),
276 Some(value) => Err((res, value)),
277 }
278 }
279
280 /// Gets the contents of the cell, initializing it to `f()` if the cell
281 /// was uninitialized.
282 ///
283 /// Many threads may call `get_or_init` concurrently with different
284 /// initializing functions, but it is guaranteed that only one function
285 /// will be executed if the function doesn't panic.
286 ///
287 /// # Panics
288 ///
289 /// If `f()` panics, the panic is propagated to the caller, and the cell
290 /// remains uninitialized.
291 ///
292 /// It is an error to reentrantly initialize the cell from `f`. The
293 /// exact outcome is unspecified. Current implementation deadlocks, but
294 /// this may be changed to a panic in the future.
295 ///
296 /// # Examples
297 ///
298 /// ```
299 /// use std::sync::OnceLock;
300 ///
301 /// let cell = OnceLock::new();
302 /// let value = cell.get_or_init(|| 92);
303 /// assert_eq!(value, &92);
304 /// let value = cell.get_or_init(|| unreachable!());
305 /// assert_eq!(value, &92);
306 /// ```
307 #[inline]
308 #[stable(feature = "once_cell", since = "1.70.0")]
309 pub fn get_or_init<F>(&self, f: F) -> &T
310 where
311 F: FnOnce() -> T,
312 {
313 match self.get_or_try_init(|| Ok::<T, !>(f())) {
314 Ok(val) => val,
315 }
316 }
317
318 /// Gets the mutable reference of the contents of the cell, initializing
319 /// it to `f()` if the cell was uninitialized.
320 ///
321 /// This method never blocks. Since it borrows the `OnceLock` mutably,
322 /// it is statically guaranteed that no active borrows to the `OnceLock`
323 /// exist, including from other threads.
324 ///
325 /// # Panics
326 ///
327 /// If `f()` panics, the panic is propagated to the caller, and the cell
328 /// remains uninitialized.
329 ///
330 /// # Examples
331 ///
332 /// ```
333 /// #![feature(once_cell_get_mut)]
334 ///
335 /// use std::sync::OnceLock;
336 ///
337 /// let mut cell = OnceLock::new();
338 /// let value = cell.get_mut_or_init(|| 92);
339 /// assert_eq!(*value, 92);
340 ///
341 /// *value += 2;
342 /// assert_eq!(*value, 94);
343 ///
344 /// let value = cell.get_mut_or_init(|| unreachable!());
345 /// assert_eq!(*value, 94);
346 /// ```
347 #[inline]
348 #[unstable(feature = "once_cell_get_mut", issue = "121641")]
349 pub fn get_mut_or_init<F>(&mut self, f: F) -> &mut T
350 where
351 F: FnOnce() -> T,
352 {
353 match self.get_mut_or_try_init(|| Ok::<T, !>(f())) {
354 Ok(val) => val,
355 }
356 }
357
358 /// Gets the contents of the cell, initializing it to `f()` if
359 /// the cell was uninitialized. If the cell was uninitialized
360 /// and `f()` failed, an error is returned.
361 ///
362 /// # Panics
363 ///
364 /// If `f()` panics, the panic is propagated to the caller, and
365 /// the cell remains uninitialized.
366 ///
367 /// It is an error to reentrantly initialize the cell from `f`.
368 /// The exact outcome is unspecified. Current implementation
369 /// deadlocks, but this may be changed to a panic in the future.
370 ///
371 /// # Examples
372 ///
373 /// ```
374 /// #![feature(once_cell_try)]
375 ///
376 /// use std::sync::OnceLock;
377 ///
378 /// let cell = OnceLock::new();
379 /// assert_eq!(cell.get_or_try_init(|| Err(())), Err(()));
380 /// assert!(cell.get().is_none());
381 /// let value = cell.get_or_try_init(|| -> Result<i32, ()> {
382 /// Ok(92)
383 /// });
384 /// assert_eq!(value, Ok(&92));
385 /// assert_eq!(cell.get(), Some(&92))
386 /// ```
387 #[inline]
388 #[unstable(feature = "once_cell_try", issue = "109737")]
389 pub fn get_or_try_init<F, E>(&self, f: F) -> Result<&T, E>
390 where
391 F: FnOnce() -> Result<T, E>,
392 {
393 // Fast path check
394 // NOTE: We need to perform an acquire on the state in this method
395 // in order to correctly synchronize `LazyLock::force`. This is
396 // currently done by calling `self.get()`, which in turn calls
397 // `self.is_initialized()`, which in turn performs the acquire.
398 if let Some(value) = self.get() {
399 return Ok(value);
400 }
401 self.initialize(f)?;
402
403 debug_assert!(self.is_initialized());
404
405 // SAFETY: The inner value has been initialized
406 Ok(unsafe { self.get_unchecked() })
407 }
408
409 /// Gets the mutable reference of the contents of the cell, initializing
410 /// it to `f()` if the cell was uninitialized. If the cell was uninitialized
411 /// and `f()` failed, an error is returned.
412 ///
413 /// This method never blocks. Since it borrows the `OnceLock` mutably,
414 /// it is statically guaranteed that no active borrows to the `OnceLock`
415 /// exist, including from other threads.
416 ///
417 /// # Panics
418 ///
419 /// If `f()` panics, the panic is propagated to the caller, and
420 /// the cell remains uninitialized.
421 ///
422 /// # Examples
423 ///
424 /// ```
425 /// #![feature(once_cell_get_mut)]
426 ///
427 /// use std::sync::OnceLock;
428 ///
429 /// let mut cell: OnceLock<u32> = OnceLock::new();
430 ///
431 /// // Failed attempts to initialize the cell do not change its contents
432 /// assert!(cell.get_mut_or_try_init(|| "not a number!".parse()).is_err());
433 /// assert!(cell.get().is_none());
434 ///
435 /// let value = cell.get_mut_or_try_init(|| "1234".parse());
436 /// assert_eq!(value, Ok(&mut 1234));
437 /// *value.unwrap() += 2;
438 /// assert_eq!(cell.get(), Some(&1236))
439 /// ```
440 #[inline]
441 #[unstable(feature = "once_cell_get_mut", issue = "121641")]
442 pub fn get_mut_or_try_init<F, E>(&mut self, f: F) -> Result<&mut T, E>
443 where
444 F: FnOnce() -> Result<T, E>,
445 {
446 if self.get().is_none() {
447 self.initialize(f)?;
448 }
449 debug_assert!(self.is_initialized());
450 // SAFETY: The inner value has been initialized
451 Ok(unsafe { self.get_unchecked_mut() })
452 }
453
454 /// Consumes the `OnceLock`, returning the wrapped value. Returns
455 /// `None` if the cell was uninitialized.
456 ///
457 /// # Examples
458 ///
459 /// ```
460 /// use std::sync::OnceLock;
461 ///
462 /// let cell: OnceLock<String> = OnceLock::new();
463 /// assert_eq!(cell.into_inner(), None);
464 ///
465 /// let cell = OnceLock::new();
466 /// cell.set("hello".to_string()).unwrap();
467 /// assert_eq!(cell.into_inner(), Some("hello".to_string()));
468 /// ```
469 #[inline]
470 #[stable(feature = "once_cell", since = "1.70.0")]
471 pub fn into_inner(mut self) -> Option<T> {
472 self.take()
473 }
474
475 /// Takes the value out of this `OnceLock`, moving it back to an uninitialized state.
476 ///
477 /// Has no effect and returns `None` if the `OnceLock` was uninitialized.
478 ///
479 /// Since this method borrows the `OnceLock` mutably, it is statically guaranteed that
480 /// no active borrows to the `OnceLock` exist, including from other threads.
481 ///
482 /// # Examples
483 ///
484 /// ```
485 /// use std::sync::OnceLock;
486 ///
487 /// let mut cell: OnceLock<String> = OnceLock::new();
488 /// assert_eq!(cell.take(), None);
489 ///
490 /// let mut cell = OnceLock::new();
491 /// cell.set("hello".to_string()).unwrap();
492 /// assert_eq!(cell.take(), Some("hello".to_string()));
493 /// assert_eq!(cell.get(), None);
494 /// ```
495 #[inline]
496 #[stable(feature = "once_cell", since = "1.70.0")]
497 pub fn take(&mut self) -> Option<T> {
498 if self.is_initialized() {
499 self.once = Once::new();
500 // SAFETY: `self.value` is initialized and contains a valid `T`.
501 // `self.once` is reset, so `is_initialized()` will be false again
502 // which prevents the value from being read twice.
503 unsafe { Some((&mut *self.value.get()).assume_init_read()) }
504 } else {
505 None
506 }
507 }
508
509 #[inline]
510 fn is_initialized(&self) -> bool {
511 self.once.is_completed()
512 }
513
514 #[cold]
515 #[optimize(size)]
516 fn initialize<F, E>(&self, f: F) -> Result<(), E>
517 where
518 F: FnOnce() -> Result<T, E>,
519 {
520 let mut res: Result<(), E> = Ok(());
521 let slot = &self.value;
522
523 // Ignore poisoning from other threads
524 // If another thread panics, then we'll be able to run our closure
525 self.once.call_once_force(|p| {
526 match f() {
527 Ok(value) => {
528 unsafe { (&mut *slot.get()).write(value) };
529 }
530 Err(e) => {
531 res = Err(e);
532
533 // Treat the underlying `Once` as poisoned since we
534 // failed to initialize our value.
535 p.poison();
536 }
537 }
538 });
539 res
540 }
541
542 /// # Safety
543 ///
544 /// The cell must be initialized
545 #[inline]
546 unsafe fn get_unchecked(&self) -> &T {
547 debug_assert!(self.is_initialized());
548 unsafe { (&*self.value.get()).assume_init_ref() }
549 }
550
551 /// # Safety
552 ///
553 /// The cell must be initialized
554 #[inline]
555 unsafe fn get_unchecked_mut(&mut self) -> &mut T {
556 debug_assert!(self.is_initialized());
557 unsafe { (&mut *self.value.get()).assume_init_mut() }
558 }
559}
560
561// Why do we need `T: Send`?
562// Thread A creates a `OnceLock` and shares it with
563// scoped thread B, which fills the cell, which is
564// then destroyed by A. That is, destructor observes
565// a sent value.
566#[stable(feature = "once_cell", since = "1.70.0")]
567unsafe impl<T: Sync + Send> Sync for OnceLock<T> {}
568#[stable(feature = "once_cell", since = "1.70.0")]
569unsafe impl<T: Send> Send for OnceLock<T> {}
570
571#[stable(feature = "once_cell", since = "1.70.0")]
572impl<T: RefUnwindSafe + UnwindSafe> RefUnwindSafe for OnceLock<T> {}
573#[stable(feature = "once_cell", since = "1.70.0")]
574impl<T: UnwindSafe> UnwindSafe for OnceLock<T> {}
575
576#[stable(feature = "once_cell", since = "1.70.0")]
577impl<T> Default for OnceLock<T> {
578 /// Creates a new uninitialized cell.
579 ///
580 /// # Example
581 ///
582 /// ```
583 /// use std::sync::OnceLock;
584 ///
585 /// fn main() {
586 /// assert_eq!(OnceLock::<()>::new(), OnceLock::default());
587 /// }
588 /// ```
589 #[inline]
590 fn default() -> OnceLock<T> {
591 OnceLock::new()
592 }
593}
594
595#[stable(feature = "once_cell", since = "1.70.0")]
596impl<T: fmt::Debug> fmt::Debug for OnceLock<T> {
597 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
598 let mut d: DebugTuple<'_, '_> = f.debug_tuple(name:"OnceLock");
599 match self.get() {
600 Some(v: &T) => d.field(v),
601 None => d.field(&format_args!("<uninit>")),
602 };
603 d.finish()
604 }
605}
606
607#[stable(feature = "once_cell", since = "1.70.0")]
608impl<T: Clone> Clone for OnceLock<T> {
609 #[inline]
610 fn clone(&self) -> OnceLock<T> {
611 let cell: OnceLock = Self::new();
612 if let Some(value: &T) = self.get() {
613 match cell.set(value.clone()) {
614 Ok(()) => (),
615 Err(_) => unreachable!(),
616 }
617 }
618 cell
619 }
620}
621
622#[stable(feature = "once_cell", since = "1.70.0")]
623impl<T> From<T> for OnceLock<T> {
624 /// Creates a new cell with its contents set to `value`.
625 ///
626 /// # Example
627 ///
628 /// ```
629 /// use std::sync::OnceLock;
630 ///
631 /// # fn main() -> Result<(), i32> {
632 /// let a = OnceLock::from(3);
633 /// let b = OnceLock::new();
634 /// b.set(3)?;
635 /// assert_eq!(a, b);
636 /// Ok(())
637 /// # }
638 /// ```
639 #[inline]
640 fn from(value: T) -> Self {
641 let cell = Self::new();
642 match cell.set(value) {
643 Ok(()) => cell,
644 Err(_) => unreachable!(),
645 }
646 }
647}
648
649#[stable(feature = "once_cell", since = "1.70.0")]
650impl<T: PartialEq> PartialEq for OnceLock<T> {
651 /// Equality for two `OnceLock`s.
652 ///
653 /// Two `OnceLock`s are equal if they either both contain values and their
654 /// values are equal, or if neither contains a value.
655 ///
656 /// # Examples
657 ///
658 /// ```
659 /// use std::sync::OnceLock;
660 ///
661 /// let five = OnceLock::new();
662 /// five.set(5).unwrap();
663 ///
664 /// let also_five = OnceLock::new();
665 /// also_five.set(5).unwrap();
666 ///
667 /// assert!(five == also_five);
668 ///
669 /// assert!(OnceLock::<u32>::new() == OnceLock::<u32>::new());
670 /// ```
671 #[inline]
672 fn eq(&self, other: &OnceLock<T>) -> bool {
673 self.get() == other.get()
674 }
675}
676
677#[stable(feature = "once_cell", since = "1.70.0")]
678impl<T: Eq> Eq for OnceLock<T> {}
679
680#[stable(feature = "once_cell", since = "1.70.0")]
681unsafe impl<#[may_dangle] T> Drop for OnceLock<T> {
682 #[inline]
683 fn drop(&mut self) {
684 if self.is_initialized() {
685 // SAFETY: The cell is initialized and being dropped, so it can't
686 // be accessed again. We also don't touch the `T` other than
687 // dropping it, which validates our usage of #[may_dangle].
688 unsafe { (&mut *self.value.get()).assume_init_drop() };
689 }
690 }
691}
692