$ü”¡Ä¤ A Condition VariableÁ½ËüÁLI Condition variables represent the ability to block a thread such that itÁüŽ GD consumes no CPU time while waiting for an event to occur. ConditionÁüÖ MJ variables are typically associated with a boolean predicate (a condition)Áü¤
LI and a mutex. The predicate is always verified inside of the mutex beforeÁüñ
'$ determining that thread must block.Á™Ëü�KH Note that this module places one additional restriction over the systemÁüéJG condition variables: each condvar can be used with only one mutex at aÁü´LI time. Any attempt to use multiple mutexes on the same condition variableÁü�
LI simultaneously will result in a runtime panic. However it is possible toÁüÎ
LI switch to a different mutex if there are no threads currently waiting onÁÜ› the condition variable.Á·Ëü»52 # Differences from the standard library `Condvar`ÁñËüõMJ - No spurious wakeups: A wait will only return a non-timeout result if itÁüÃ30 was woken up by `notify_one` or `notify_all`.Áü÷KH - `Condvar::notify_all` will only wake up a single thread, the rest areÁüÃLI requeued to wait for the `Mutex` to be unlocked by the thread that wasÁ|� woken up.Áü KH - Only requires 1 word of space, whereas the standard library boxes theÁüì,) `Condvar` due to platform limitations.Áü™$! - Can be statically constructed.Áü¾2/ - Does not require any drop glue when dropped.Áüñ0- - Inline fast path for the uncontended case.Á¢Ët¦ # ExamplesÁµË<¹ ```ÁüÁ&# use parking_lot::{Mutex, Condvar};Á¼è use std::sync::Arc;Á¤€ use std::thread;Á•Ëü™=: let pair = Arc::new((Mutex::new(false), Condvar::new()));Áì× let pair2 = pair.clone();ÁõËüùLI // Inside of our lock, spawn a new thread, and then wait for it to startÁÔÆ thread::spawn(move|| {Áüá,) let &(ref lock, ref cvar) = &*pair2;ÁüŽ&# let mut started = lock.lock();Áĵ *started = true;ÁÔÎ cvar.notify_one();Á<é });ÁñËüõ&# // wait for the thread to start upÁüœ'$ let &(ref lock, ref cvar) = &*pair;ÁüÄ" let mut started = lock.lock();Á”ç if !*started {Áüú cvar.wait(&mut started);Á,› }Áü¡JG // Note that we used an if instead of a while loop above. This is onlyÁüìLI // possible because parking_lot's Condvar will never spuriously wake up.Áü¹PM // This means that wait() will only return after notify_one or notify_all isÁtŠ // called.Á<™Öƒ<¬Ý>ywj"V�| Ôº,º«IdÙÝ>"#$'(+-/358;>ìØüìGD Creates a new condition variable which is ready to be waited on andÁl¸
notified.ÁåÝ>!!
"ü›" üÓ0- Wakes up one blocked thread on this condvar.ÁˆËü�*' Returns whether a thread was woken up.Á¿ËüÇIF If there is a blocked thread on this condition variable, then it willÁü•C@ be woken up from its call to `wait` or `wait_timeout`. Calls toÁüÝ-* `notify_one` are not buffered in any way.Á�Ëü—/, To wake up all threads, see `notify_all()`.ÁËËtÓµƒæË<îÖƒìú use parking_lot::Condvar;Áœ Ëü¤ ! let condvar = Condvar::new();ÁÊ ËüÒ =: // do something with condvar, share it with other threadsÁ”!Ëôœ! if !condvar.notify_one() {Áü¿!30 println!("Nobody was listening for this.");Á,÷!Ô‰<�"ÖƒT¢"ææÝ>!"!
RequeueOneÁrçHòS8Ã�Ý>àIÜ¢.$¶•&Ε&ë•&&$&Â^“—ÞÞ·sßunparked_threadsÁàrequeued_threadsÁáhave_more_threadsÁâbe_fairÁã_sealedÁ^³Úñ8‰$›Q³˜ü±4!üÉ11. Wakes up all blocked threads on this condvar.Áÿ1Ëü‡2+( Returns the number of threads woken up.Á·2Ëü¿2EB This method will ensure that any current waiters on the conditionÁü‰3HE variable are awoken. Calls to `notify_all()` are not buffered in anyÁDÖ3 way.Áã3Ëüë330 To wake up only one thread, see `notify_one()`.ÁT¸4èèÝ>ýP!Ã4!
'$Ä4ü¿68|Â6ééÝ>àIýP!Ò6!
($Ó6“,Ù6¡8(¶•)Ε)ë•))()Â^Ž—±˜ÔçA(¶•*Ε*ë•**(*Â^‹™¸˜üòJBüðEFC Blocks the current thread until this condition variable receives aÁŒ»F notification.ÁÑFËüÙFLI This function will atomically unlock the mutex specified (represented byÁüªGJG `mutex_guard`) and block the current thread. This means that any callsÁüùGJG to `notify_*()` which happen logically after the mutex is unlocked areÁüÈHKH candidates to wake this thread up. When this function call returns, theÁü˜I.+ lock specified will have been re-acquired.ÁËIËdÓI # PanicsÁäIËüìIJG This function will panic if another thread is waiting on the `Condvar`Áü»J$! with a different `Mutex` object.Á$ùJêëìêÝ>ëççÌë“ì‡
½^HPbïAì¬BðDÔ^!™,,‰K!ªâðDþJ
+ðD$ŠKmutex_guardÁ\�K%'üñTŽü›LIF Waits on this condition variable for a notification, timing out afterÁüéL the specified time instant.Á�MËü•MIF The semantics of this function are equivalent to `wait()` except thatÁüãMGD the thread will be blocked roughly until `timeout` is reached. ThisÁü¯NIF method should not be used for precise timing due to anomalies such asÁüýNEB preemption or platform differences that may not cause the maximumÁüÇO41 amount of time waited to be precisely `timeout`.Á€PËüˆPGD Note that the best effort is made to ensure that the time waited isÁüÔPLI measured with a monotonic clock, and not affected by the changes made toÁ¤¥Q the system time.Á¾QËüÆQFC The returned `WaitTimeoutResult` value indicates if the timeout isÁÔ‘R known to have elapsed.Á°RËü¸RJG Like `wait`, the lock specified will be re-acquired when this functionÁü‡S>; returns, regardless of whether the timeout elapsed or not.ÁÊSËdÒS�£ãSËüëSJ£üºT$€¤TøTíîïíÝ>îççÌë“ì‡
5ðDá»$Âvé¥\Ðv conditionÁL�w±°<—wˆŠ„†üÄ��ü¬zFŠŸü÷zJG notification. If the provided condition evaluates to `false`, then theÁüÆ{FC thread is no longer blocked and the operation is completed. If theÁü‘|GD condition evaluates to `true`, then the thread is blocked again andÁüÝ|A> waits for another notification before repeating this process.Á£}Ëü«}LýŸüü}JÒ üË~J¥¡üšKø¡üê.Ì¢�€Ëd¥€�£¶€Ëü¾€J£ü��$€¤TË�úûüúÝ>ûççÌë“ì‡
O$™ŸtöTúRTVYždè›PQüÑ#¬ñü÷WT A mutual exclusive primitive that is always fair, useful for protecting shared dataÁÏËüÓOL This mutex will block threads waiting for the lock to become available. TheÁü£?< mutex can be statically initialized or created by the `new`ÁüãOL constructor. Each mutex has a type parameter which represents the data thatÁü³KH it is protecting. The data can only be accessed through the RAII guardsÁüÿOL returned from `lock` and `try_lock`, which guarantees that the data is onlyÁüÏ+( ever accessed when the mutex is locked.ÁûËüÿFC The regular mutex provided by `parking_lot` uses eventual fairnessÁüÆIF (after some time it will default to the fair algorithm), but eventualÁü�NK fairness does not provide the same guarantees an always fair method would.Áüß<9 Fair mutexes are generally slower, but sometimes needed.Áœ Ëü OL In a fair mutex the waiters form a queue, and the lock is always granted toÁüð NK the next requester in the queue, in first-in first-out order. This ensuresÁü¿
OL that one thread cannot starve others by quickly re-acquiring the lock afterÁŒ� releasing it.Á¡Ëü¥^[ A fair mutex may not be interesting if threads have different priorities (this is known asÁÄ„ priority inversion).Á�Ëü¡30 # Differences from the standard library `Mutex`ÁÕËüÙ;8 - No poisoning, the lock is released normally on panic.Áü•
KH - Only requires 1 byte of space, whereas the standard library boxes theÁüá
.+ `FairMutex` due to platform limitations.Áü�$Š‚üµ2·‚üè0ò‚ü™EB - Efficient handling of micro-contention using adaptive spinning.Áüß52 - Allows raw locking & unlocking without a guard.Á•Ët™µƒ¨Ë<¬Öƒü´ use parking_lot::FairMutex;ÁüÔ(% use std::sync::{Arc, mpsc::channel};Á¤ý³„’ËÄ– const N: usize = 10;Á¯Ëü³OL // Spawn a few threads to increment a shared variable (non-atomically), andÁüƒ=: // let the main thread know once all increments are done.Á4Á //ÁüÈQN // Here we're using an Arc to share memory among threads, and the data insideÁüš)& // the Arc is protected with a mutex.ÁüÄ+( let data = Arc::new(FairMutex::new(0));ÁðËìô let (tx, rx) = channel();Á¤’ for _ in 0..10 {Áü§96 let (data, tx) = (Arc::clone(&data), tx.clone());Áüá thread::spawn(move || {Áü�KH // The shared state can only be accessed once the lock is held.ÁüÍMJ // Our non-atomic increment is safe because we're the only threadÁü›GD // which can access the shared state when the lock is held.Áüã'$ let mut data = data.lock();Á¼‹ *data += 1;ÁÜ£ if *data == N {Áü¿%" tx.send(()).unwrap();Álå
½^HPbïAÚãAôüêMOü˜!$üŸOL An RAII mutex guard returned by `FairMutexGuard::map`, which can point to aÁüï# subfield of the protected data.Á“Ëü—WT The main difference between `MappedFairMutexGuard` and `FairMutexGuard` is that theÁüïKH former doesn't support temporarily unlocking and re-locking, since thatÁü» PM could introduce soundness issues if the locked object is modified by anotherÁ\Œ! thread.Á¤¡!ÚZ™[[Zìüº!ïïßó@ô—Jõ‡
ì2ò<âª}AÚãAôü¶!WYL†,Š^`be”DãÃ\]ÔÑŒæüîB? A mutual exclusion primitive useful for protecting shared dataÁ±ËüµOçÞü…?¿ßüÅO‡àü•KßàüáO³áü±+‹âÝËtá # FairnessÁðËüôOL A typical unfair lock can often end up in a situation where a single threadÁüÄPM quickly acquires and releases the same mutex in succession, which can starveÁü•NK other threads waiting to acquire the mutex. While this improves throughputÁüäOL because it doesn't force a context switch when a thread tries to re-acquireÁü´ @= a mutex it has just released, this can starve other threads.Áõ Ëüù QN This mutex uses [eventual fairness](https://trac.webkit.org/changeset/203350)ÁüË
GD to ensure that the lock will be fair on average without sacrificingÁü“MJ throughput. This is done by forcing a fair unlock on average every 0.5ms,ÁüáMJ which will force the lock to go to the next thread waiting for the mutex.Á¯Ëü³MJ Additionally, any critical section longer than 1ms will always use a fairÁü�
NK unlock, which has a negligible impact on throughput considering the lengthÁäÐ
½^HPbïAÚ¬Bôü¸!MOüÖ$ üé!KH An RAII mutex guard returned by `MutexGuard::map`, which can point to aÁüµ"#»ýÙ"ËüÝ"OL The main difference between `MappedMutexGuard` and `MutexGuard` is that theÁü#KÒþüù#P¦ÿ\Ê$þÿ„ß$Úf™ggfìüô$ïïßó@ô—Jõ‡
EB Returns whether the associated `Once` has successfully executed aÁd÷
closure.Á$�Î?zz
|$¢;2üãC@ A synchronization primitive which can be used to run a one-timeÁü§JG initialization. Useful for one-time initialization for globals, FFI orÁÔò related functionality.Á�
Ëü‘
2/ # Differences from the standard library `Once`ÁÄ
ƒÐº$÷$þý$BDÄ&ƒ¶•…Ε…ë•……ƒ…кÎ?Ô^ø°ú°û°Ðü°ý°�þ°ìH�ˈXêE>кüÚ*Nüþ&GD Performs the same function as `call_once` except ignores poisoning.ÁÊ'ËüÒ'HE If this `Once` has been poisoned (some initialization panicked) thenÁüŸ(KH this function will continue to attempt to call initialization functionsÁüï($! until one of them doesn't panic.Á˜)Ëü )IF The closure `f` is yielded a structure which can be used to query theÁüî)KH state of this `Once` (whether initialization has previously panicked orÁ
\Î<Òåæëíïò”DãÃßàNonZeroUsizeÁdüº’ßáÄ$™ßãGetThreadIdÁ\ŸÞßäÔÑl¼ñQìŽADŽ(*´üü®MJ Implementation of the `GetThreadId` trait for `lock_api::ReentrantMutex`.Á\‡€Dău^´wæ�'åå€Dü•'€Dèéßàé¼Ã$Éçç€Düï+Œòææ€D£ £ ¤ Ϧ ì€ ™‘‹ÖqËîýPç„ç
é$…Ù鶕êΕêë•êêéêøMÕ°Ô^Ôµüê?< A mutex which can be recursively locked by a single thread.Áª Ëü® FC This type is identical to `Mutex` except for the following points:Áõ Ëüù PM - Locking multiple times from the same thread will work correctly instead ofÁ”Ê
PM - `ReentrantMutexGuard` does not give mutable references to the locked data.Áü®'$ Use a `RefCell` if you need this.ÁÖËüÚKH See [`Mutex`](crate::Mutex) for more details about the underlying mutexÁt¦ primitive.Át¾™ììè÷ÍÛaü¢Bü‡
