libsw/
lib.rs

1// libsw: stopwatch library
2// copyright (C) 2022-2023 Ula Shipman <ula.hello@mailbox.org>
3// licensed under MIT OR Apache-2.0
4
5//! `libsw` is a comprehensive stopwatch implementation.
6//!
7//! It offers [checked stopping](StopwatchImpl::checked_stop) and
8//! [arithmetic](StopwatchImpl::checked_add), [precise
9//! control](StopwatchImpl::start_at) over when operations occur, and supports
10//! [arbitrary timekeeping types](Instant).
11//!
12//! If you want to do benchmarking, please use something like
13//! [Criterion](https://docs.rs/criterion).
14//!
15//! # Introduction
16//!
17//! `libsw` provides the [`StopwatchImpl`] type as a stopwatch.
18//!
19//! This implementation is agnostic to the timekeeping type used, by virtue of
20//! being generic. Any type `I` that implements the [`Instant`] trait (as in
21//! `StopwatchImpl<I>`) can be used for timekeeping.
22//!
23//! `Instant` is implemented for several timekeeping types out of the box (see
24//! [timekeeping support](#timekeeping-support)). If present, these
25//! implementations are exposed as type aliases.
26//!
27//! # Features
28//!
29//! | Name             | Features enabled                | Description                                                                                             |
30//! |------------------|---------------------------------|---------------------------------------------------------------------------------------------------------|
31//! | `default`        | `std_instant`, `std_systemtime` | Enabled by default.                                                                                     |
32//! | `std`            |                                 | Depends on the standard library. Implements `std::error::Error` for [`Error`].                          |
33//! | `nightly`        |                                 | Implements `core::error::Error` for [`Error`] **if** `std` is not enabled. Requires a nightly compiler. |
34//! | `std_instant`    | `std`                           | Implements [`Instant`] for `std::time::Instant`. Exposes `Sw` type alias.                               |
35//! | `std_systemtime` | `std`                           | Implements [`Instant`] for `std::time::SystemTime`. Exposes `SystemSw` type alias.                      |
36//! | `tokio`          | `std`                           | Implements [`Instant`] for `tokio::time::Instant`. Exposes `TokioSw` type alias.                        |
37//! | `coarsetime`     | `std`                           | Implements [`Instant`] for `coarsetime::Instant`. Exposes `CoarseSw` type alias.                        |
38//! | `quanta`         | `std`                           | Implements [`Instant`] for `quanta::Instant`. Exposes `QuantaSw` type alias.                            |
39//! | `time`           | `std`                           | Deprecated. Implements [`Instant`] for `time::Instant`. Exposes `TimeSw` type alias.                    |
40//!
41//! ## Timekeeping support
42//!
43//! `libsw` can be used with any timekeeping type that implements [`Instant`],
44//! as long as the appropriate feature flag is enabled.
45//!
46//! See `Instant`'s [documentation](Instant#provided-implementations) for a list
47//! of types supported out of the box.
48//!
49//! ## `no_std` support
50//!
51//! The `std` feature flag unsets `#[no_std]`. It is enabled by default, but you
52//! can disable it by disabling the default features.
53//!
54//! In `Cargo.toml`,
55//!
56//! ```toml
57//! [dependencies]
58//! # replace '...' with the appropriate version
59//! libsw = { version = ..., default-features = false }
60//! ```
61//!
62//! # Compiler support
63//!
64//! Standalone, the minimum supported version of Rust is `1.61.0`.
65//! Adding dependencies may bump this.
66//!
67//! # Safety
68//!
69//! `libsw` contains no unsafe code (`#![forbid(unsafe_code)]`).
70
71#![cfg_attr(not(feature = "std"), no_std)]
72#![cfg_attr(all(feature = "nightly", not(feature = "std")), feature(error_in_core))]
73#![cfg_attr(doc_cfg, feature(doc_cfg))]
74#![forbid(unsafe_code)]
75#![warn(missing_docs, clippy::pedantic, clippy::cargo)]
76
77extern crate core;
78
79mod error;
80mod guard;
81mod stopwatch;
82
83pub use crate::error::{Error, Result};
84pub use crate::guard::Guard;
85pub use crate::stopwatch::StopwatchImpl;
86pub use ::libsw_core::Instant;
87
88/// Alias to [`StopwatchImpl`] using the standard library's
89/// [`Instant`](std::time::Instant) type.
90///
91/// This is the "default" stopwatch.
92#[cfg(feature = "std_instant")]
93#[cfg_attr(doc_cfg, doc(cfg(feature = "std_instant")))]
94pub type Sw = StopwatchImpl<::std::time::Instant>;
95
96/// Deprecated alias to the "default" stopwatch.
97#[cfg(feature = "std_instant")]
98#[cfg_attr(doc_cfg, doc(cfg(feature = "std_instant")))]
99#[deprecated(
100    since = "3.0.0",
101    note = "use `Sw` instead, an alias to `StopwatchImpl<std::time::Instant>`"
102)]
103pub type Stopwatch = Sw;
104
105/// Alias to [`StopwatchImpl`] using the standard library's
106/// [`SystemTime`](std::time::SystemTime) type.
107#[cfg(feature = "std_systemtime")]
108#[cfg_attr(doc_cfg, doc(cfg(feature = "std_systemtime")))]
109pub type SystemSw = StopwatchImpl<::std::time::SystemTime>;
110
111/// Alias to [`StopwatchImpl`] using Tokio's [`Instant`](tokio::time::Instant)
112/// type.
113#[cfg(feature = "tokio")]
114#[cfg_attr(doc_cfg, doc(cfg(feature = "tokio")))]
115pub type TokioSw = StopwatchImpl<::tokio::time::Instant>;
116
117/// Alias to [`StopwatchImpl`] using the `coarsetime` crate's
118/// [`Instant`](coarsetime::Instant) type.
119#[cfg(feature = "coarsetime")]
120#[cfg_attr(doc_cfg, doc(cfg(feature = "coarsetime")))]
121pub type CoarseSw = StopwatchImpl<::coarsetime::Instant>;
122
123/// Alias to [`StopwatchImpl`] using the `quanta` crate's
124/// [`Instant`](quanta::Instant) type.
125#[cfg(feature = "quanta")]
126#[cfg_attr(doc_cfg, doc(cfg(feature = "quanta")))]
127pub type QuantaSw = StopwatchImpl<::quanta::Instant>;
128
129/// Alias to [`StopwatchImpl`] using the `time` crate's
130/// [`Instant`](time::Instant) type.
131#[allow(deprecated)]
132#[cfg(feature = "time")]
133#[cfg_attr(doc_cfg, doc(cfg(feature = "time")))]
134#[deprecated(
135    note = "the `time` crate has deprecated `time::Instant` in favor of the `time::ext::InstantExt` trait used with `std::time::Instant`"
136)]
137pub type TimeSw = StopwatchImpl<::time::Instant>;
138
139#[cfg(test)]
140mod tests;
libsw/lib.rs

libsw/
lib.rs
