pw_time/
pw_time.rs

1// Copyright 2026 The Pigweed Authors
2//
3// Licensed under the Apache License, Version 2.0 (the "License"); you may not
4// use this file except in compliance with the License. You may obtain a copy of
5// the License at
6//
7//     https://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12// License for the specific language governing permissions and limitations under
13// the License.
14#![no_std]
15
16//! # pw_time
17//!
18//! `pw_time` provides time types and a system clock.
19//!
20//!  * [`Clock`] - A monotonically increasing clock with its own scale between
21//!    internal "ticks" and human time.
22//!  * [`Instant<Clock>`] - A sample of a specific instant on a given [`Clock`].
23//!  * [`Duration<Clock>`] - A span of time whose internal representation is scaled to
24//!    the given [`Clock`].
25//!  * [`SystemClock`] - The clock used by the core system/RTOS.
26//!
27//! ## Examples
28//!
29//! ```
30//! # #[unsafe(no_mangle)]
31//! # unsafe extern "C-unwind" fn pw_assert_HandleFailure() -> ! { loop {} }
32//! use pw_time::{SystemClock, Instant, Duration, Clock};
33//!
34//! let start = SystemClock::now();
35//! let duration = Duration::from_millis(500);
36//! let end = start + duration;
37//! assert_eq!(end - start, duration);
38//! ```
39//!
40//! ## Design
41//!
42//! #### Clocks
43//!
44//! `pw_time` is designed to allow type-safe handling of systems with multiple
45//! clock domains.  Each clock domain is defined by a [`Clock`].  [`Instant`]
46//! and [`Duration`] are generic of a [`Clock`] and can not be mixed.
47//!
48//! #### Representation
49//!
50//! `pw_time` uses 64 bit internal types to represent [`Instant`]s (unsigned)
51//! and [`Duration`]s (signed).  The scale of this internal value is defined
52//! by the [`Clock::TICKS_PER_SEC`].  Future work may move from this scalar
53//! scale to a ratio based one similar to C++'s `std::chrono` types.
54//!
55//! #### Const conversion
56//!
57//! [`Duration`]'s `from_*` constructors are const and are designed to be
58//! optimized into single "tick native" values by the compiler.
59//!
60//! #### Panic behavior
61//!
62//! `pw_time` is designed to never cause a Rust `panic` because this can lead
63//! to code size bloat on size constrained systems.  Instead it relies on
64//! [`pw_assert`] to allow system specific panic behavior.
65
66/// The clock used by the core system/RTOS
67///
68/// This clock is by the system for time bound operations such as thread
69/// sleeping, waiting on mutexes/semaphores, etc.  The clock's rate is system
70/// dependent.
71pub use pw_time_backend::SystemClock;
72pub use pw_time_core::{Clock, Duration, Instant};
pw_time/pw_time.rs

pw_time/
pw_time.rs
