43 lines
21 KiB
Plaintext
43 lines
21 KiB
Plaintext
|
rust
|
|||
|
|
ÚS #rustc 1.96.0 (ac68faa20 2026-05-25)ÁíàÄTËŸ ÜJîÄ)'ß\¥! -3d1337db07d0b3aeÁ ¤°ð ¾ä-±($²ï=©Ã -7e98a21bfd32b0edÁ‰ OnUnwindÁDÀ6 » use_stdÁœ�6 OnSuccessÁLà7 »žœ°7 defer_on_successÁ„§? »žœô> defer_on_unwindÁ|²B »žœÿA guard_on_successÁ„”[ »žœáZ guard_on_unwindÁ|öb »žœÃb testsÁ,¤n ‚ $™n í À StrategyÁ
|
|||
|
|
should_runÁ
|
|||
|
|
¾ deferÁ
|
|||
|
|
ScopeGuardÁ ¥ — ¤ » dropfnÁ strategyÁ ¥ — ¤
|
|||
|
|
with_strategyÁ
|
|||
|
|
into_innerÁ £ ¥ — ¥ — ¤ $¥ $— $¤ $å $´ *¥ *— *¤ *¶ /¥ /— /¤ /ã 4¥ 4— 4¤ 4× AlwaysÁ :× )
|
|||
|
|
.
|
|||
|
|
3
|
|||
|
|
8
|
|||
|
|
8
|
|||
|
|
8
|
|||
|
|
;
|
|||
|
|
;
|
|||
|
|
;
|
|||
|
|
¿c 9 u+Æøõd à � æ » “ Ü'6šÞ¬h ¥—¤ é!… ö!… Œ"… ¿c… : 94
|
|||
|
|
9 $ * / ¿c#
|
|||
|
|
� é!ö!Œ" 9í À Í0 × Ü0 ` PhantomDataÁ\ò0 • ù – ManuallyDropÁd�1 ÃÛ r,ª1 é! DerefMutÁD±1 ö! µ Å1 “
|
|||
|
|
Ú,±< ü ò… ütE B A scope guard will run a given closure when it goes out of scope,Á üº$ ! even if the code between panics.Á üß$ ! (as long as panic doesn't abort)Á „ ú tˆ # ExamplesÁ — ú ”› ## Hello WorldÁ ® ú ü²@ = This example creates a scope guard with an example function:Á ó ú <÷ ```Á äÿ extern crate scopeguard;Á œ ú d fn f() {Á ü0 - let _guard = scopeguard::guard((), |_| {Á üÞ* ' println!("Hello Scope Exit!");Á \‰ });Á • ú ü™! // rest of the code here.Á » ú ü¿O L // Here, at the end of `_guard`'s scope, the guard's closure is called.Á ü�M J // It is also called if we exit this scope through unwinding instead.Á ,Ý }Á Œã # fn main() {Á lõ
|
|||
|
|
# f();Á <ƒ # }Á <‹ þ “ ú |— ## `defer!`Á § ú ü«< 9 Use the `defer` macro to run an operation at scope exit,Á üè? < either regular scope exit or during unwinding from a panic.Á ¨ ú <¬ þ ü´0 - #[macro_use(defer)] extern crate scopeguard;Á å ú Äé use std::cell::Cell;Á ‚ ú |† fn main() {Á ü–Q N // use a cell to observe drops during and after the scope guard is activeÁ üè( % let drop_counter = Cell::new(0);Á L‘ {Á ü› H E // Create a scope guard using `defer!` for the current scopeÁ ¤ä defer! {Á üù 9 6 drop_counter.set(1 + drop_counter.get());Á l³
|
|||
|
|
|
|||
|
|
}Á Á
|
|||
|
|
ú üÅ
|
|||
|
|
: 7 // Do regular operations here in the meantime.Á € ú ü„ 9 6 // Just before scope exit: it hasn't run yet.Á ü¾ . + assert_eq!(drop_counter.get(), 0);Á í ú üñ K H // The following scope end is where the defer closure is calledÁ L½ }Á üÇ * ' assert_eq!(drop_counter.get(), 1);Á ,ò É <ø þ €
|
|||
|
|
ú ì„
|
|||
|
|
## Scope Guard with ValueÁ ¢
|
|||
|
|
ú ü¦
|
|||
|
|
J G If the scope guard closure needs to access an outer value that is alsoÁ üñ
|
|||
|
|
P M mutated outside of the scope guard, then you may want to use the scope guardÁ üÂN K with a value. The guard works like a smart pointer, so the inner value canÁ ü‘5 2 be accessed by reference or by mutable reference.Á Ç ú üË ### 1. The guard owns a fileÁ ì ú üðO L In this example, the scope guard owns a file and ensures pending writes areÁ ÌÀ synced at scope exit.Á Ú ú <Þ þ äæ Ž
|
|||
|
|
ƒ ú œ‡ use std::fs::*;Á ü› use std::io::{self, Write};Á ü»9 6 # // Mock file so that we don't actually write a fileÁ ´õ # struct MockFile;Á ¬Œ # impl MockFile {Á ü¢B ? # fn create(_s: &str) -> io::Result<Self> { Ok(MockFile) }Á üåE B # fn write_all(&self, _b: &[u8]) -> io::Result<()> { Ok(()) }Á ü«9 6 # fn sync_all(&self) -> io::Result<()> { Ok(()) }Á <å ‡ üí! # use self::MockFile as File;Á � ú ü“% " fn try_main() -> io::Result<()> {Á ü¹- * let f = File::create("newfile.txt")?;Á üç1 . let mut file = scopeguard::guard(f, |f| {Á ü™6 3 // ensure we flush file at return or panicÁ üÐ! let _ = f.sync_all();Á \ò  üþ9 6 // Access the file through the scope guard itselfÁ ü¸0 - file.write_all(b"test me\n").map(|_| ())Á ,é É ï ú |ó í äƒ try_main().unwrap();Á , É ¦ ú <ª þ ² ú ü¶8 5 ### 2. The guard restores an invariant on scope exitÁ ï ú <ó þ äû Ž
|
|||
|
|
˜ ú üœ use std::mem::ManuallyDrop;Á Œ¼ use std::ptr;Á Î ú üÒD A // This function, just for this example, takes the first elementÁ ü—A > // and inserts it into the assumed sorted tail of the vector.Á 4Ù //Á üàK H // For optimization purposes we temporarily violate an invariant of theÁ ü¬- * // Vec, that it owns all of its elements.Á 4Ú À) üáJ G // The safe approach is to use swap, which means two writes to memory,Á ü¬R O // the optimization is to use a “holeâ€� which uses only one write of memoryÁ üÿ" // for each position it moves.Á 4¢ À) ü© > ; // We *must* use a scope guard to run this code safely. WeÁ üè M J // are running arbitrary user code (comparison operators) that may panic.Á ü¶ H E // The scope guard ensures we restore the invariant after successfulÁ üÿ + ( // exit or during unwinding from panic.Á ü« . + fn insertion_sort_first<T>(v: &mut Vec<T>)Á ÜÚ where T: PartialOrdÁ ,ö {Á üü struct Hole<'a, T: 'a> {Á ô� v: &'a mut Vec<T>,Á ̼ index: usize,Á üÖ # value: ManuallyDrop<T>,Á Lú ¤ „ ú „ˆ
|
|||
|
|
unsafe {Á ü™ H E // Create a moved-from location in the vector, a “holeâ€�.Á üâ ) & let value = ptr::read(&v[0]);Á üŒ!T Q let mut hole = Hole { v: v, index: 0, value: ManuallyDrop::new(value) };Á á! ú üå!. + // Use a scope guard with a value.Á ü”"G D // At scope exit, plug the hole so that the vector is fullyÁ üÜ"! // initialized again.Á üþ"U R // The scope guard owns the hole, but we can access it through the guard.Á üÔ#A > let mut hole_guard = scopeguard::guard(hole, |hole| {Á ü–$S P // plug the hole in the vector with the value that was // taken outÁ üê$' $ let index =
|
|||
|
|
Ú Fĸ0 VD×0 hÄå0 †´ƒ1 ¸DŸ1 ËËææDÀ1 ù”‰2 üË1= : Controls in which cases the associated code should be runÁ D“2 Îì ü‰2« ÕH ÕH Äš3 ü¢2= : Return `true` if the guard’s associated code should runÁ üä21 . (in the context where this method is called).ÁT�3
|
|||
|
|
ÝHÄî7 à ¼£8 T¦8
|
|||
|
|
|
|||
|
|
|
|||
|
|
”¤< üó:0 - Macro to create a `ScopeGuard` (always run).Á ¤; ú ü¨;? < The macro takes statements, which are the body of a closureÁ üè;+ ( that will run when the scope is exited.Á (|”< ·< Ž= ½< Ç< , ¾< ¿< Å< , À< 8¿ Á< & Â< 8¯ Ã<
|
|||
|
|
Æ< *É< Ì< ‹= 8 Ö< 8 _guardÁ 4Ú< á< , ã< 8 ,ä< 'é< 8£ ,ë< ð< „= ñ< ò< $ ó< õ< ö< ÷< ø< ú< ƒ= , ü< ý< €= , þ< 8¿ ÿ<
|
|||
|
|
�= % …= % Œ= üðG' ü¦CA > `ScopeGuard` is a scope guard that may own a protected value.Á èC ú üìC= : If you place a guard in a local variable, the closure canÁ üªDN K run regardless how you leave the scope — through regular return or panicÁ üùDJ G (except if panic or other code aborts; so as long as destructors run).Á ÄÄE It is run only once.Á ÝE ú üáEI F The `S` parameter for [`Strategy`](trait.Strategy.html) determines ifÁ ô«F the closure actually runs.Á ÊF ú üÎFM J The guard's closure will be called with the held value in the destructor.Á œG ú ü GO L The `ScopeGuard` implements `Deref` so that you can access the inner value.Á TûG ¥ — ¤ Íìà †H ÍìÉ ‰H ÍìÏ TŒH –"Éà L¥H ÉÃU˜" Ï D·H … Ü'6šÞ¬h 3tv qs n ŒH à ´ÇH ,ÇH ÃÛÃÛ ª ÅÛ»¬ „ µÜÀ,�%*üãH 4ãH ÃÛÃÛ ª ÅÛ»¬ „ µÜÀ,�%*ÉüÔI! DÔI • • – ù Fu\»Ÿ ÏÏ üúIJ ¥ — ¤ ÍUL©J ™U ‚J ©U …J ¹U ‰U ÿI ßUD»J … 24 8: üºL< üËJL I Create a `ScopeGuard` that owns `v` (accessible through deref) and callsÁ üœK& # `dropfn` when its destructor runs.Á ÇK ú üÏKH E The `Strategy` decides whether the scope guard's closure should run.Á .\ªL lÁL ÃÉ…
|
|||
|
|
ÃÉÏÁ ÏL “4ÕL üâS# üžNM J “Defuseâ€� the guard and extract the value without calling the closure.Á ðN ú <øN þ ä„O Ž
|
|||
|
|
¥O ú üO( % use scopeguard::{guard, ScopeGuard};Á ÚO ú üâO% " fn conditional() -> bool { true }Á ŒP ú |”P í ü¨P= : let mut guard = guard(Vec::new(), |mut v| v.clear());Á ´êP guard.push(1);Á …Q ú Ô�Q if conditional() {Á ü¬Q3 0 // a condition maybe makes us decide toÁ üäQB ? // “defuseâ€� the guard and get back its inner partsÁ ü«R6 3 let value = ScopeGuard::into_inner(guard);Á „æR
|
|||
|
|
} else {Á üûR0 - // guard still exists in this branchÁ L°S ¤ ,¾S É <ÈS þ TéS …Ã
|
|||
|
|
ÃÉÏ£,ôS üÞXW üûWL I Create a new `ScopeGuard` owning `v` and with deferred closure `dropfn`.Á .\ÒX ,åX ÃÉ æ » “ Ü'6šÞ¬hÃÉà ¥ — ‰U ëX ™U îX ¹UL«Y ÍU
|