Scopeguard

https://docs.rs/scopeguard/latest/
Admin
Scopeguard is a Rust library that provides scope guards to run closures when exiting a scope, even...
Tokens:30,827
Snippets:77
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Rustdoc: Scrape and Include Code Examples

Source: https://docs.rs/scopeguard/latest/scrape-examples-help

Rustdoc automatically scrapes documented items from source code and includes them in generated documentation. This feature requires `cargo doc` with specific unstable options and aims to improve documentation by showing real-world usage. Limitations include a maximum of 5 examples per item and only one shown by default.

```Rust
pub fn a_func() {}
```

```Rust
fn main() {
  a_crate::a_func();
}
```

--------------------------------

### Rust ScopeGuard Example Usage

Source: https://docs.rs/scopeguard/latest/scopeguard/fn.guard

An example demonstrating the usage of the `guard` function to manage a file resource. The closure ensures the file is synced upon exiting the scope, whether normally or via panic.

```rust
fn g() {
    let f = File::create("newfile.txt").unwrap();
    let mut file = guard(f, |f| {
        // write file at return or panic
        let _ = f.sync_all();
    });
    // access the file through the scope guard itself
    file.write_all(b"test me\n").unwrap();
}
```

--------------------------------

### Rust ScopeGuard File Ownership Example

Source: https://docs.rs/scopeguard/latest/index

Demonstrates using `scopeguard::guard` to manage a file, ensuring pending writes are synced at scope exit. This example shows how a guard can own a resource and perform cleanup actions automatically.

```Rust
extern crate scopeguard;

use std::fs::File;
use std::io::{self, Write};

fn try_main() -> io::Result<()> {
    let f = File::create("newfile.txt")?;
    let mut file = scopeguard::guard(f, |f| {
        // ensure we flush file at return or panic
        let _ = f.sync_all();
    });
    // Access the file through the scope guard itself
    file.write_all(b"test me\n").map(|_| ())
}

fn main() {
    try_main().unwrap();
}
```

--------------------------------

### Rust ScopeGuard File Ownership Example

Source: https://docs.rs/scopeguard/latest/scopeguard

Demonstrates using `scopeguard::guard` to manage a file, ensuring pending writes are synced at scope exit. This example shows how a guard can own a resource and perform cleanup actions automatically.

```Rust
extern crate scopeguard;

use std::fs::File;
use std::io::{self, Write};

fn try_main() -> io::Result<()> {
    let f = File::create("newfile.txt")?;
    let mut file = scopeguard::guard(f, |f| {
        // ensure we flush file at return or panic
        let _ = f.sync_all();
    });
    // Access the file through the scope guard itself
    file.write_all(b"test me\n").map(|_| ())
}

fn main() {
    try_main().unwrap();
}
```

--------------------------------

### Rust ScopeGuard File Ownership Example

Source: https://docs.rs/scopeguard/latest/scopeguard/index

Demonstrates using `scopeguard::guard` to manage a file, ensuring pending writes are synced at scope exit. This example shows how a guard can own a resource and perform cleanup actions automatically.

```Rust
extern crate scopeguard;

use std::fs::File;
use std::io::{self, Write};

fn try_main() -> io::Result<()> {
    let f = File::create("newfile.txt")?;
    let mut file = scopeguard::guard(f, |f| {
        // ensure we flush file at return or panic
        let _ = f.sync_all();
    });
    // Access the file through the scope guard itself
    file.write_all(b"test me\n").map(|_| ())
}

fn main() {
    try_main().unwrap();
}
```

--------------------------------

### Rust Insertion Sort Example

Source: https://docs.rs/scopeguard/latest/src/scopeguard/lib.rs

Demonstrates the usage of scope guards within an insertion sort algorithm. It shows how to manage a 'hole' in a vector and ensure cleanup or state restoration upon scope exit.

```rust
/// 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.
#[macro_export]
macro_rules! defer {
    ($($t:tt)*) => {
        let _guard = $crate::guard((), |()| { $($t)* });
    };
}

/// `ScopeGuard` is a scope guard that may own a protected value.
///
/// If you place a guard in a local variable, the closure can
/// run regardless how you leave the scope — through regular return or panic
/// (except if panic or other code aborts; so as long as destructors run).
/// It is run only once.
///
/// The `S` parameter for [`Strategy`](trait.Strategy.html) determines if
/// the closure actually runs.
///
/// The guard's closure will be called with the held value in the destructor.
///
// Example usage from the text:
// fn main() {
//     let string = String::from;
//     let mut data = vec![string("c"), string("a"), string("b"), string("d")];
//     // Assuming insertion_sort_first is defined elsewhere and uses scope guards
//     // insertion_sort_first(&mut data);
//     // assert_eq!(data, vec!["a", "b", "c", "d"]);
// }

```

--------------------------------

### Rust Example: Using ScopeGuard and Defusing

Source: https://docs.rs/scopeguard/latest/scopeguard/fn.guard_on_unwind

Demonstrates how to use the scopeguard crate, specifically creating a guard and manually defusing it at the end of a scope. This pattern can be used for performance or to emulate no-std behavior.

```rust
extern crate scopeguard;

use scopeguard::ScopeGuard;
{
    let guard = scopeguard::guard((), |_| {});

    // rest of the code here

    // we reached the end of scope without unwinding - defuse it
    ScopeGuard::into_inner(guard);
}

```

--------------------------------

### ScopeGuard Usage Example - Rust

Source: https://docs.rs/scopeguard/latest/scopeguard/struct.ScopeGuard

Demonstrates the practical usage of ScopeGuard in Rust, showing how to create a guard, modify its internal value, and conditionally extract the value using `into_inner` based on a runtime condition.

```rust
extern crate scopeguard;

use scopeguard::{guard, ScopeGuard};

fn conditional() -> bool { true }

fn main() {
    let mut guard = guard(Vec::new(), |mut v| v.clear());
    guard.push(1);

    if conditional() {
        // a condition maybe makes us decide to
        // “defuse” the guard and get back its inner parts
        let value = ScopeGuard::into_inner(guard);
    } else {
        // guard still exists in this branch
    }
}
```

--------------------------------

### Rust ScopeGuard Invariant Restoration Example

Source: https://docs.rs/scopeguard/latest/index

Illustrates using `scopeguard::guard` to restore a vector's invariant after temporarily violating it during an insertion sort-like operation. This highlights the safety net provided by guards against panics.

```Rust
extern crate scopeguard;

use std::mem::ManuallyDrop;
use std::ptr;

// This function, just for this example, takes the first element
// and inserts it into the assumed sorted tail of the vector.
//
// For optimization purposes we temporarily violate an invariant of the
// Vec, that it owns all of its elements.
//
// The safe approach is to use swap, which means two writes to memory,
// the optimization is to use a “hole” which uses only one write of memory
// for each position it moves.
//
// We *must* use a scope guard to run this code safely. We
// are running arbitrary user code (comparison operators) that may panic.
// 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>,
    }

    unsafe {
        // Create a moved-from location in the vector, a “hole”.
        let value = ptr::read(&v[0]);
        let mut hole = Hole { v: v, index: 0, value: ManuallyDrop::new(value) };

        // Use a scope guard with a value.
        // At scope exit, plug the hole so that the vector is fully
        // initialized again.
        // The scope guard owns the hole, but we can access it through the guard.
        let mut hole_guard = scopeguard::guard(hole, |hole| {
            // plug the hole in the vector with the value that was // taken out
            let index = hole.index;
            ptr::copy_nonoverlapping(&*hole.value, &mut hole.v[index], 1);
        });

        // run algorithm that moves the hole in the vector here
        // move the hole until it's in a sorted position
        for i in 1..hole_guard.v.len() {
            if *hole_guard.value >= hole_guard.v[i] {
                // move the element back and the hole forward
                let index = hole_guard.index;
                hole_guard.v.swap(index, index + 1);
                hole_guard.index += 1;
            } else {
                break;
            }
        }

        // When the scope exits here, the Vec becomes whole again!
    }
}

fn main() {
    let string = String::from;
    let mut data = vec![string("c"), string("a"), string("b"), string("d")];
    insertion_sort_first(&mut data);
    assert_eq!(data, vec!["a", "b", "c", "d"]);
}
```

--------------------------------

### Rust ScopeGuard Invariant Restoration Example

Source: https://docs.rs/scopeguard/latest/scopeguard/index

Illustrates using `scopeguard::guard` to restore a vector's invariant after temporarily violating it during an insertion sort-like operation. This highlights the safety net provided by guards against panics.

```Rust
extern crate scopeguard;

use std::mem::ManuallyDrop;
use std::ptr;

// This function, just for this example, takes the first element
// and inserts it into the assumed sorted tail of the vector.
//
// For optimization purposes we temporarily violate an invariant of the
// Vec, that it owns all of its elements.
//
// The safe approach is to use swap, which means two writes to memory,
// the optimization is to use a “hole” which uses only one write of memory
// for each position it moves.
//
// We *must* use a scope guard to run this code safely. We
// are running arbitrary user code (comparison operators) that may panic.
// 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>,
    }

    unsafe {
        // Create a moved-from location in the vector, a “hole”.
        let value = ptr::read(&v[0]);
        let mut hole = Hole { v: v, index: 0, value: ManuallyDrop::new(value) };

        // Use a scope guard with a value.
        // At scope exit, plug the hole so that the vector is fully
        // initialized again.
        // The scope guard owns the hole, but we can access it through the guard.
        let mut hole_guard = scopeguard::guard(hole, |hole| {
            // plug the hole in the vector with the value that was // taken out
            let index = hole.index;
            ptr::copy_nonoverlapping(&*hole.value, &mut hole.v[index], 1);
        });

        // run algorithm that moves the hole in the vector here
        // move the hole until it's in a sorted position
        for i in 1..hole_guard.v.len() {
            if *hole_guard.value >= hole_guard.v[i] {
                // move the element back and the hole forward
                let index = hole_guard.index;
                hole_guard.v.swap(index, index + 1);
                hole_guard.index += 1;
            } else {
                break;
            }
        }

        // When the scope exits here, the Vec becomes whole again!
    }
}

fn main() {
    let string = String::from;
    let mut data = vec![string("c"), string("a"), string("b"), string("d")];
    insertion_sort_first(&mut data);
    assert_eq!(data, vec!["a", "b", "c", "d"]);
}
```

--------------------------------

### Rust ScopeGuard Invariant Restoration Example

Source: https://docs.rs/scopeguard/latest/scopeguard

Illustrates using `scopeguard::guard` to restore a vector's invariant after temporarily violating it during an insertion sort-like operation. This highlights the safety net provided by guards against panics.

```Rust
extern crate scopeguard;

use std::mem::ManuallyDrop;
use std::ptr;

// This function, just for this example, takes the first element
// and inserts it into the assumed sorted tail of the vector.
//
// For optimization purposes we temporarily violate an invariant of the
// Vec, that it owns all of its elements.
//
// The safe approach is to use swap, which means two writes to memory,
// the optimization is to use a “hole” which uses only one write of memory
// for each position it moves.
//
// We *must* use a scope guard to run this code safely. We
// are running arbitrary user code (comparison operators) that may panic.
// 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>,
    }

    unsafe {
        // Create a moved-from location in the vector, a “hole”.
        let value = ptr::read(&v[0]);
        let mut hole = Hole { v: v, index: 0, value: ManuallyDrop::new(value) };

        // Use a scope guard with a value.
        // At scope exit, plug the hole so that the vector is fully
        // initialized again.
        // The scope guard owns the hole, but we can access it through the guard.
        let mut hole_guard = scopeguard::guard(hole, |hole| {
            // plug the hole in the vector with the value that was // taken out
            let index = hole.index;
            ptr::copy_nonoverlapping(&*hole.value, &mut hole.v[index], 1);
        });

        // run algorithm that moves the hole in the vector here
        // move the hole until it's in a sorted position
        for i in 1..hole_guard.v.len() {
            if *hole_guard.value >= hole_guard.v[i] {
                // move the element back and the hole forward
                let index = hole_guard.index;
                hole_guard.v.swap(index, index + 1);
                hole_guard.index += 1;
            } else {
                break;
            }
        }

        // When the scope exits here, the Vec becomes whole again!
    }
}

fn main() {
    let string = String::from;
    let mut data = vec![string("c"), string("a"), string("b"), string("d")];
    insertion_sort_first(&mut data);
    assert_eq!(data, vec!["a", "b", "c", "d"]);
}
```

--------------------------------

### APIDOC: scopeguard Strategy Trait and Methods

Source: https://docs.rs/scopeguard/latest/scopeguard/trait.Strategy

Comprehensive documentation for the scopeguard crate's Strategy trait. It includes the trait definition, the required `should_run` method, and details on its implementors like Always, OnSuccess, and OnUnwind.

```APIDOC
Trait: scopeguard::Strategy

Description:
Controls in which cases the associated code should be run.
This trait is not dyn compatible (not object safe).

Source:
[../src/scopeguard/lib.rs.html#201-205]

Required Methods:

  - fn should_run() -> bool
    Description: Return `true` if the guard’s associated code should run (in the context where this method is called).
    Source: [../src/scopeguard/lib.rs.html#204]

Implementors:

  - impl Strategy for Always
    Source: [../src/scopeguard/lib.rs.html#245-250]

  - impl Strategy for OnSuccess
    Source: [../src/scopeguard/lib.rs.html#237-242]

  - impl Strategy for OnUnwind
    Source: [../src/scopeguard/lib.rs.html#229-234]
```

--------------------------------

### Using the defer! Macro

Source: https://docs.rs/scopeguard/latest/src/scopeguard/lib.rs

Illustrates the use of the `defer!` macro to execute a closure at the end of the current scope. This macro simplifies the process of ensuring cleanup or side effects occur regardless of how the scope is exited, including panics.

```rust
#[macro_use(defer)] extern crate scopeguard;

use std::cell::Cell;

fn main() {
    // use a cell to observe drops during and after the scope guard is active
    let drop_counter = Cell::new(0);
    {
        // Create a scope guard using `defer!` for the current scope
        defer! {
            drop_counter.set(1 + drop_counter.get());
        }

        // Do regular operations here in the meantime.

        // Just before scope exit: it hasn't run yet.
        assert_eq!(drop_counter.get(), 0);

        // The following scope end is where the defer closure is called
    }
    assert_eq!(drop_counter.get(), 1);
}
```

--------------------------------

### ScopeGuard Crate Items Overview

Source: https://docs.rs/scopeguard/latest/scopeguard/all

Lists the primary items available within the scopeguard Rust crate, categorized by type. This includes macros for deferred execution, core data structures like ScopeGuard, and behavioral definitions via traits.

```rust
Structs:
  ScopeGuard

Enums:
  Always
  OnSuccess
  OnUnwind

Traits:
  Strategy

Macros:
  defer
  defer_on_success
  defer_on_unwind

Functions:
  guard
  guard_on_success
  guard_on_unwind
```

--------------------------------

### Rust: Create Scope Guard with Closure

Source: https://docs.rs/scopeguard/latest/scopeguard/index

Demonstrates creating a basic scope guard in Rust using `scopeguard::guard`. The guard executes a provided closure when it goes out of scope, ensuring execution even if the code between panics (as long as panic doesn't abort).

```Rust
extern crate scopeguard;

fn f() {
    let _guard = scopeguard::guard((), |_| {
        println!("Hello Scope Exit!");
    });

    // rest of the code here.

    // Here, at the end of `_guard`'s scope, the guard's closure is called.
    // It is also called if we exit this scope through unwinding instead.
}
```

--------------------------------

### Rust: Create Scope Guard with Closure

Source: https://docs.rs/scopeguard/latest/scopeguard

Demonstrates creating a basic scope guard in Rust using `scopeguard::guard`. The guard executes a provided closure when it goes out of scope, ensuring execution even if the code between panics (as long as panic doesn't abort).

```Rust
extern crate scopeguard;

fn f() {
    let _guard = scopeguard::guard((), |_| {
        println!("Hello Scope Exit!");
    });

    // rest of the code here.

    // Here, at the end of `_guard`'s scope, the guard's closure is called.
    // It is also called if we exit this scope through unwinding instead.
}
```

--------------------------------

### Rust: Create Scope Guard with Closure

Source: https://docs.rs/scopeguard/latest/index

Demonstrates creating a basic scope guard in Rust using `scopeguard::guard`. The guard executes a provided closure when it goes out of scope, ensuring execution even if the code between panics (as long as panic doesn't abort).

```Rust
extern crate scopeguard;

fn f() {
    let _guard = scopeguard::guard((), |_| {
        println!("Hello Scope Exit!");
    });

    // rest of the code here.

    // Here, at the end of `_guard`'s scope, the guard's closure is called.
    // It is also called if we exit this scope through unwinding instead.
}
```

--------------------------------

### ScopeGuard::with_strategy Constructor

Source: https://docs.rs/scopeguard/latest/src/scopeguard/lib.rs

Creates a new ScopeGuard instance. It takes ownership of a value `v` and a closure `dropfn`. The `dropfn` will be called when the guard's destructor runs, based on the strategy `S`.

```rust
impl<T, F, S>
where
    F: FnOnce(T),
    S: Strategy,
{
    /// Create a `ScopeGuard` that owns `v` (accessible through deref) and calls
    /// `dropfn` when its destructor runs.
    ///
    /// The `Strategy` decides whether the scope guard's closure should run.
    #[inline]
    #[must_use]
    pub fn with_strategy(v: T, dropfn: F) -> ScopeGuard<T, F, S> {
        ScopeGuard {
            value: ManuallyDrop::new(v),
            dropfn: ManuallyDrop::new(dropfn),
            strategy: PhantomData,
        }
    }
}
```

--------------------------------

### defer! Macro Usage

Source: https://docs.rs/scopeguard/latest/src/scopeguard/lib.rs

Demonstrates the basic usage of the defer! macro, which schedules a closure to be executed when the current scope exits. This is useful for ensuring cleanup actions are always performed.

```rust
let drops = Cell::new(0);
defer!(drops.set(1000));
assert_eq!(drops.get(), 0);
```

--------------------------------

### Rust Conversion Traits: From and Into

Source: https://docs.rs/scopeguard/latest/scopeguard/struct.ScopeGuard

Documents the `From` and `Into` traits in Rust's core library, which facilitate type conversions. `From` allows conversion into a type, while `Into` allows conversion from a type, often implemented automatically when `From` is available.

```APIDOC
trait From<T>
  
  fn from(t: T) -> T
    - Returns the argument unchanged.
    - Source: https://doc.rust-lang.org/nightly/core/convert/mod.rs.html#774

trait Into<U>
  
  fn into(self) -> U
    - Calls `U::from(self)`.
    - This conversion is whatever the implementation of `From<T> for U` chooses to do.
    - Source: https://doc.rust-lang.org/nightly/core/convert/mod.rs.html#767
```

--------------------------------

### ScopeGuard Methods and Implementations

Source: https://docs.rs/scopeguard/latest/scopeguard/struct.ScopeGuard

Details the available methods for the ScopeGuard struct, including `into_inner` and `with_strategy`, along with its various trait implementations such as Deref, Drop, and Sync, and blanket implementations.

```APIDOC
ScopeGuard Methods and Implementations

Methods:
* [into_inner](#method.into_inner)
* [with_strategy](#method.with_strategy)

Trait Implementations:
* [Debug](#impl-Debug-for-ScopeGuard%3CT,+F,+S%3E)
* [Deref](#impl-Deref-for-ScopeGuard%3CT,+F,+S%3E)
* [DerefMut](#impl-DerefMut-for-ScopeGuard%3CT,+F,+S%3E)
* [Drop](#impl-Drop-for-ScopeGuard%3CT,+F,+S%3E)
* [Sync](#impl-Sync-for-ScopeGuard%3CT,+F,+S%3E)

Auto Trait Implementations:
* [Freeze](#impl-Freeze-for-ScopeGuard%3CT,+F,+S%3E)
* [RefUnwindSafe](#impl-RefUnwindSafe-for-ScopeGuard%3CT,+F,+S%3E)
* [Send](#impl-Send-for-ScopeGuard%3CT,+F,+S%3E)
* [Unpin](#impl-Unpin-for-ScopeGuard%3CT,+F,+S%3E)
* [UnwindSafe](#impl-UnwindSafe-for-ScopeGuard%3CT,+F,+S%3E)

Blanket Implementations:
* [Any](#impl-Any-for-T)
* [Borrow<T>](#impl-Borrow%3CT%3E-for-T)
* [BorrowMut<T>](#impl-BorrowMut%3CT%3E-for-T)
* [From<T>](#impl-From%3CT%3E-for-T)
* [Into<U>](#impl-Into%3CU%3E-for-T)
* [Receiver](#impl-Receiver-for-P)
* [TryFrom<U>](#impl-TryFrom%3CU%3E-for-T)
* [TryInto<U>](#impl-TryInto%3CU%3E-for-T)

Implementation for ScopeGuard<T, F, S>

impl<T, F, S> ScopeGuard<T, F, S> where F: FnOnce(T), S: Strategy
```

--------------------------------

### Basic Scope Guard Usage

Source: https://docs.rs/scopeguard/latest/src/scopeguard/lib.rs

Demonstrates the fundamental usage of `scopeguard::guard` to execute a closure when the guard goes out of scope. This is useful for ensuring actions are performed upon normal scope exit or during unwinding from a panic.

```rust
extern crate scopeguard;

fn f() {
    let _guard = scopeguard::guard((), |_| {
        println!("Hello Scope Exit!");
    });

    // rest of the code here.

    // Here, at the end of `_guard`'s scope, the guard's closure is called.
    // It is also called if we exit this scope through unwinding instead.
}
# fn main() {
#    f();
# }
```

--------------------------------

### scopeguard API Documentation

Source: https://docs.rs/scopeguard/latest/scopeguard/enum.OnUnwind

Documentation for the scopeguard crate's core types and traits, including the OnUnwind enum and its implementations for Debug and Strategy.

```APIDOC
scopeguard::OnUnwind Enum:
  Description: Represents a guard that runs code on scope exit, specifically when unwinding occurs. Requires the 'use_std' crate feature.

  Trait Implementations:
    impl Debug for OnUnwind:
      fn fmt(&self, f: &mut Formatter<'_>) -> Result
        - Formats the value using the given formatter.

    impl Strategy for OnUnwind:
      fn should_run() -> bool
        - Return true if the guard’s associated code should run (in the context where this method is called).

  Auto Trait Implementations:
    - Freeze
    - RefUnwindSafe
    - Send
    - Sync
    - Unpin
    - UnwindSafe

  Blanket Implementations:
    - Any
    - Borrow<T>
    - BorrowMut<T>
    - From<T>
    - Into<U>
    - TryFrom<U>
    - TryInto<U>
```

--------------------------------

### Scope Guard Owning a File for Sync

Source: https://docs.rs/scopeguard/latest/src/scopeguard/lib.rs

Shows how a scope guard can own a resource, such as a file handle, and ensure a specific operation, like syncing pending writes, is performed upon scope exit. This pattern guarantees resource integrity even if the code block panics.

```rust
extern crate scopeguard;

use std::fs::*
use std::io::{self, Write};
# // Mock file so that we don't actually write a file
# struct MockFile;
# impl MockFile {
#     fn create(_s: &str) -> io::Result<Self> { Ok(MockFile) }
#     fn write_all(&self, _b: &[u8]) -> io::Result<()> { Ok(()) }
#     fn sync_all(&self) -> io::Result<()> { Ok(()) }
# }
# use self::MockFile as File;

fn try_main() -> io::Result<()> {
    let f = File::create("newfile.txt")?;
    let mut file = scopeguard::guard(f, |f| {
        // ensure we flush file at return or panic
        let _ = f.sync_all();
    });
    // Access the file through the scope guard itself
    file.write_all(b"test me\n").map(|_| ())
}

fn main() {
    try_main().unwrap();
}
```

--------------------------------

### Rust TryInto Trait

Source: https://docs.rs/scopeguard/latest/scopeguard/struct.ScopeGuard

Documentation for the `TryInto` trait in Rust, which provides a fallible conversion mechanism. It includes the associated `Error` type for conversion failures and the `try_into` method to perform the conversion.

```APIDOC
Rust TryInto Trait Documentation:

Associated Type: Error
  Type returned in the event of a conversion error.
  Source: https://doc.rust-lang.org/nightly/src/core/convert/mod.rs.html#805

Method: try_into
  Performs the conversion.
  Signature: fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
  Parameters:
    self: The value to convert.
  Returns:
    A Result containing the converted value of type U on success, or an error of type <U as TryFrom<T>>::Error on failure.
```

--------------------------------

### ScopeGuard Debug Implementation

Source: https://docs.rs/scopeguard/latest/src/scopeguard/lib.rs

Provides a Debug implementation for the ScopeGuard struct, allowing it to be formatted for debugging purposes. It displays the 'value' field.

```rust
impl<T, F, S> fmt::Debug for ScopeGuard<T, F, S>
where
    T: fmt::Debug,
    F: FnOnce(T),
    S: Strategy,
{
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.debug_struct(stringify!(ScopeGuard))
            .field("value", &*self.value)
            .finish()
    }
}
```

--------------------------------

### Create ScopeGuard with Strategy - Rust

Source: https://docs.rs/scopeguard/latest/scopeguard/struct.ScopeGuard

Creates a ScopeGuard that owns a value `v` and executes a provided `dropfn` when its destructor runs. The `Strategy` determines if the closure should be executed, allowing for conditional cleanup.

```rust
pub fn with_strategy<T, F, S>(v: T, dropfn: F) -> ScopeGuard<T, F, S>
// where S: Strategy
```

--------------------------------

### defer_on_success! Macro Usage

Source: https://docs.rs/scopeguard/latest/src/scopeguard/lib.rs

Shows how to use the defer_on_success! macro, which executes a closure only if the scope exits normally (without panicking). This is ideal for actions that should only happen on successful completion.

```rust
let drops = Cell::new(0);
{
    defer_on_success!(drops.set(1));
    assert_eq!(drops.get(), 0);
}
assert_eq!(drops.get(), 1);
```

```rust
let drops = Cell::new(0);
let _ = catch_unwind(AssertUnwindSafe(|| {
    defer_on_success!(drops.set(1));
    panic!("failure")
}));
assert_eq!(drops.get(), 0);
```

--------------------------------

### Rust Conversion Traits: TryFrom and TryInto

Source: https://docs.rs/scopeguard/latest/scopeguard/struct.ScopeGuard

Documents the `TryFrom` and `TryInto` traits in Rust's core library, enabling fallible type conversions. `TryFrom` attempts a conversion and returns a `Result`, while `TryInto` is the reciprocal trait.

```APIDOC
trait TryFrom<U>
  
  type Error = Infallible
    - The type returned in the event of a conversion error.
    - Source: https://doc.rust-lang.org/nightly/core/convert/mod.rs.html#813-815
  
  fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
    - Performs the conversion.
    - Source: https://doc.rust-lang.org/nightly/core/convert/mod.rs.html#820

trait TryInto<U>
  
  // No methods defined directly, relies on TryFrom implementation.
  // Source: https://doc.rust-lang.org/nightly/core/convert/mod.rs.html#802
```

--------------------------------

### Rust Scope Guard Strategies and Macros

Source: https://docs.rs/scopeguard/latest/src/scopeguard/lib.rs

Defines the core `Strategy` trait and its implementations (`Always`, `OnUnwind`, `OnSuccess`), along with the `defer!` macros for creating scope guards. These are fundamental to the crate's functionality.

```rust
#[cfg(not(any(test, feature = "use_std")))]
extern crate core as std;

use std::fmt;
use std::marker::PhantomData;
use std::mem::ManuallyDrop;
use std::ops::{Deref, DerefMut};
use std::ptr;

/// Controls in which cases the associated code should be run
pub trait Strategy {
    /// Return `true` if the guard’s associated code should run
    /// (in the context where this method is called).
    fn should_run() -> bool;
}

/// Always run on scope exit.
///
/// “Always” run: on regular exit from a scope or on unwinding from a panic.
/// Can not run on abort, process exit, and other catastrophic events where
/// destructors don’t run.
#[derive(Debug)]
pub enum Always {}

/// Run on scope exit through unwinding.
///
/// Requires crate feature `use_std`.
#[cfg(feature = "use_std")]
#[derive(Debug)]
pub enum OnUnwind {}

/// Run on regular scope exit, when not unwinding.
///
/// Requires crate feature `use_std`.
#[cfg(feature = "use_std")]
#[derive(Debug)]
pub enum OnSuccess {}

impl Strategy for Always {
    #[inline(always)]
    fn should_run() -> bool {
        true
    }
}

#[cfg(feature = "use_std")]
impl Strategy for OnUnwind {
    #[inline]
    fn should_run() -> bool {
        std::thread::panicking()
    }
}

#[cfg(feature = "use_std")]
impl Strategy for OnSuccess {
    #[inline]
    fn should_run() -> bool {
        !std::thread::panicking()
    }
}

/// 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.
#[macro_export]
macro_rules! defer {
    ($($t:tt)*) => {
        let _guard = $crate::guard((), |()| { $($t)* });
    };
}

/// Macro to create a `ScopeGuard` (run on successful scope exit).
///
/// The macro takes statements, which are the body of a closure
/// that will run when the scope is exited.
///
/// Requires crate feature `use_std`.
#[cfg(feature = "use_std")]
#[macro_export]
macro_rules! defer_on_success {
    ($($t:tt)*) => {
        let _guard = $crate::guard_on_success((), |()| { $($t)* });
    };
}

/// Macro to create a `ScopeGuard` (run on unwinding from panic).
///
/// The macro takes statements, which are the body of a closure
/// that will run when the scope is exited.
///
/// Requires crate feature `use_std`.
#[cfg(feature = "use_std")]
#[macro_export]
macro_rules! defer_on_unwind {
    ($($t:tt)*) => {
        let _guard = $crate::guard_on_unwind((), |()| { $($t)* });
    };
}

```

--------------------------------

### ScopeGuard API and Trait Implementations - Rust

Source: https://docs.rs/scopeguard/latest/scopeguard/struct.ScopeGuard

Details the core API methods and trait implementations for the Rust ScopeGuard struct. This includes methods for formatting, dereferencing (both immutable and mutable), and the automatic drop behavior.

```APIDOC
struct ScopeGuard<T, F, S>
  where F: FnOnce(T),
        S: Strategy

// Public Methods:

// Creates a ScopeGuard that owns `v` and calls `dropfn` when its destructor runs.
// The `Strategy` decides whether the scope guard’s closure should run.
pub fn with_strategy<T, F, S>(v: T, dropfn: F) -> ScopeGuard<T, F, S>

// "Defuses" the guard and extracts the value without calling the closure.
pub fn into_inner(guard: Self) -> T

// Trait Implementations:

// impl<T, F, S> Debug for ScopeGuard<T, F, S>
// where T: Debug, F: FnOnce(T), S: Strategy
// Formats the value using the given formatter.
fn fmt(&self, f: &mut Formatter<'_>) -> Result

// impl<T, F, S> Deref for ScopeGuard<T, F, S>
// where F: FnOnce(T), S: Strategy
// The resulting type after dereferencing.
type Target = T
// Dereferences the value.
fn deref(&self) -> &T

// impl<T, F, S> DerefMut for ScopeGuard<T, F, S>
// where F: FnOnce(T), S: Strategy
// Mutably dereferences the value.
fn deref_mut(&mut self) -> &mut T

// impl<T, F, S> Drop for ScopeGuard<T, F, S>
// where F: FnOnce(T), S: Strategy
// Executes the destructor for this type.
fn drop(&mut self)

```

--------------------------------

### guard and guard_on_unwind Usage

Source: https://docs.rs/scopeguard/latest/src/scopeguard/lib.rs

Demonstrates the guard and guard_on_unwind functions, which create ScopeGuard instances. These functions allow for explicit control over deferred execution, including dropping nested guards and captured values.

```rust
let value_drops = Cell::new(0);
let value = guard((), |()| value_drops.set(1 + value_drops.get()));
let closure_drops = Cell::new(0);
let guard = guard(value, |_| closure_drops.set(1 + closure_drops.get()));
assert_eq!(value_drops.get(), 0);
assert_eq!(closure_drops.get(), 0);
drop(guard);
assert_eq!(value_drops.get(), 1);
assert_eq!(closure_drops.get(), 1);
```

```rust
let value_drops = Cell::new(0);
let value = guard((), |()| value_drops.set(1 + value_drops.get()));
let captured_drops = Cell::new(0);
let captured = guard((), |()| captured_drops.set(1 + captured_drops.get()));
let closure_drops = Cell::new(0);
let guard = guard_on_unwind(value, |value| {
    drop(value);
    drop(captured);
    closure_drops.set(1 + closure_drops.get())
});
assert_eq!(value_drops.get(), 0);
assert_eq!(captured_drops.get(), 0);
assert_eq!(closure_drops.get(), 0);
drop(guard);
assert_eq!(value_drops.get(), 1);
assert_eq!(captured_drops.get(), 1);
assert_eq!(closure_drops.get(), 0);
```

--------------------------------

### Rust Scopeguard: Deferred Execution with `defer!` and `guard`

Source: https://docs.rs/scopeguard/latest/src/readme/readme.rs

Demonstrates the usage of the `scopeguard` crate's `defer!` macro and `guard` function in Rust. The `defer!` macro executes a closure when the current scope exits, either normally or via panic. The `guard` function provides RAII-style resource management, ensuring a cleanup closure is called upon scope exit.

```Rust
1#[macro_use(defer)]
2extern crate scopeguard;
3
4use scopeguard::guard;
5
6fn f() {
7    defer! {
8        println!("Called at return or panic");
9    }
10    panic!();
11}
12
13use std::fs::File;
14use std::io::Write;
15
16fn g() {
17    let f = File::create("newfile.txt").unwrap();
18    let mut file = guard(f, |f| {
19        // write file at return or panic
20        let _ = f.sync_all();
21    });
22    // access the file through the scope guard itself
23    file.write_all(b"test me\n").unwrap();
24}
25
26fn main() {
27    f();
28    g();
29}
```

--------------------------------

### Rust: Use defer! Macro for Scope Exit Operations

Source: https://docs.rs/scopeguard/latest/index

Shows how to use the `defer!` macro from the scopeguard crate to execute an operation at the end of the current scope. This is useful for cleanup tasks that should run regardless of how the scope is exited, including unwinding from a panic.

```Rust
#[macro_use(defer)] extern crate scopeguard;

use std::cell::Cell;

fn main() {
    // use a cell to observe drops during and after the scope guard is active
    let drop_counter = Cell::new(0);
    {
        // Create a scope guard using `defer!` for the current scope
        defer! {
            drop_counter.set(1 + drop_counter.get());
        }

        // Do regular operations here in the meantime.

        // Just before scope exit: it hasn't run yet.
        assert_eq!(drop_counter.get(), 0);

        // The following scope end is where the defer closure is called
    }
    assert_eq!(drop_counter.get(), 1);
}
```

--------------------------------

### Generic Blanket Implementations for T

Source: https://docs.rs/scopeguard/latest/scopeguard/enum.OnUnwind

This section covers blanket implementations of common Rust traits for any type `T` that satisfies certain bounds. These are standard Rust features that apply broadly to types, including those used with `rs-scopeguard`.

```APIDOC
Generic Blanket Implementations for T:

- impl<T> Any for T where T: 'static + ?Sized
  - Description: Provides the `Any` trait for any type `T` that is `'static` and `Sized`. The `Any` trait allows for runtime type identification.
  - Methods:
    - `type_id(&self) -> TypeId`: Gets the `TypeId` of `self`.
  - Constraints: `T: 'static`, `T: ?Sized`
  - Related Traits: `Borrow<T>`, `BorrowMut<T>`, `From<T>`, `Into<U>`, `TryFrom<U>`

- impl<T> Borrow<T> for T where T: ?Sized
  - Description: Allows any type `T` (that is not dynamically sized) to be borrowed as a reference to itself.
  - Methods:
    - `borrow(&self) -> &T`: Immutably borrows from an owned value.
  - Constraints: `T: ?Sized`
  - Related Traits: `Any`, `BorrowMut<T>`, `From<T>`, `Into<U>`, `TryFrom<U>`

- impl<T> BorrowMut<T> for T where T: ?Sized
  - Description: Allows any type `T` (that is not dynamically sized) to be mutably borrowed as a mutable reference to itself.
  - Methods:
    - `borrow_mut(&mut self) -> &mut T`: Mutably borrows from an owned value.
  - Constraints: `T: ?Sized`
  - Related Traits: `Any`, `Borrow<T>`, `From<T>`, `Into<U>`, `TryFrom<U>`

- impl<T> From<T> for T
  - Description: Implements the `From` trait for a type `T` to itself, allowing conversion of `T` into `T`.
  - Methods:
    - `from(t: T) -> T`: Returns the argument unchanged.
  - Related Traits: `Any`, `Borrow<T>`, `BorrowMut<T>`, `Into<U>`, `TryFrom<U>`

- impl<T, U> Into<U> for T where U: From<T>
  - Description: Implements the `Into` trait for type `T` to `U`, provided that `U` implements `From<T>`.
  - Methods:
    - `into(self) -> U`: Calls `U::from(self)`.
  - Constraints: `U: From<T>`
  - Related Traits: `Any`, `Borrow<T>`, `BorrowMut<T>`, `From<T>`, `TryFrom<U>`

- impl<T, U> TryFrom<U> for T where T: From<U>
  - Description: Implements the `TryFrom` trait for type `T` from `U`, provided that `T` implements `From<U>`. This implies a fallible conversion.
  - Constraints: `T: From<U>`
  - Related Traits: `Any`, `Borrow<T>`, `BorrowMut<T>`, `From<T>`, `Into<U>`
```

--------------------------------

### guard Function (Default Strategy)

Source: https://docs.rs/scopeguard/latest/src/scopeguard/lib.rs

A convenience function to create a ScopeGuard with the default `Always` strategy. It takes a value and a closure, returning a guard that will execute the closure when dropped.

```rust
/// Create a new `ScopeGuard` owning `v` and with deferred closure `dropfn`.
#[inline]
#[must_use]
pub fn guard<T, F>(v: T, dropfn: F) -> ScopeGuard<T, F, Always>
where
    F: FnOnce(T),
{
    ScopeGuard::with_strategy(v, dropfn)
}
```

--------------------------------

### Generic Trait Implementations for T

Source: https://docs.rs/scopeguard/latest/scopeguard/struct.ScopeGuard

Documentation for blanket implementations of standard Rust traits for any type T. These are fundamental traits that enable various operations and compile-time checks.

```APIDOC
Generic Implementations for Type T:

- Any: Implemented for T where T: 'static + ?Sized.
  - Methods:
    - type_id(&self) -> TypeId
      - Description: Gets the TypeId of self.
      - Returns: The unique identifier for the type of self.

- Borrow<T>: Implemented for T where T: ?Sized.
  - Methods:
    - borrow(&self) -> &T
      - Description: Immutably borrows from an owned value.
      - Returns: An immutable reference to the borrowed value.
```
Tokens:
Raw