// SPDX-License-Identifier: GPL-2.0 //! Time related primitives.//!//! This module contains the kernel APIs related to time and timers that//! have been ported or wrapped for usage by Rust code in the kernel.//!//! There are two types in this module://!//! - The [`Instant`] type represents a specific point in time.//! - The [`Delta`] type represents a span of time.//!//! Note that the C side uses `ktime_t` type to represent both. However, timestamp//! and timedelta are different. To avoid confusion, we use two different types.//!//! A [`Instant`] object can be created by calling the [`Instant::now()`] function.//! It represents a point in time at which the object was created.//! By calling the [`Instant::elapsed()`] method, a [`Delta`] object representing//! the elapsed time can be created. The [`Delta`] object can also be created//! by subtracting two [`Instant`] objects.//!//! A [`Delta`] type supports methods to retrieve the duration in various units.//!//! C header: [`include/linux/jiffies.h`](srctree/include/linux/jiffies.h).//! C header: [`include/linux/ktime.h`](srctree/include/linux/ktime.h). use core::marker::PhantomData;use core::ops; pub mod delay;pub mod hrtimer; /// The number of nanoseconds per microsecond.pub const NSEC_PER_USEC: i64 = bindings::NSEC_PER_USEC as i64; /// The number of nanoseconds per millisecond.pub const NSEC_PER_MSEC: i64 = bindings::NSEC_PER_MSEC as i64; /// The number of nanoseconds per second.pub const NSEC_PER_SEC: i64 = bindings::NSEC_PER_SEC as i64; /// The time unit of Linux kernel. One jiffy equals (1/HZ) second.pub type Jiffies = crate::ffi::c_ulong; /// The millisecond time unit.pub type Msecs = crate::ffi::c_uint; /// Converts milliseconds to jiffies.#[inline]pub fn msecs_to_jiffies(msecs: Msecs) -> Jiffies { // SAFETY: The `__msecs_to_jiffies` function is always safe to call no // matter what the argument is. unsafe { bindings::__msecs_to_jiffies(msecs) }} /// Trait for clock sources.////// Selection of the clock source depends on the use case. In some cases the usage of a/// particular clock is mandatory, e.g. in network protocols, filesystems. In other/// cases the user of the clock has to decide which clock is best suited for the/// purpose. In most scenarios clock [`Monotonic`] is the best choice as it/// provides a accurate monotonic notion of time (leap second smearing ignored).////// # Safety////// Implementers must ensure that `ktime_get()` returns a value in the inclusive range/// `0..=KTIME_MAX` (i.e., greater than or equal to 0 and less than or equal to/// `KTIME_MAX`, where `KTIME_MAX` equals `i64::MAX`).pub unsafe trait ClockSource { /// The kernel clock ID associated with this clock source. /// /// This constant corresponds to the C side `clockid_t` value. const ID: bindings::clockid_t; /// Get the current time from the clock source. /// /// The function must return a value in the range `0..=KTIME_MAX`. fn ktime_get() -> bindings::ktime_t;} /// A monotonically increasing clock.////// A nonsettable system-wide clock that represents monotonic time since as/// described by POSIX, "some unspecified point in the past". On Linux, that/// point corresponds to the number of seconds that the system has been/// running since it was booted.////// The CLOCK_MONOTONIC clock is not affected by discontinuous jumps in the/// CLOCK_REAL (e.g., if the system administrator manually changes the/// clock), but is affected by frequency adjustments. This clock does not/// count time that the system is suspended.pub struct Monotonic; // SAFETY: The kernel's `ktime_get()` is guaranteed to return a value// in `0..=KTIME_MAX`.unsafe impl ClockSource for Monotonic { const ID: bindings::clockid_t = bindings::CLOCK_MONOTONIC as bindings::clockid_t; fn ktime_get() -> bindings::ktime_t { // SAFETY: It is always safe to call `ktime_get()` outside of NMI context. unsafe { bindings::ktime_get() } }} /// A settable system-wide clock that measures real (i.e., wall-clock) time.////// Setting this clock requires appropriate privileges. This clock is/// affected by discontinuous jumps in the system time (e.g., if the system/// administrator manually changes the clock), and by frequency adjustments/// performed by NTP and similar applications via adjtime(3), adjtimex(2),/// clock_adjtime(2), and ntp_adjtime(3). This clock normally counts the/// number of seconds since 1970-01-01 00:00:00 Coordinated Universal Time/// (UTC) except that it ignores leap seconds; near a leap second it may be/// adjusted by leap second smearing to stay roughly in sync with UTC. Leap/// second smearing applies frequency adjustments to the clock to speed up/// or slow down the clock to account for the leap second without/// discontinuities in the clock. If leap second smearing is not applied,/// the clock will experience discontinuity around leap second adjustment.pub struct RealTime; // SAFETY: The kernel's `ktime_get_real()` is guaranteed to return a value// in `0..=KTIME_MAX`.unsafe impl ClockSource for RealTime { const ID: bindings::clockid_t = bindings::CLOCK_REALTIME as bindings::clockid_t; fn ktime_get() -> bindings::ktime_t { // SAFETY: It is always safe to call `ktime_get_real()` outside of NMI context. unsafe { bindings::ktime_get_real() } }} /// A monotonic that ticks while system is suspended.////// A nonsettable system-wide clock that is identical to CLOCK_MONOTONIC,/// except that it also includes any time that the system is suspended. This/// allows applications to get a suspend-aware monotonic clock without/// having to deal with the complications of CLOCK_REALTIME, which may have/// discontinuities if the time is changed using settimeofday(2) or similar.pub struct BootTime; // SAFETY: The kernel's `ktime_get_boottime()` is guaranteed to return a value// in `0..=KTIME_MAX`.unsafe impl ClockSource for BootTime { const ID: bindings::clockid_t = bindings::CLOCK_BOOTTIME as bindings::clockid_t; fn ktime_get() -> bindings::ktime_t { // SAFETY: It is always safe to call `ktime_get_boottime()` outside of NMI context. unsafe { bindings::ktime_get_boottime() } }} /// International Atomic Time.////// A system-wide clock derived from wall-clock time but counting leap seconds.////// This clock is coupled to CLOCK_REALTIME and will be set when CLOCK_REALTIME is/// set, or when the offset to CLOCK_REALTIME is changed via adjtimex(2). This/// usually happens during boot and **should** not happen during normal operations./// However, if NTP or another application adjusts CLOCK_REALTIME by leap second/// smearing, this clock will not be precise during leap second smearing.////// The acronym TAI refers to International Atomic Time.pub struct Tai; // SAFETY: The kernel's `ktime_get_clocktai()` is guaranteed to return a value// in `0..=KTIME_MAX`.unsafe impl ClockSource for Tai { const ID: bindings::clockid_t = bindings::CLOCK_TAI as bindings::clockid_t; fn ktime_get() -> bindings::ktime_t { // SAFETY: It is always safe to call `ktime_get_tai()` outside of NMI context. unsafe { bindings::ktime_get_clocktai() } }} /// A specific point in time.////// # Invariants////// The `inner` value is in the range from 0 to `KTIME_MAX`.#[repr(transparent)]#[derive(PartialEq, PartialOrd, Eq, Ord)]pub struct Instant<C: ClockSource> { inner: bindings::ktime_t, _c: PhantomData<C>,} impl<C: ClockSource> Clone for Instant<C> { fn clone(&self) -> Self { *self }} impl<C: ClockSource> Copy for Instant<C> {} impl<C: ClockSource> Instant<C> { /// Get the current time from the clock source. #[inline] pub fn now() -> Self { // INVARIANT: The `ClockSource::ktime_get()` function returns a value in the range // from 0 to `KTIME_MAX`. Self { inner: C::ktime_get(), _c: PhantomData, } } /// Return the amount of time elapsed since the [`Instant`]. #[inline] pub fn elapsed(&self) -> Delta { Self::now() - *self } #[inline] pub(crate) fn as_nanos(&self) -> i64 { self.inner } /// Create an [`Instant`] from a `ktime_t` without checking if it is non-negative. /// /// # Panics /// /// On debug builds, this function will panic if `ktime` is not in the range from 0 to /// `KTIME_MAX`. /// /// # Safety /// /// The caller promises that `ktime` is in the range from 0 to `KTIME_MAX`. #[inline] pub(crate) unsafe fn from_ktime(ktime: bindings::ktime_t) -> Self { debug_assert!(ktime >= 0); // INVARIANT: Our safety contract ensures that `ktime` is in the range from 0 to // `KTIME_MAX`. Self { inner: ktime, _c: PhantomData, } }} impl<C: ClockSource> ops::Sub for Instant<C> { type Output = Delta; // By the type invariant, it never overflows. #[inline] fn sub(self, other: Instant<C>) -> Delta { Delta { value: self.inner - other.inner, } }} impl<T: ClockSource> ops::Add<Delta> for Instant<T> { type Output = Self; #[inline] fn add(self, rhs: Delta) -> Self::Output { // INVARIANT: With arithmetic over/underflow checks enabled, this will panic if we overflow // (e.g. go above `KTIME_MAX`) let res = self.inner + rhs.value; // INVARIANT: With overflow checks enabled, we verify here that the value is >= 0 #[cfg(CONFIG_RUST_OVERFLOW_CHECKS)] assert!(res >= 0); Self { inner: res, _c: PhantomData, } }} impl<T: ClockSource> ops::Sub<Delta> for Instant<T> { type Output = Self; #[inline] fn sub(self, rhs: Delta) -> Self::Output { // INVARIANT: With arithmetic over/underflow checks enabled, this will panic if we overflow // (e.g. go above `KTIME_MAX`) let res = self.inner - rhs.value; // INVARIANT: With overflow checks enabled, we verify here that the value is >= 0 #[cfg(CONFIG_RUST_OVERFLOW_CHECKS)] assert!(res >= 0); Self { inner: res, _c: PhantomData, } }} mod private { pub trait Sealed {} impl Sealed for super::Nsec {} impl Sealed for super::Jiffy {}} /// A trait for time units.pub trait TimeUnit: private::Sealed { /// The underlying representation of the time unit. type Repr: Copy + Clone + PartialEq + PartialOrd + Eq + Ord + core::fmt::Debug;} /// A time unit of nanoseconds.////// A [`Delta<Nsec>`] stores its value as [`i64`] nanoseconds and can represent/// any [`i64`] value, including negative, zero, and positive numbers.#[derive(Copy, Clone, PartialEq, PartialOrd, Eq, Ord, Debug)]pub enum Nsec {} impl TimeUnit for Nsec { type Repr = i64;} /// A time unit of jiffies.////// A [`Delta<Jiffy>`] stores its value as [`isize`] jiffies and can represent/// any [`isize`] value, including negative, zero, and positive numbers.#[derive(Copy, Clone, PartialEq, PartialOrd, Eq, Ord, Debug)]pub enum Jiffy {} impl TimeUnit for Jiffy { type Repr = isize;} /// A span of time.////// The span is stored in the unit given by the type parameter `U` (see/// [`TimeUnit`]); its value has type `U::Repr`. `U` defaults to [`Nsec`], so a/// plain [`Delta`] is a span in nanoseconds. The value can be negative, zero, or/// positive.#[derive(Copy, Clone, PartialEq, PartialOrd, Eq, Ord, Debug)]pub struct Delta<U: TimeUnit = Nsec> { value: U::Repr,} impl Delta<Jiffy> { /// Create a new [`Delta`] from a number of jiffies. #[inline] pub const fn from_jiffies(jiffies: isize) -> Self { Self { value: jiffies } } /// Return the number of jiffies in the [`Delta`]. #[inline] pub const fn as_jiffies(self) -> isize { self.value }} impl ops::Add for Delta { type Output = Self; #[inline] fn add(self, rhs: Self) -> Self { Self { value: self.value + rhs.value, } }} impl ops::AddAssign for Delta { #[inline] fn add_assign(&mut self, rhs: Self) { self.value += rhs.value; }} impl ops::Sub for Delta { type Output = Self; #[inline] fn sub(self, rhs: Self) -> Self::Output { Self { value: self.value - rhs.value, } }} impl ops::SubAssign for Delta { #[inline] fn sub_assign(&mut self, rhs: Self) { self.value -= rhs.value; }} impl ops::Mul<i64> for Delta { type Output = Self; #[inline] fn mul(self, rhs: i64) -> Self::Output { Self { value: self.value * rhs, } }} impl ops::MulAssign<i64> for Delta { #[inline] fn mul_assign(&mut self, rhs: i64) { self.value *= rhs; }} impl ops::Div for Delta { type Output = i64; #[inline] fn div(self, rhs: Self) -> Self::Output { #[cfg(CONFIG_64BIT)] { self.value / rhs.value } #[cfg(not(CONFIG_64BIT))] { // SAFETY: This function is always safe to call regardless of the input values unsafe { bindings::div64_s64(self.value, rhs.value) } } }} impl Delta { /// A span of time equal to zero. pub const ZERO: Self = Self { value: 0 }; /// Create a new [`Delta`] from a number of nanoseconds. #[inline] pub const fn from_nanos(nanos: i64) -> Self { Self { value: nanos } } /// Create a new [`Delta`] from a number of microseconds. /// /// The `micros` can range from -9_223_372_036_854_775 to 9_223_372_036_854_775. /// If `micros` is outside this range, `i64::MIN` is used for negative values, /// and `i64::MAX` is used for positive values due to saturation. #[inline] pub const fn from_micros(micros: i64) -> Self { Self { value: micros.saturating_mul(NSEC_PER_USEC), } } /// Create a new [`Delta`] from a number of milliseconds. /// /// The `millis` can range from -9_223_372_036_854 to 9_223_372_036_854. /// If `millis` is outside this range, `i64::MIN` is used for negative values, /// and `i64::MAX` is used for positive values due to saturation. #[inline] pub const fn from_millis(millis: i64) -> Self { Self { value: millis.saturating_mul(NSEC_PER_MSEC), } } /// Create a new [`Delta`] from a number of seconds. /// /// The `secs` can range from -9_223_372_036 to 9_223_372_036. /// If `secs` is outside this range, `i64::MIN` is used for negative values, /// and `i64::MAX` is used for positive values due to saturation. #[inline] pub const fn from_secs(secs: i64) -> Self { Self { value: secs.saturating_mul(NSEC_PER_SEC), } } /// Return `true` if the [`Delta`] spans no time. #[inline] pub fn is_zero(self) -> bool { self.as_nanos() == 0 } /// Return `true` if the [`Delta`] spans a negative amount of time. #[inline] pub fn is_negative(self) -> bool { self.as_nanos() < 0 } /// Return the number of nanoseconds in the [`Delta`]. #[inline] pub const fn as_nanos(self) -> i64 { self.value } /// Return the smallest number of microseconds greater than or equal /// to the value in the [`Delta`]. #[inline] pub fn as_micros_ceil(self) -> i64 { // Only positive values need to be rounded up: truncating division already // rounds towards zero, i.e. up, for negative values. // // The usual `(nanos + d - 1) / d` is not used because the addition overflows // once `nanos` exceeds `i64::MAX - (d - 1)`; saturating the addition instead // would drop the rounding bias and return a result one unit too small. let n = self.as_nanos();Lines 1–500 of 582. Load more
// SPDX-License-Identifier: GPL-2.0 //! Time related primitives. //! //! This module contains the kernel APIs related to time and timers that //! have been ported or wrapped for usage by Rust code in the kernel. //! //! There are two types in this module: //! //! - The [`Instant`] type represents a specific point in time. //! - The [`Delta`] type represents a span of time. //! //! Note that the C side uses `ktime_t` type to represent both. However, timestamp //! and timedelta are different. To avoid confusion, we use two different types. //! //! A [`Instant`] object can be created by calling the [`Instant::now()`] function. //! It represents a point in time at which the object was created. //! By calling the [`Instant::elapsed()`] method, a [`Delta`] object representing //! the elapsed time can be created. The [`Delta`] object can also be created //! by subtracting two [`Instant`] objects. //! //! A [`Delta`] type supports methods to retrieve the duration in various units. //! //! C header: [`include/linux/jiffies.h`](srctree/include/linux/jiffies.h). //! C header: [`include/linux/ktime.h`](srctree/include/linux/ktime.h). use core::marker::PhantomData; use core::ops; pub mod delay; pub mod hrtimer; /// The number of nanoseconds per microsecond. pub const NSEC_PER_USEC: i64 = bindings::NSEC_PER_USEC as i64; /// The number of nanoseconds per millisecond. pub const NSEC_PER_MSEC: i64 = bindings::NSEC_PER_MSEC as i64; /// The number of nanoseconds per second. pub const NSEC_PER_SEC: i64 = bindings::NSEC_PER_SEC as i64; /// The time unit of Linux kernel. One jiffy equals (1/HZ) second. pub type Jiffies = crate::ffi::c_ulong; /// The millisecond time unit. pub type Msecs = crate::ffi::c_uint; /// Converts milliseconds to jiffies. #[inline] pub fn msecs_to_jiffies(msecs: Msecs) -> Jiffies { // SAFETY: The `__msecs_to_jiffies` function is always safe to call no // matter what the argument is. unsafe { bindings::__msecs_to_jiffies(msecs) } } /// Trait for clock sources. /// /// Selection of the clock source depends on the use case. In some cases the usage of a /// particular clock is mandatory, e.g. in network protocols, filesystems. In other /// cases the user of the clock has to decide which clock is best suited for the /// purpose. In most scenarios clock [`Monotonic`] is the best choice as it /// provides a accurate monotonic notion of time (leap second smearing ignored). /// /// # Safety /// /// Implementers must ensure that `ktime_get()` returns a value in the inclusive range /// `0..=KTIME_MAX` (i.e., greater than or equal to 0 and less than or equal to /// `KTIME_MAX`, where `KTIME_MAX` equals `i64::MAX`). pub unsafe trait ClockSource { /// The kernel clock ID associated with this clock source. /// /// This constant corresponds to the C side `clockid_t` value. const ID: bindings::clockid_t; /// Get the current time from the clock source. /// /// The function must return a value in the range `0..=KTIME_MAX`. fn ktime_get() -> bindings::ktime_t; } /// A monotonically increasing clock. /// /// A nonsettable system-wide clock that represents monotonic time since as /// described by POSIX, "some unspecified point in the past". On Linux, that /// point corresponds to the number of seconds that the system has been /// running since it was booted. /// /// The CLOCK_MONOTONIC clock is not affected by discontinuous jumps in the /// CLOCK_REAL (e.g., if the system administrator manually changes the /// clock), but is affected by frequency adjustments. This clock does not /// count time that the system is suspended. pub struct Monotonic; // SAFETY: The kernel's `ktime_get()` is guaranteed to return a value // in `0..=KTIME_MAX`. unsafe impl ClockSource for Monotonic { const ID: bindings::clockid_t = bindings::CLOCK_MONOTONIC as bindings::clockid_t; fn ktime_get() -> bindings::ktime_t { // SAFETY: It is always safe to call `ktime_get()` outside of NMI context. unsafe { bindings::ktime_get() } } } /// A settable system-wide clock that measures real (i.e., wall-clock) time. /// /// Setting this clock requires appropriate privileges. This clock is /// affected by discontinuous jumps in the system time (e.g., if the system /// administrator manually changes the clock), and by frequency adjustments /// performed by NTP and similar applications via adjtime(3), adjtimex(2), /// clock_adjtime(2), and ntp_adjtime(3). This clock normally counts the /// number of seconds since 1970-01-01 00:00:00 Coordinated Universal Time /// (UTC) except that it ignores leap seconds; near a leap second it may be /// adjusted by leap second smearing to stay roughly in sync with UTC. Leap /// second smearing applies frequency adjustments to the clock to speed up /// or slow down the clock to account for the leap second without /// discontinuities in the clock. If leap second smearing is not applied, /// the clock will experience discontinuity around leap second adjustment. pub struct RealTime; // SAFETY: The kernel's `ktime_get_real()` is guaranteed to return a value // in `0..=KTIME_MAX`. unsafe impl ClockSource for RealTime { const ID: bindings::clockid_t = bindings::CLOCK_REALTIME as bindings::clockid_t; fn ktime_get() -> bindings::ktime_t { // SAFETY: It is always safe to call `ktime_get_real()` outside of NMI context. unsafe { bindings::ktime_get_real() } } } /// A monotonic that ticks while system is suspended. /// /// A nonsettable system-wide clock that is identical to CLOCK_MONOTONIC, /// except that it also includes any time that the system is suspended. This /// allows applications to get a suspend-aware monotonic clock without /// having to deal with the complications of CLOCK_REALTIME, which may have /// discontinuities if the time is changed using settimeofday(2) or similar. pub struct BootTime; // SAFETY: The kernel's `ktime_get_boottime()` is guaranteed to return a value // in `0..=KTIME_MAX`. unsafe impl ClockSource for BootTime { const ID: bindings::clockid_t = bindings::CLOCK_BOOTTIME as bindings::clockid_t; fn ktime_get() -> bindings::ktime_t { // SAFETY: It is always safe to call `ktime_get_boottime()` outside of NMI context. unsafe { bindings::ktime_get_boottime() } } } /// International Atomic Time. /// /// A system-wide clock derived from wall-clock time but counting leap seconds. /// /// This clock is coupled to CLOCK_REALTIME and will be set when CLOCK_REALTIME is /// set, or when the offset to CLOCK_REALTIME is changed via adjtimex(2). This /// usually happens during boot and **should** not happen during normal operations. /// However, if NTP or another application adjusts CLOCK_REALTIME by leap second /// smearing, this clock will not be precise during leap second smearing. /// /// The acronym TAI refers to International Atomic Time. pub struct Tai; // SAFETY: The kernel's `ktime_get_clocktai()` is guaranteed to return a value // in `0..=KTIME_MAX`. unsafe impl ClockSource for Tai { const ID: bindings::clockid_t = bindings::CLOCK_TAI as bindings::clockid_t; fn ktime_get() -> bindings::ktime_t { // SAFETY: It is always safe to call `ktime_get_tai()` outside of NMI context. unsafe { bindings::ktime_get_clocktai() } } } /// A specific point in time. /// /// # Invariants /// /// The `inner` value is in the range from 0 to `KTIME_MAX`. #[repr(transparent)] #[derive(PartialEq, PartialOrd, Eq, Ord)] pub struct Instant<C: ClockSource> { inner: bindings::ktime_t, _c: PhantomData<C>, } impl<C: ClockSource> Clone for Instant<C> { fn clone(&self) -> Self { *self } } impl<C: ClockSource> Copy for Instant<C> {} impl<C: ClockSource> Instant<C> { /// Get the current time from the clock source. #[inline] pub fn now() -> Self { // INVARIANT: The `ClockSource::ktime_get()` function returns a value in the range // from 0 to `KTIME_MAX`. Self { inner: C::ktime_get(), _c: PhantomData, } } /// Return the amount of time elapsed since the [`Instant`]. #[inline] pub fn elapsed(&self) -> Delta { Self::now() - *self } #[inline] pub(crate) fn as_nanos(&self) -> i64 { self.inner } /// Create an [`Instant`] from a `ktime_t` without checking if it is non-negative. /// /// # Panics /// /// On debug builds, this function will panic if `ktime` is not in the range from 0 to /// `KTIME_MAX`. /// /// # Safety /// /// The caller promises that `ktime` is in the range from 0 to `KTIME_MAX`. #[inline] pub(crate) unsafe fn from_ktime(ktime: bindings::ktime_t) -> Self { debug_assert!(ktime >= 0); // INVARIANT: Our safety contract ensures that `ktime` is in the range from 0 to // `KTIME_MAX`. Self { inner: ktime, _c: PhantomData, } } } impl<C: ClockSource> ops::Sub for Instant<C> { type Output = Delta; // By the type invariant, it never overflows. #[inline] fn sub(self, other: Instant<C>) -> Delta { Delta { value: self.inner - other.inner, } } } impl<T: ClockSource> ops::Add<Delta> for Instant<T> { type Output = Self; #[inline] fn add(self, rhs: Delta) -> Self::Output { // INVARIANT: With arithmetic over/underflow checks enabled, this will panic if we overflow // (e.g. go above `KTIME_MAX`) let res = self.inner + rhs.value; // INVARIANT: With overflow checks enabled, we verify here that the value is >= 0 #[cfg(CONFIG_RUST_OVERFLOW_CHECKS)] assert!(res >= 0); Self { inner: res, _c: PhantomData, } } } impl<T: ClockSource> ops::Sub<Delta> for Instant<T> { type Output = Self; #[inline] fn sub(self, rhs: Delta) -> Self::Output { // INVARIANT: With arithmetic over/underflow checks enabled, this will panic if we overflow // (e.g. go above `KTIME_MAX`) let res = self.inner - rhs.value; // INVARIANT: With overflow checks enabled, we verify here that the value is >= 0 #[cfg(CONFIG_RUST_OVERFLOW_CHECKS)] assert!(res >= 0); Self { inner: res, _c: PhantomData, } } } mod private { pub trait Sealed {} impl Sealed for super::Nsec {} impl Sealed for super::Jiffy {} } /// A trait for time units. pub trait TimeUnit: private::Sealed { /// The underlying representation of the time unit. type Repr: Copy + Clone + PartialEq + PartialOrd + Eq + Ord + core::fmt::Debug; } /// A time unit of nanoseconds. /// /// A [`Delta<Nsec>`] stores its value as [`i64`] nanoseconds and can represent /// any [`i64`] value, including negative, zero, and positive numbers. #[derive(Copy, Clone, PartialEq, PartialOrd, Eq, Ord, Debug)] pub enum Nsec {} impl TimeUnit for Nsec { type Repr = i64; } /// A time unit of jiffies. /// /// A [`Delta<Jiffy>`] stores its value as [`isize`] jiffies and can represent /// any [`isize`] value, including negative, zero, and positive numbers. #[derive(Copy, Clone, PartialEq, PartialOrd, Eq, Ord, Debug)] pub enum Jiffy {} impl TimeUnit for Jiffy { type Repr = isize; } /// A span of time. /// /// The span is stored in the unit given by the type parameter `U` (see /// [`TimeUnit`]); its value has type `U::Repr`. `U` defaults to [`Nsec`], so a /// plain [`Delta`] is a span in nanoseconds. The value can be negative, zero, or /// positive. #[derive(Copy, Clone, PartialEq, PartialOrd, Eq, Ord, Debug)] pub struct Delta<U: TimeUnit = Nsec> { value: U::Repr, } impl Delta<Jiffy> { /// Create a new [`Delta`] from a number of jiffies. #[inline] pub const fn from_jiffies(jiffies: isize) -> Self { Self { value: jiffies } } /// Return the number of jiffies in the [`Delta`]. #[inline] pub const fn as_jiffies(self) -> isize { self.value } } impl ops::Add for Delta { type Output = Self; #[inline] fn add(self, rhs: Self) -> Self { Self { value: self.value + rhs.value, } } } impl ops::AddAssign for Delta { #[inline] fn add_assign(&mut self, rhs: Self) { self.value += rhs.value; } } impl ops::Sub for Delta { type Output = Self; #[inline] fn sub(self, rhs: Self) -> Self::Output { Self { value: self.value - rhs.value, } } } impl ops::SubAssign for Delta { #[inline] fn sub_assign(&mut self, rhs: Self) { self.value -= rhs.value; } } impl ops::Mul<i64> for Delta { type Output = Self; #[inline] fn mul(self, rhs: i64) -> Self::Output { Self { value: self.value * rhs, } } } impl ops::MulAssign<i64> for Delta { #[inline] fn mul_assign(&mut self, rhs: i64) { self.value *= rhs; } } impl ops::Div for Delta { type Output = i64; #[inline] fn div(self, rhs: Self) -> Self::Output { #[cfg(CONFIG_64BIT)] { self.value / rhs.value } #[cfg(not(CONFIG_64BIT))] { // SAFETY: This function is always safe to call regardless of the input values unsafe { bindings::div64_s64(self.value, rhs.value) } } } } impl Delta { /// A span of time equal to zero. pub const ZERO: Self = Self { value: 0 }; /// Create a new [`Delta`] from a number of nanoseconds. #[inline] pub const fn from_nanos(nanos: i64) -> Self { Self { value: nanos } } /// Create a new [`Delta`] from a number of microseconds. /// /// The `micros` can range from -9_223_372_036_854_775 to 9_223_372_036_854_775. /// If `micros` is outside this range, `i64::MIN` is used for negative values, /// and `i64::MAX` is used for positive values due to saturation. #[inline] pub const fn from_micros(micros: i64) -> Self { Self { value: micros.saturating_mul(NSEC_PER_USEC), } } /// Create a new [`Delta`] from a number of milliseconds. /// /// The `millis` can range from -9_223_372_036_854 to 9_223_372_036_854. /// If `millis` is outside this range, `i64::MIN` is used for negative values, /// and `i64::MAX` is used for positive values due to saturation. #[inline] pub const fn from_millis(millis: i64) -> Self { Self { value: millis.saturating_mul(NSEC_PER_MSEC), } } /// Create a new [`Delta`] from a number of seconds. /// /// The `secs` can range from -9_223_372_036 to 9_223_372_036. /// If `secs` is outside this range, `i64::MIN` is used for negative values, /// and `i64::MAX` is used for positive values due to saturation. #[inline] pub const fn from_secs(secs: i64) -> Self { Self { value: secs.saturating_mul(NSEC_PER_SEC), } } /// Return `true` if the [`Delta`] spans no time. #[inline] pub fn is_zero(self) -> bool { self.as_nanos() == 0 } /// Return `true` if the [`Delta`] spans a negative amount of time. #[inline] pub fn is_negative(self) -> bool { self.as_nanos() < 0 } /// Return the number of nanoseconds in the [`Delta`]. #[inline] pub const fn as_nanos(self) -> i64 { self.value } /// Return the smallest number of microseconds greater than or equal /// to the value in the [`Delta`]. #[inline] pub fn as_micros_ceil(self) -> i64 { // Only positive values need to be rounded up: truncating division already // rounds towards zero, i.e. up, for negative values. // // The usual `(nanos + d - 1) / d` is not used because the addition overflows // once `nanos` exceeds `i64::MAX - (d - 1)`; saturating the addition instead // would drop the rounding bias and return a result one unit too small. let n = self.as_nanos();