libsw_core/
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_core` is a comprehensive stopwatch implementation.
6//!
7//! It offers [checked stopping](Stopwatch::checked_stop) and
8//! [arithmetic](Stopwatch::checked_add), [precise
9//! control](Stopwatch::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_core` provides the [`Stopwatch`] type.
18//!
19//! This implementation is agnostic to the timekeeping type used, by
20//! virtue of being generic. Any type `I` that implements the [`Instant`]
21//! trait (as in `Stopwatch<I>`) can be used for timekeeping.
22//!
23//! `Instant` is implemented for several timekeeping types out of the box (see
24//! [features](#features)). If present, these
25//! implementations are exposed as type aliases.
26//!
27//! # Features
28//!
29//! | Name         | Implies | Description                                                                                                                               |
30//! |--------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------|
31//! | `default`    |         | Enabled by default.                                                                                                                       |
32//! | `std`        |         | Depends on the standard library. Implements [`Instant`] for `std::time::{Instant, SystemTime}`. Exposes `Sw` and `SystemSw` type aliases. |
33//! | `tokio`      | `std`   | Implements [`Instant`] for `tokio::time::Instant`. Exposes `TokioSw` type alias.                                                          |
34//! | `coarsetime` | `std`   | Implements [`Instant`] for `coarsetime::Instant`. Exposes `CoarseSw` type alias.                                                          |
35//! | `quanta`     | `std`   | Implements [`Instant`] for `quanta::Instant`. Exposes `QuantaSw` type alias.                                                              |
36//! | `time`       | `std`   | Deprecated. Implements [`Instant`] for `time::Instant`. Exposes `TimeSw` type alias.                                                      |
37//!
38//! ## `no_std` support
39//!
40//! `#![no_std]` is set by default.
41//!
42//! ## Compiler support
43//!
44//! Standalone, the minimum supported version of Rust is `1.61.0`.
45//! Adding dependencies may bump this.
46//!
47//! ## Safety
48//!
49//! `libsw_core` contains no unsafe code (`#![forbid(unsafe_code)]`).
50
51#![cfg_attr(not(feature = "std"), no_std)]
52#![cfg_attr(doc_cfg, feature(doc_cfg))]
53#![forbid(unsafe_code)]
54#![warn(missing_docs, clippy::pedantic, clippy::cargo)]
55
56extern crate core;
57
58mod canonical;
59mod instant;
60mod instant_impls;
61mod stopwatch;
62
63pub use crate::instant::Instant;
64pub use crate::stopwatch::Stopwatch;
65
66/// Alias to [`Stopwatch`] using the standard library's
67/// [`Instant`](std::time::Instant) type.
68#[cfg(feature = "std")]
69#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
70pub type Sw = Stopwatch<::std::time::Instant>;
71
72/// Alias to [`Stopwatch`] using the standard library's
73/// [`SystemTime`](std::time::SystemTime) type.
74#[cfg(feature = "std")]
75#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
76pub type SystemSw = Stopwatch<::std::time::SystemTime>;
77
78/// Alias to [`Stopwatch`] using Tokio's [`Instant`](tokio::time::Instant) type.
79#[cfg(feature = "tokio")]
80#[cfg_attr(doc_cfg, doc(cfg(feature = "tokio")))]
81pub type TokioSw = Stopwatch<::tokio::time::Instant>;
82
83/// Alias to [`Stopwatch`] using the `coarsetime` crate's
84/// [`Instant`](coarsetime::Instant) type.
85#[cfg(feature = "coarsetime")]
86#[cfg_attr(doc_cfg, doc(cfg(feature = "coarsetime")))]
87pub type CoarseSw = Stopwatch<::coarsetime::Instant>;
88
89/// Alias to [`Stopwatch`] using the `quanta` crate's
90/// [`Instant`](quanta::Instant) type.
91#[cfg(feature = "quanta")]
92#[cfg_attr(doc_cfg, doc(cfg(feature = "quanta")))]
93pub type QuantaSw = Stopwatch<::quanta::Instant>;
94
95/// Alias to [`Stopwatch`] using the `time` crate's [`Instant`](time::Instant)
96/// type.
97#[allow(deprecated)]
98#[cfg(feature = "time")]
99#[cfg_attr(doc_cfg, doc(cfg(feature = "time")))]
100#[deprecated(
101    note = "the `time` crate has deprecated `time::Instant` in favor of the `time::ext::InstantExt` trait used with `std::time::Instant`"
102)]
103pub type TimeSw = Stopwatch<::time::Instant>;
104
105#[cfg(test)]
106mod tests;
libsw_core/lib.rs

libsw_core/
lib.rs
