111 lines
54 KiB
Plaintext
111 lines
54 KiB
Plaintext
|
rust
|
|||
|
|
RØ #rustc 1.96.0 (ac68faa20 2026-05-25)ÁíàÄTËŸ ÜJîÄ)'ß\¥! -3d1337db07d0b3aeÁ ¤°ð ¾ä-±($²ï=©Ã -7e98a21bfd32b0edÁ‰ í$ò ‚ $Ì »À|Ò ¼Ë portable_atomicÁ|ª »¯Üÿ atomicÁ4¸ »¯Üƒ barrierÁ<˜ »ðœÇ lazyÁ$ò »�„§ testsÁ,ëU‚ $àU ticketÁ4â» ticket_mutexÁć TicketMutexÁ\Ú»ÑÄð TicketMutexGuardÁ„ç»Ñ&( fairÁ$Ø »
|
|||
|
|
fair_mutexÁ´� FairMutexÁLÈ
|
|||
|
|
»¼´ä FairMutexGuardÁtÓ
|
|||
|
|
»¼$&
|
|||
|
|
StarvationÁTã
|
|||
|
|
»¼BD
|
|||
|
|
InnerMutexÁTé» use_ticket_mutexÁäÅ InnerMutexGuardÁ|Ç»Åä£ onceÁ$£ »„„Ø ² YieldÁ,Õ»À|‰ rwlockÁ4� »º”¾ Ÿ,Ò »À|‚ Ó|Ü »º”… BarrierÁ<ì »ðœš LazyÁ$—$ »�„Ë# OnceÁ$•+ »„„É* Ò4ß. »º”�. RwLockUpgradableGuardÁ¬Ï2 »º”ÿ1 Ô„®6 »º”Þ5 lock_apiÁD´8 »ª¤á7 ”,ëG »¼´ÏG í mutexÁ spinÁ
|
|||
|
|
|
|||
|
|
SpinMutexÁ ¥ £ phantomÁ lockÁ dataÁ SpinMutexGuardÁ 'aÁ ¥ í ø ¥ £ "¥ "£ %¥ '¥ )¥ )£ )æ )
|
|||
|
|
into_innerÁ )
|
|||
|
|
as_mut_ptrÁ /¥ /£ /í 3¥ 3£ 3 is_lockedÁ 3 force_unlockÁ 3 try_lockÁ 3 get_mutÁ :¥ :£ :× = = @¥ @£ @> D¥ D£ D÷
|
|||
|
|
H˜ H¥ H leakÁ L˜ L¥ L× P˜ P¥ P×
|
|||
|
|
T˜ T¥ Tå T´ Y˜ Y¥ Y¶ ]˜ ]¥ ]ã
|
|||
|
|
¯ l¥ l£ ß o˜ o¥ ¤ r¥ r£ r innerÁ v¥ v£ y¥ y£ ¥ |˜ |¥ |ô
|
|||
|
|
€¥ €£ €æ €‰
|
|||
|
|
…¥ …£ …í ‰¥ ‰£ ‰Ö
|
|||
|
|
‰æ
|
|||
|
|
‰ù
|
|||
|
|
Ž ‰ˆ ‘¥ ‘£ ‘× •¥ •£ •> ™¥ ™£ ™÷ �˜ �¥ �ú ¡˜ ¡¥ ¡×
|
|||
|
|
¥˜ ¥¥ ¥× ©˜ ©¥ ©å ©´ ®˜ ®¥ ®¶ relaxÁ ²
|
|||
|
|
RelaxStrategyÁ ³ ² SpinÁ µ
|
|||
|
|
² · ² LoopÁ ¹
|
|||
|
|
²» ¤ Á¥ %
|
|||
|
|
'
|
|||
|
|
.
|
|||
|
|
2
|
|||
|
|
6
|
|||
|
|
7
|
|||
|
|
8
|
|||
|
|
9
|
|||
|
|
=
|
|||
|
|
=
|
|||
|
|
=
|
|||
|
|
O
|
|||
|
|
O
|
|||
|
|
O
|
|||
|
|
S
|
|||
|
|
S
|
|||
|
|
S
|
|||
|
|
X
|
|||
|
|
\
|
|||
|
|
`
|
|||
|
|
ˆ
|
|||
|
|
Œ
|
|||
|
|
�
|
|||
|
|
Ž
|
|||
|
|
�
|
|||
|
|
”
|
|||
|
|
”
|
|||
|
|
”
|
|||
|
|
¤
|
|||
|
|
¤
|
|||
|
|
¤
|
|||
|
|
¨
|
|||
|
|
¨
|
|||
|
|
¨
|
|||
|
|
|
|||
|
|
±
|
|||
|
|
³� Á ß í ø æk–
|
|||
|
|
Swø ¥£ ÌìÇ � ƒ í ø ŸÇ.øœ& 8¥ Ìì£ ¿cÇ ³ Ç é Ç… ¿c ƒ í ø ŸÇ.øœ& ˜ Ü Äc• é!• ö!• Œ"• � r r ¤ uô
|
|||
|
|
SG,¬,Ì…‹ Ìì� ¿c� ³ � é �… ¿c | | ¥ ô
|
|||
|
|
b~,Ž8‘
|
|||
|
|
˜ Ü Äcä é!ä ö!ä ³ µ µ ¶Ê tôp(æh&' ³ ¹ ¹ ºè vŽx*Ñ¿` % v r" ' y r: L ‘ r¡ |@ • rD ™ rP ¥ |T © |Y ® |] · µ» ¹� ~Ìì¿c³ é Äc é! ö! Œ" ³´ë
|
|||
|
|
& ,
|
|||
|
|
3 |ë
|
|||
|
|
¶] ,û Z ¬• $¥ -
|
|||
|
|
4 |•
|
|||
|
|
õ0… E V © \Á • ‹ üÍŠ …‹ Ö Ý ü¡¼ Ü , 3 Ç $¾ … $² ¤]¤] V ¦]Á‚] üß3ø¤”& › î0î0
|
|||
|
|
UnsafeCellÁ ð0»Ì- ·}—KEüC£… } … } • • – PhantomDataÁ Fu\»Ÿ‹ \ ø øÇ ´à# ,ð#
|
|||
|
|
" |à#
|
|||
|
|
,…‹ 5 F õ# üÆ#; r …‹ €$ ‡$ ü™#n ƒ � $·# … ,ª# Ç ± … ° » I ²Áí Ô4õ ‚] ¥Tð | ½lé ³ ¿Ê$ø µ ÀÊ ¶ Àü ¼K üz\ Y This crate provides [spin-based](https://en.wikipedia.org/wiki/Spinlock) versions of theÁ ü×` ] primitives in `std::sync` and `std::lazy`. Because synchronization is done through spinning,Á ü¸A > the primitives are suitable for use in `no_std` environments.Á ú ú tþ # FeaturesÁ � ú ü‘J G - `Mutex`, `RwLock`, `Once`/`SyncOnceCell`, and `SyncLazy` equivalentsÁ Ü ú üà' $ - Support for `no_std` environmentsÁ ˆ ú üŒC @ - [`lock_api`](https://crates.io/crates/lock_api) compatibilityÁ Ð ú üÔ! - Upgradeable `RwLock` guardsÁ ö ú üú3 0 - Guards can be sent and shared between threadsÁ ® ú œ² - Guard leakingÁ Æ ú ”Ê - Ticket locksÁ Ý ú üá6 3 - Different strategies for dealing with contentionÁ ˜ ú üœ# # Relationship with `std::sync`Á À ú üÄB ? While `spin` is not a drop-in replacement for `std::sync` (andÁ ü‡o l [should not be considered as such](https://matklad.github.io/2020/01/02/spinlocks-considered-harmful.html))Á ü÷P M an effort is made to keep this crate reasonably consistent with `std::sync`.Á È ú üÌh e Many of the types defined in this crate have 'additional capabilities' when compared to `std::sync`:Á µ ú ü¹ i f - Because spinning does not depend on the thread-driven model of `std::sync`, guards ([`MutexGuard`],Á ü£
|
|||
|
|
^ [ [`RwLockReadGuard`], [`RwLockWriteGuard`], etc.) may be sent and shared between threads.Á ‚ ú ü† T Q - [`RwLockUpgradableGuard`] supports being upgraded into a [`RwLockWriteGuard`].Á Û ú üß O L - Guards support [leaking](https://doc.rust-lang.org/nomicon/leaking.html).Á ¯ ú ü³ F C - [`Once`] owns the value returned by its `call_once` initializer.Á ú ú üþ 7 4 - [`RwLock`] supports counting readers and writers.Á ¶
|
|||
|
|
ú üº
|
|||
|
|
Y V Conversely, the types in this crate do not have some of the features `std::sync` has:Á ” ú ü˜] Z - Locks do not track [panic poisoning](https://doc.rust-lang.org/nomicon/poisoning.html).Á ö ú ¤ú ## Feature flagsÁ � ú ü“F C The crate comes with a few feature flags that you may wish to use.Á Ú ú üÞT Q - `lock_api` enables support for [`lock_api`](https://crates.io/crates/lock_api)Á ³ ú ü·I F - `ticket_mutex` uses a ticket lock for the implementation of `Mutex`Á � ú ü…b _ - `fair_mutex` enables a fairer implementation of `Mutex` that uses eventual fairness to avoidÁ „è
|
|||
|
|
starvationÁ ù ú üýC @ - `std` enables support for thread yielding instead of spinningÁ ²Áí" Ô# ‚] ¥" | ½! ³ ¿Ê µ ÀÊ1 ¶ À‰ ”é ‚ là ü 2 / Locks that have the same behaviour as a mutex.Á 3ú ü7_ \ The [`Mutex`] in the root of the crate, can be configured using the `ticket_mutex` feature.Á ü—^ [ If it's enabled, [`TicketMutex`] and [`TicketMutexGuard`] will be re-exported as [`Mutex`]Á üöR O and [`MutexGuard`], otherwise the [`SpinMutex`] and guard will be re-exported.Á Éú üÍ* ' `ticket_mutex` is disabled by default.Á øú üü# [`Mutex`]: ../struct.Mutex.htmlÁ ü - * [`MutexGuard`]: ../struct.MutexGuard.htmlÁ üÎ. + [`TicketMutex`]: ./struct.TicketMutex.htmlÁ üý8 5 [`TicketMutexGuard`]: ./struct.TicketMutexGuard.htmlÁ ü¶* ' [`SpinMutex`]: ./struct.SpinMutex.htmlÁ üá4 1 [`SpinMutexGuard`]: ./struct.SpinMutexGuard.htmlÁ »òŒþ Ìø ,Ë lor|ÁLä bƒ tï clý
|
|||
|
|
³ e ¿Ê$Œ µ f ÀÊ ¶ f À× £ ` hr,² é! j DerefMutÁD¹ ö! kdì ä A naïve spinning mutex.Á ú ü!r o Waiting threads hammer an atomic variable until it becomes available. Best-case latency is low, but worst-caseÁ ü”& # latency is theoretically infinite.Á »
|
|||
|
|
spin_mutexÁ´�ô— $ô
|
|||
|
|
AtomicBoolÁTÖ ¬] ®Dâ ¼À lñ ³
|
|||
|
|
¿Ê$€ µ ÀÊ ¶ Àî TŸ î0
|
|||
|
|
× ¯ ` º \À • º – ManuallyDropÁdÖ ÃÛ r,î é! »>Dõ ö! ,ÀœÀõ÷åçÒÔ$�„™°Ÿ¡œ¸”ŒÑhü�^\^MOüý ) ü„h e A [spin lock](https://en.m.wikipedia.org/wiki/Spinlock) providing mutually exclusive access to data.Á íú lñ
|
|||
|
|
# ExampleÁ ÿú <ƒ ```Á l‹
|
|||
|
|
use spin;Á ™ú ü�3 0 let lock = spin::mutex::SpinMutex::<_>::new(0);Á Ñú ´Õ // Modify the dataÁ ¬ì *lock.lock() = 2;Á ‚ú ¤† // Read the dataÁ ô› let answer = *lock.lock();Á Ôº assert_eq!(answer, 2);Á <ÕÒD Ýú Üá # Thread safety exampleÁ ýú <�ÒD l‰âD ü—" use std::sync::{Arc, Barrier};Á ºú ä¾ let thread_count = 1000;Á üÛC @ let spin_mutex = Arc::new(spin::mutex::SpinMutex::<_>::new(0));Á Ÿú ü£G D // We use a barrier to ensure the readout happens after all writingÁ üë; 8 let barrier = Arc::new(Barrier::new(thread_count + 1));Á §ú ô« # let mut ts = Vec::new();Á üÊ for _ in (0..thread_count) {Á üë) & let my_barrier = barrier.clone();Á ü• ) & let my_lock = spin_mutex.clone();Á l¿
|
|||
|
|
# let t =Á üÍ $ ! std::thread::spawn(move || {Á üò + ( let mut guard = my_lock.lock();Á Äž
|
|||
|
|
*guard += 1;Á ·
|
|||
|
|
ú ü»
|
|||
|
|
5 2 // Release the lock to prevent a deadlockÁ Äñ
|
|||
|
|
drop(guard);Á ôŠ my_barrier.wait();Á \© });Á Œµ # ts.push(t);Á ,Ç }Á Í ú œÑ barrier.wait();Á å ú üé ( % let answer = { *spin_mutex.lock() };Á ü’ % " assert_eq!(answer, thread_count);Á ¸ ú œ¼ # for t in ts {Á äÐ # t.join().unwrap();Á <í # }Á <õ ÒD Lˆ
|
|||
|
|
¥ £ Îì… ’
|
|||
|
|
Íì‹ D�
|
|||
|
|
Ç æk–
|
|||
|
|
Swø .0 + �
|
|||
|
|
¼ ¼
|
|||
|
|
<
|
|||
|
|
¬ ÜÊ
|
|||
|
|
$Õ
|
|||
|
|
° œë
|
|||
|
|
$ë
|
|||
|
|
ä üö- üƒ. + A guard that provides mutable data access.Á ²ú ü¶? < When the guard falls out of scope it will release the lock.Á t� ˜ ¥ ÎìÜ ” Ü ˜ • ŸÇ.øœ& `�35 ¤ª$ª ˜ ° dÄ$Ä Üü€9 ¥ £ ! ! õQ Œ …R ž Ìì… $˜Ç $& ü½9 ¥ # £ $ # $ õQ É …R Û ŽV$ÕÇ üû< 8 à ¥ & à & ÐT ‡ � Ü $“£ ü»< 8 Ä ¥ ( Ä ( ÐT Ç ÌìÜ $Ó£ Ôü ¥ * £ + * + Íì… � …R „Ç,-. ü¡! ü�; 8 Creates a new [`SpinMutex`] wrapping the supplied data.Á Ýú lå°D ÷ú <ÿÒD ü‹ use spin::mutex::SpinMutex;Á ¯ú ü·: 7 static MUTEX: SpinMutex<()> = SpinMutex::<_>::new(());Á öú |þ fn demo() {Á ü’ let lock = MUTEX.lock();Á ü·! // do something with lockÁ œÝ drop(lock);Á ,õÇN <ÿÒD ® …Ç ) ) ¸ ø*äÜ üã@ = Consumes this [`SpinMutex`] and unwraps the underlying data.Á ¨ú l°°D Âú <ÊÒD üÖ4 1 let lock = spin::mutex::SpinMutex::<_>::new(42);Á ü�& # assert_eq!(42, lock.into_inner());Á <ºÒDTã Ç… ) )
|
|||
|
|
-…‹$îüÐ " üÃ5 2 Returns a mutable pointer to the underlying data.Á ýú ü…^ [ This is mostly meant to be used for applications which require manual unlocking, but whereÁ üèM J storing both the lock and the pointer to the inner data gets inefficient.Á º ú l °D <Ô ÒD üà 4÷\ ™ ú d¡ unsafe {Á ü² ' $ core::mem::forget(lock.lock());Á Þ ú üæ 1 . assert_eq!(lock.as_mut_ptr().read(), 42);Á üœ $ ! lock.as_mut_ptr().write(58);Á Å ú äÍ lock.force_unlock();Á ,î ÇN ø ú ü€ ! assert_eq!(*lock.lock(), 58);Á ¦ ú <® ÒDT× Å ÅÇ … ) â )
|
|||
|
|
.…‹$ã ü– 1 ¥ 0 £ 1 1 0 õQ › …R ¦ ³‹ l© Ç2 ! %' üƒ%' üÎ V S Locks the [`SpinMutex`] and returns a guard that permits access to the inner data.Á ©!ú ü±!: 7 The returned value may be dereferenced for data accessÁ üð!C @ and the lock will be dropped when the guard falls out of scope.Á ¸"ú <À"ÒD üÌ"3…E ,„# {Á üŽ## let mut data = lock.lock();Á ü¶#> ; // The lock is now locked and the data can be accessedÁ œù# *data += 1;Á ü‘$A > // The lock is implicitly dropped at the end of the scopeÁ ,×$ÇN <á$ÒD$Š% Æ ÆÇ ƒ í ø ŸÇ.øœ& Æ… / �% /
|
|||
|
|
2…‹$�%üê)" ¥ 4 £ 5 5 4 õQ ï) …R ú)Ç6789 üê, ü“*1 . Returns `true` if the lock is currently held.Á É*ú dÑ* # SafetyÁ â*ú üê*m j This function provides no synchronization guarantees and so its result should be considered 'out of date'Á üÜ+s p the instant it is called. Do not use it for synchronization purposes. However, it may
|
|||
|
|
` £c bufÁ ` àB¤GS
|
|||
|
|
ÍÖ¿Ù¿ Ú¿« Û¿ˆ Ü¿ Ý¿Þ¿ˆ ‚†f|Â
|
|||
|
|
¤rŸÈŸÈ È ErrorÁ O˜éBL : £? :
|
|||
|
|
=…‹$¤?± ª?$Å@ = <closure_kind>Á > <closure_signature>Á > <upvars>Á > > = >…‹ ¤rï~ ƒ í ø ŸÇ.øœ& … c c ˆ ¢cµ
|
|||
|
|
` £cÈ} ` àB¤GS
|
|||
|
|
$ö@ =¶ ? Î ? ë ? ? = ?…‹”�Þ�ü×A8 ¥ A £ B A B õQ ÜA …R ñA ³ … <èAÇC ´ C &( ,. ¤–B<™B Ç @ @
|
|||
|
|
C…‹üÜB& ¥ E £ F E F ÛX áB …R äBÇG ë G ĉC$ŒC …Ç D D
|
|||
|
|
G…‹ø$‘CüÅC) ˜ I ¥ J J I ÐT ÎC•K ÊC ü¡G$ üõCM J Leak the lock guard, yielding a mutable reference to the underlying data.Á ÇDú üÏDM J Note that this function will permanently lock the original [`SpinMutex`].Á ¡Eú <©EÒD üµE5 2 let mylock = spin::mutex::SpinMutex::<_>::new(0);Á ïEú ü÷EJ G let data: &mut i32 = spin::mutex::SpinMutexGuard::leak(mylock.lock());Á ÆFú tÎF *data = 1;Á ÌáF assert_eq!(*data, 1);Á <ÿFÒD$¨G • ˜ Ü H H
|
|||
|
|
K ˜ Ü thisÁ$Gü¥IE ˜ M ¥ N M N ÐT ®I ¿cÜ TºI•O Àc O ªI%' üñI4 ôI Î Ï Ð Î• Ï c c ˆ ¢cµ
|