tarantool/
clock.rs

1//! The `clock` module returns time values derived from the Posix / C
2//! [CLOCK_GETTIME](http://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_getres.html)
3//! function or equivalent.
4//!
5//! Most functions in the module return a number of seconds; functions with names followed by “64”
6//! return a 64-bit number of nanoseconds.
7//!
8//! - [time()](fn.time.html) - Get the wall clock time in seconds
9//! - [time64()](fn.time64.html) - Get the wall clock time in nanoseconds
10//! - [monotonic()](fn.monotonic.html) - Get the monotonic time in seconds
11//! - [monotonic64()](fn.monotonic64.html) - Get the monotonic time in nanoseconds
12//! - [proc()](fn.proc.html) - Get the processor time in seconds
13//! - [proc64()](fn.proc64.html) - Get the processor time in nanoseconds
14//! - [thread()](fn.thread.html) - Get the thread time in seconds
15//! - [thread64()](fn.thread64.html) - Get the thread time in nanoseconds
16//!
17//! See also:
18//! - [Lua reference: Module clock](https://www.tarantool.io/en/doc/latest/reference/reference_lua/clock/)
19//! - [C API reference: Module clock](https://www.tarantool.io/en/doc/latest/dev_guide/reference_capi/clock/)
20
21use std::time::Duration;
22
23/// A large duration, effectively infinite for all practical purposes.
24///
25/// This value can be used as a default timeout value whenever there's no
26/// obvious limit but the API requires an explicit value.
27///
28/// Is equivalent to 100 years.
29pub const INFINITY: Duration = Duration::from_secs(100 * 365 * 24 * 60 * 60);
30
31use crate::ffi::tarantool as ffi;
32
33/// The wall clock time in seconds.
34///
35/// Derived from C function `clock_gettime(CLOCK_REALTIME)`.
36/// This is the best function for knowing what the official time is, as determined by the system administrator.
37///
38/// Return: seconds since epoch (1970-01-01 00:00:00), adjusted.
39///
40/// Example:
41/// ```no_run
42/// // This will print an approximate number of years since 1970.
43/// use tarantool::clock::time;
44/// println!("{}", time() / (365. * 24. * 60. * 60.));
45/// ```
46///
47/// See also: [fiber::time()](../fiber/fn.time.html), [fiber::time64()](../fiber/fn.time64.html)
48#[inline(always)]
49pub fn time() -> f64 {
50    unsafe { ffi::clock_realtime() }
51}
52
53/// The wall clock time in nanoseconds since epoch.
54///
55/// Example:
56/// ```no_run
57/// // This will print an approximate number of years since 1970.
58/// use tarantool::clock::time64;
59/// println!("{}", time64() / (365 * 24 * 60 * 60));
60/// ```
61/// See: [time()](fn.time.html)
62#[inline(always)]
63pub fn time64() -> u64 {
64    unsafe { ffi::clock_realtime64() }
65}
66
67/// The monotonic time.
68///
69/// Derived from C function `clock_gettime(CLOCK_MONOTONIC)`.
70/// Monotonic time is similar to wall clock time but is not affected by changes to or from daylight saving time, or by
71/// changes done by a user. This is the best function to use with benchmarks that need to calculate elapsed time.
72///
73/// Return: seconds or nanoseconds since the last time that the computer was booted.
74/// Return type: `u64` or `f64`
75///
76/// Example:
77/// ```no_run
78/// // This will print nanoseconds since the start.
79/// use tarantool::clock::monotonic64;
80/// println!("{}", monotonic64());
81/// ```
82#[inline(always)]
83pub fn monotonic() -> f64 {
84    unsafe { ffi::clock_monotonic() }
85}
86
87/// See: [monotonic()](fn.monotonic.html)
88#[inline(always)]
89pub fn monotonic64() -> u64 {
90    unsafe { ffi::clock_monotonic64() }
91}
92
93/// The processor time.
94///
95/// Derived from C function `clock_gettime(CLOCK_PROCESS_CPUTIME_ID)`.
96/// This is the best function to use with benchmarks that need to calculate the amount of time for which CPU was used.
97///
98/// Return: seconds or nanoseconds since processor start.
99/// Return type: `u64` or `f64`
100///
101/// Example:
102/// ```no_run
103/// // This will print nanoseconds in the CPU since the start.
104/// use tarantool::clock::process64;
105/// println!("{}", process64());
106/// ```
107#[inline(always)]
108pub fn process() -> f64 {
109    unsafe { ffi::clock_process() }
110}
111
112/// See: [process()](fn.process.html)
113#[inline(always)]
114pub fn process64() -> u64 {
115    unsafe { ffi::clock_process64() }
116}
117
118/// The thread time.
119///
120/// Derived from C function `clock_gettime(CLOCK_THREAD_CPUTIME_ID)`.
121/// This is the best function to use with benchmarks that need to calculate hthe amount of time for which a CPU thread was used.
122///
123/// Return: seconds or nanoseconds since the transaction processor thread started.
124/// Return type: `u64` or `f64`
125///
126/// Example:
127/// ```no_run
128/// // This will print seconds in the thread since the start.
129/// use tarantool::clock::thread64;
130/// println!("{}", thread64());
131/// ```
132#[inline(always)]
133pub fn thread() -> f64 {
134    unsafe { ffi::clock_thread() }
135}
136
137/// See: [thread()](fn.thread.html)
138#[inline(always)]
139pub fn thread64() -> u64 {
140    unsafe { ffi::clock_thread64() }
141}
tarantool/clock.rs

tarantool/
clock.rs
