Crate libsw

libsw is a comprehensive stopwatch implementation.

Examples

The following (contrived) example shows the basic features of the crate. You are encouraged to read the examples provided for methods of StopwatchImpl and Guard for more complex use cases.

If you want to do benchmarking, please use something like Criterion.

use libsw::{Guard, Sw};

use core::time::Duration;
use std::thread;
use std::time::Instant;

fn main() {
    if let Err(err) = try_main() {
        // libsw::Error implements display, this
        // will explain the error
        eprintln!("error: {err}");
    }
}

fn try_main() -> libsw::Result<()> {
    let mut sw = Sw::new();

    // time how long `expensive` takes
    sw.start()?;
    let x = expensive();
    sw.stop()?;

    println!(
        "expensive function returned {x} after {:?}",
        sw.elapsed()
    );

    sw.reset();

    // another way to do this is with guards. the
    // guard will keep `sw` running until it's
    // dropped.
    let y = expensive_timed(sw.guard()?);
    println!(
        "same function returned {y} after {:?}",
        sw.elapsed()
    );

    sw.stop()?; // uh-oh, this will fail! the
                // stopwatch is already stopped.

    Ok(())
}

fn expensive() -> u32 {
    thread::sleep(Duration::from_millis(100));
    1
}

fn expensive_timed<I: libsw::Instant>(_guard: Guard<'_, I>) -> u32 {
    // guard is dropped when the function returns,
    // automatically stopping the guarded
    // stopwatch
    expensive()
}

Feature flags

Name	Features enabled	Description
default	std_instant, std_systemtime	Enabled by default.
std		Depends on the standard library. Implements std::error::Error for Error.
nightly		Implements core::error::Error for Error if std is not enabled. Requires a nightly compiler.
std_instant	std	Implements Instant for std::time::Instant. Exposes Sw type alias.
std_systemtime	std	Implements Instant for std::time::SystemTime.
tokio	std	Implements Instant for tokio::time::Instant. Exposes TokioSw type alias.

Timekeeping support

libsw can be used with any timekeeping type that implements Instant, as long as the appropriate feature flag is enabled.

See Instant’s documentation for a list of types supported out of the box.

no_std support

The std feature flag unsets #[no_std]. It is enabled by default, but you can disable it by disabling the default features.

In Cargo.toml,

[dependencies]
# replace '...' with the appropriate version
libsw = { version = ..., default-features = false }

Compiler support

The minimum supported version of Rust is 1.61.0.

Safety

libsw contains no unsafe code (#![forbid(unsafe_code)]).

Structs

Guard

A running, guarded, stopwatch. When dropped, the stopwatch will automatically stop.

StopwatchImpl

A stopwatch measures and accumulates elapsed time between starts and stops.

Enums

Error

Enumeration over possible errors.

Traits

Instant

A trait outlining the behavior of a timekeeping type.

Type Definitions

Result

Alias to Result<T, Error>.

StopwatchDeprecated

Deprecated alias to the “default” stopwatch.

Sw

Alias to StopwatchImpl using the standard library’s Instant type.