Crate run_down

Run-down protection as a pattern is useful in situations where re-initialization or destruction of a shared resource is required in a SMP environment. The pattern has two parts, a means to guarantee the resource is accessible and remains so for the during of it’s usage. As well as way to make the resource inaccessible from a point going forward and the ability to wait for all outstanding usages to drain so you can safely perform the required operation.

This crate was inspired by the run-down protection primitive in the NT kernel. Where it’s used in situations such as driver unload, where futher access to the driver needs to be rejected and the unloading thread must wait for inflight acesss to stop before the driver can be completely unload.

Example

use run_down::{
    RundownGuard,
    RundownRef
};
use std::sync::Arc;
use std::thread;
use std::time::Duration;

let rundown = Arc::new(RundownRef::new());

for i in 1..25 {

    let rundown_clone = Arc::clone(&rundown);

    thread::spawn(move || {

        // Attempt to acquire rundown protection, while the main
        // thread could be running down the object as we execute.
        //
        match rundown_clone.try_acquire() {
            Ok(run_down_guard) => {
                println!("{}: Run-down protection acquired.", i);

                // Stall the thread while holding rundown protection.
                thread::sleep(Duration::from_millis(10));
            }
            Err(m) => {
                println!("{}: Failed to acquire run-down protection - {:?}", i, m);
            },
        }
    });
}

println!("0: Waiting for rundown to complete");
rundown.wait_for_rundown();
println!("0: Rundown complete");

Structs

• RundownGuard
  An RAII implementation of a “scoped lock” pattern, but specialized to the needs of run-down protection. When this structure is dropped (falls out of scope), the rundown protection reference that was previously acquired is released.
• RundownRef
  Tracks the status of run-down protection for an object. The type would be embedded in the object needing run-down protection.

Enums

• RundownError
  The set of errors returned by methods in the run-down crate.