From: Alice Ryhl <aliceryhl@google.com>

Introduce a type representing time duration. Define our own type instead
of using `core::time::Duration` because in kernel C code, an i64
(ktime_t) is used for representing time durations, an i64 backed
duration type is more efficient when interacting with time APIs in C.

Signed-off-by: Alice Ryhl <aliceryhl@google.com>
[boqun: Rename `Ktime` to `Duration`, and make it a type of durations]
Signed-off-by: Boqun Feng <boqun.feng@gmail.com>
---
 rust/kernel/time.rs | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/rust/kernel/time.rs b/rust/kernel/time.rs
index bbb666e64dd7..b238b3a4e899 100644
--- a/rust/kernel/time.rs
+++ b/rust/kernel/time.rs
@@ -7,6 +7,9 @@
 //!
 //! C header: [`include/linux/jiffies.h`](srctree/include/linux/jiffies.h).
 
+/// The number of nanoseconds per millisecond.
+pub const NSEC_PER_MSEC: i64 = bindings::NSEC_PER_MSEC as i64;
+
 /// The time unit of Linux kernel. One jiffy equals (1/HZ) second.
 pub type Jiffies = core::ffi::c_ulong;
 
@@ -20,3 +23,44 @@ pub fn msecs_to_jiffies(msecs: Msecs) -> Jiffies {
     // matter what the argument is.
     unsafe { bindings::__msecs_to_jiffies(msecs) }
 }
+
+/// A time duration.
+///
+/// # Examples
+///
+/// ```
+/// let one_second = kernel::time::Duration::new(1000_000_000);
+///
+/// // 1 second is 1000 milliseconds.
+/// assert_eq!(one_second.to_ms(), 1000);
+/// ```
+#[repr(transparent)]
+#[derive(Copy, Clone, Debug)]
+pub struct Duration {
+    inner: i64,
+}
+
+impl Duration {
+    /// Creates a new duration of `ns` nanoseconds.
+    pub const fn new(ns: i64) -> Self {
+        Self { inner: ns }
+    }
+
+    /// Divides the number of nanoseconds by a compile-time constant.
+    #[inline]
+    fn divns_constant<const DIV: i64>(self) -> i64 {
+        self.to_ns() / DIV
+    }
+
+    /// Returns the number of milliseconds.
+    #[inline]
+    pub fn to_ms(self) -> i64 {
+        self.divns_constant::<NSEC_PER_MSEC>()
+    }
+
+    /// Returns the number of nanoseconds.
+    #[inline]
+    pub fn to_ns(self) -> i64 {
+        self.inner
+    }
+}
-- 
2.44.0

On 24.03.24 23:33, Boqun Feng wrote:> From: Alice Ryhl <aliceryhl@google.com>
> 
> Introduce a type representing time duration. Define our own type instead
> of using `core::time::Duration` because in kernel C code, an i64
> (ktime_t) is used for representing time durations, an i64 backed
> duration type is more efficient when interacting with time APIs in C.
> 
> Signed-off-by: Alice Ryhl <aliceryhl@google.com>
> [boqun: Rename `Ktime` to `Duration`, and make it a type of durations]
> Signed-off-by: Boqun Feng <boqun.feng@gmail.com>
> ---
>  rust/kernel/time.rs | 44 ++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 44 insertions(+)
> 
> diff --git a/rust/kernel/time.rs b/rust/kernel/time.rs
> index bbb666e64dd7..b238b3a4e899 100644
> --- a/rust/kernel/time.rs
> +++ b/rust/kernel/time.rs
> @@ -7,6 +7,9 @@
>  //!
>  //! C header: [`include/linux/jiffies.h`](srctree/include/linux/jiffies.h).
> 
> +/// The number of nanoseconds per millisecond.
> +pub const NSEC_PER_MSEC: i64 = bindings::NSEC_PER_MSEC as i64;
> +
>  /// The time unit of Linux kernel. One jiffy equals (1/HZ) second.
>  pub type Jiffies = core::ffi::c_ulong;
> 
> @@ -20,3 +23,44 @@ pub fn msecs_to_jiffies(msecs: Msecs) -> Jiffies {
>      // matter what the argument is.
>      unsafe { bindings::__msecs_to_jiffies(msecs) }
>  }
> +
> +/// A time duration.
> +///
> +/// # Examples
> +///
> +/// ```
> +/// let one_second = kernel::time::Duration::new(1000_000_000);
> +///
> +/// // 1 second is 1000 milliseconds.
> +/// assert_eq!(one_second.to_ms(), 1000);
> +/// ```
> +#[repr(transparent)]
> +#[derive(Copy, Clone, Debug)]
> +pub struct Duration {
> +    inner: i64,

Why not use the name `ns` or `nanos`?

> +}
> +
> +impl Duration {
> +    /// Creates a new duration of `ns` nanoseconds.
> +    pub const fn new(ns: i64) -> Self {
> +        Self { inner: ns }
> +    }
> +
> +    /// Divides the number of nanoseconds by a compile-time constant.
> +    #[inline]
> +    fn divns_constant<const DIV: i64>(self) -> i64 {
> +        self.to_ns() / DIV
> +    }

I am a bit confused, why is this better than writing
`self.to_ns() / DIV` at the callsite?

-- 
Cheers,
Benno

> +
> +    /// Returns the number of milliseconds.
> +    #[inline]
> +    pub fn to_ms(self) -> i64 {
> +        self.divns_constant::<NSEC_PER_MSEC>()
> +    }
> +
> +    /// Returns the number of nanoseconds.
> +    #[inline]
> +    pub fn to_ns(self) -> i64 {
> +        self.inner
> +    }
> +}
> --
> 2.44.0
>

On Tue, Mar 26, 2024 at 04:50:02PM +0000, Benno Lossin wrote:
> On 24.03.24 23:33, Boqun Feng wrote:> From: Alice Ryhl <aliceryhl@google.com>
> > 
> > Introduce a type representing time duration. Define our own type instead
> > of using `core::time::Duration` because in kernel C code, an i64
> > (ktime_t) is used for representing time durations, an i64 backed
> > duration type is more efficient when interacting with time APIs in C.
> > 
> > Signed-off-by: Alice Ryhl <aliceryhl@google.com>
> > [boqun: Rename `Ktime` to `Duration`, and make it a type of durations]
> > Signed-off-by: Boqun Feng <boqun.feng@gmail.com>
> > ---
> >  rust/kernel/time.rs | 44 ++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 44 insertions(+)
> > 
> > diff --git a/rust/kernel/time.rs b/rust/kernel/time.rs
> > index bbb666e64dd7..b238b3a4e899 100644
> > --- a/rust/kernel/time.rs
> > +++ b/rust/kernel/time.rs
> > @@ -7,6 +7,9 @@
> >  //!
> >  //! C header: [`include/linux/jiffies.h`](srctree/include/linux/jiffies.h).
> > 
> > +/// The number of nanoseconds per millisecond.
> > +pub const NSEC_PER_MSEC: i64 = bindings::NSEC_PER_MSEC as i64;
> > +
> >  /// The time unit of Linux kernel. One jiffy equals (1/HZ) second.
> >  pub type Jiffies = core::ffi::c_ulong;
> > 
> > @@ -20,3 +23,44 @@ pub fn msecs_to_jiffies(msecs: Msecs) -> Jiffies {
> >      // matter what the argument is.
> >      unsafe { bindings::__msecs_to_jiffies(msecs) }
> >  }
> > +
> > +/// A time duration.
> > +///
> > +/// # Examples
> > +///
> > +/// ```
> > +/// let one_second = kernel::time::Duration::new(1000_000_000);
> > +///
> > +/// // 1 second is 1000 milliseconds.
> > +/// assert_eq!(one_second.to_ms(), 1000);
> > +/// ```
> > +#[repr(transparent)]
> > +#[derive(Copy, Clone, Debug)]
> > +pub struct Duration {
> > +    inner: i64,
> 
> Why not use the name `ns` or `nanos`?
> 

Good point, I will rename it in next version.

> > +}
> > +
> > +impl Duration {
> > +    /// Creates a new duration of `ns` nanoseconds.
> > +    pub const fn new(ns: i64) -> Self {
> > +        Self { inner: ns }
> > +    }
> > +
> > +    /// Divides the number of nanoseconds by a compile-time constant.
> > +    #[inline]
> > +    fn divns_constant<const DIV: i64>(self) -> i64 {
> > +        self.to_ns() / DIV
> > +    }
> 
> I am a bit confused, why is this better than writing
> `self.to_ns() / DIV` at the callsite?
> 

Hmm.. you're right, there should be no difference I think. If there is
nothing I'm missing from Alice, I will drop this function in the next
version.

Regards,
Boqun

> -- 
> Cheers,
> Benno
> 
> > +
> > +    /// Returns the number of milliseconds.
> > +    #[inline]
> > +    pub fn to_ms(self) -> i64 {
> > +        self.divns_constant::<NSEC_PER_MSEC>()
> > +    }
> > +
> > +    /// Returns the number of nanoseconds.
> > +    #[inline]
> > +    pub fn to_ns(self) -> i64 {
> > +        self.inner
> > +    }
> > +}
> > --
> > 2.44.0
> >

On Tue, Mar 26, 2024 at 10:11:07AM -0700, Boqun Feng wrote:
[...]
> > > +impl Duration {
> > > +    /// Creates a new duration of `ns` nanoseconds.
> > > +    pub const fn new(ns: i64) -> Self {
> > > +        Self { inner: ns }
> > > +    }
> > > +
> > > +    /// Divides the number of nanoseconds by a compile-time constant.
> > > +    #[inline]
> > > +    fn divns_constant<const DIV: i64>(self) -> i64 {
> > > +        self.to_ns() / DIV
> > > +    }
> > 
> > I am a bit confused, why is this better than writing
> > `self.to_ns() / DIV` at the callsite?
> > 
> 
> Hmm.. you're right, there should be no difference I think. If there is
> nothing I'm missing from Alice, I will drop this function in the next
> version.
> 

On a second thought, I think this prevents accidentally divide a
non-const value, in other words, if you use this function, you're
guaranteed the divisor is a constant, and you have the compiler checking
that for you. So in that sense, I think it makes sense to remain it
here. Thoughts?

Regards,
Boqun

> Regards,
> Boqun
> 
> > -- 
> > Cheers,
> > Benno
> > 
> > > +
> > > +    /// Returns the number of milliseconds.
> > > +    #[inline]
> > > +    pub fn to_ms(self) -> i64 {
> > > +        self.divns_constant::<NSEC_PER_MSEC>()
> > > +    }
> > > +
> > > +    /// Returns the number of nanoseconds.
> > > +    #[inline]
> > > +    pub fn to_ns(self) -> i64 {
> > > +        self.inner
> > > +    }
> > > +}
> > > --
> > > 2.44.0
> > >

On 26.03.24 18:17, Boqun Feng wrote:
> On Tue, Mar 26, 2024 at 10:11:07AM -0700, Boqun Feng wrote:
> [...]
>>>> +impl Duration {
>>>> +    /// Creates a new duration of `ns` nanoseconds.
>>>> +    pub const fn new(ns: i64) -> Self {
>>>> +        Self { inner: ns }
>>>> +    }
>>>> +
>>>> +    /// Divides the number of nanoseconds by a compile-time constant.
>>>> +    #[inline]
>>>> +    fn divns_constant<const DIV: i64>(self) -> i64 {
>>>> +        self.to_ns() / DIV
>>>> +    }
>>>
>>> I am a bit confused, why is this better than writing
>>> `self.to_ns() / DIV` at the callsite?
>>>
>>
>> Hmm.. you're right, there should be no difference I think. If there is
>> nothing I'm missing from Alice, I will drop this function in the next
>> version.
>>
> 
> On a second thought, I think this prevents accidentally divide a
> non-const value, in other words, if you use this function, you're
> guaranteed the divisor is a constant, and you have the compiler checking
> that for you. So in that sense, I think it makes sense to remain it
> here. Thoughts?

I don't see the value in that. It does not prevent me from just doing
`self.to_ns() / DIV` now. I imagine that 99% of the time users will want
to get milliseconds or microseconds and we should have methods for that
(when we have users). But for the last 1% I don't think we need this
method.

-- 
Cheers,
Benno