1 // Copyright 2014 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
11 //! A "once initialization" primitive
13 //! This primitive is meant to be used to run one-time initialization. An
14 //! example use case would be for initializing an FFI library.
21 use sync::{StaticMutex, MUTEX_INIT};
23 /// A synchronization primitive which can be used to run a one-time global
24 /// initialization. Useful for one-time initialization for FFI or related
25 /// functionality. This type can only be constructed with the `ONCE_INIT`
31 /// use std::sync::{Once, ONCE_INIT};
33 /// static START: Once = ONCE_INIT;
35 /// START.call_once(|| {
36 /// // run initialization here
42 cnt: atomic::AtomicInt,
43 lock_cnt: atomic::AtomicInt,
46 unsafe impl Sync for Once {}
48 /// Initialization value for static `Once` values.
50 pub const ONCE_INIT: Once = Once {
52 cnt: atomic::ATOMIC_INT_INIT,
53 lock_cnt: atomic::ATOMIC_INT_INIT,
57 /// Perform an initialization routine once and only once. The given closure
58 /// will be executed if this is the first time `call_once` has been called,
59 /// and otherwise the routine will *not* be invoked.
61 /// This method will block the calling task if another initialization
62 /// routine is currently running.
64 /// When this function returns, it is guaranteed that some initialization
65 /// has run and completed (it may not be the closure specified).
67 pub fn call_once<F>(&'static self, f: F) where F: FnOnce() {
68 // Optimize common path: load is much cheaper than fetch_add.
69 if self.cnt.load(atomic::SeqCst) < 0 {
73 // Implementation-wise, this would seem like a fairly trivial primitive.
74 // The stickler part is where our mutexes currently require an
75 // allocation, and usage of a `Once` shouldn't leak this allocation.
77 // This means that there must be a deterministic destroyer of the mutex
78 // contained within (because it's not needed after the initialization
81 // The general scheme here is to gate all future threads once
82 // initialization has completed with a "very negative" count, and to
83 // allow through threads to lock the mutex if they see a non negative
84 // count. For all threads grabbing the mutex, exactly one of them should
85 // be responsible for unlocking the mutex, and this should only be done
86 // once everyone else is done with the mutex.
88 // This atomicity is achieved by swapping a very negative value into the
89 // shared count when the initialization routine has completed. This will
90 // read the number of threads which will at some point attempt to
91 // acquire the mutex. This count is then squirreled away in a separate
92 // variable, and the last person on the way out of the mutex is then
93 // responsible for destroying the mutex.
95 // It is crucial that the negative value is swapped in *after* the
96 // initialization routine has completed because otherwise new threads
97 // calling `call_once` will return immediately before the initialization
100 let prev = self.cnt.fetch_add(1, atomic::SeqCst);
102 // Make sure we never overflow, we'll never have int::MIN
103 // simultaneous calls to `call_once` to make this value go back to 0
104 self.cnt.store(int::MIN, atomic::SeqCst);
108 // If the count is negative, then someone else finished the job,
109 // otherwise we run the job and record how many people will try to grab
111 let guard = self.mutex.lock();
112 if self.cnt.load(atomic::SeqCst) > 0 {
114 let prev = self.cnt.swap(int::MIN, atomic::SeqCst);
115 self.lock_cnt.store(prev, atomic::SeqCst);
119 // Last one out cleans up after everyone else, no leaks!
120 if self.lock_cnt.fetch_add(-1, atomic::SeqCst) == 1 {
121 unsafe { self.mutex.destroy() }
126 #[deprecated = "renamed to `call_once`"]
127 pub fn doit<F>(&'static self, f: F) where F: FnOnce() { self.call_once(f) }
135 use super::{ONCE_INIT, Once};
136 use sync::mpsc::channel;
140 static O: Once = ONCE_INIT;
142 O.call_once(|| a += 1);
144 O.call_once(|| a += 1);
150 static O: Once = ONCE_INIT;
151 static mut run: bool = false;
153 let (tx, rx) = channel();
154 for _ in range(0u, 10) {
156 Thread::spawn(move|| {
157 for _ in range(0u, 4) { Thread::yield_now() }
165 tx.send(()).unwrap();
177 for _ in range(0u, 10) {