seq_runtime/
time_ops.rs

1//! Time operations for Seq
2//!
3//! Provides timing primitives for performance measurement and delays.
4//!
5//! # Usage from Seq
6//!
7//! ```seq
8//! time.now      # ( -- Int ) microseconds since epoch
9//! time.nanos    # ( -- Int ) nanoseconds (monotonic, for timing)
10//! 100 time.sleep-ms  # ( Int -- ) sleep for N milliseconds
11//! ```
12//!
13//! # Example: Measuring execution time
14//!
15//! ```seq
16//! : benchmark ( -- )
17//!   time.nanos    # start time
18//!   do-work
19//!   time.nanos    # end time
20//!   swap -        # elapsed nanos
21//!   1000000 /     # convert to ms
22//!   "Elapsed: " write
23//!   int->string write
24//!   "ms" write-line
25//! ;
26//! ```
27
28use crate::stack::{Stack, pop, push};
29use crate::value::Value;
30use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
31
32// Thread-local monotonic clock base for consistent nanosecond timing
33thread_local! {
34    static CLOCK_BASE: Instant = Instant::now();
35}
36
37/// Get current time in microseconds since Unix epoch
38///
39/// Stack effect: ( -- Int )
40///
41/// Returns wall-clock time. Good for timestamps.
42/// For measuring durations, prefer `time.nanos` which uses a monotonic clock.
43///
44/// # Safety
45/// - `stack` must be a valid stack pointer (may be null for empty stack)
46#[unsafe(no_mangle)]
47pub unsafe extern "C" fn patch_seq_time_now(stack: Stack) -> Stack {
48    let micros = SystemTime::now()
49        .duration_since(UNIX_EPOCH)
50        .map(|d| d.as_micros() as i64)
51        .unwrap_or(0);
52
53    unsafe { push(stack, Value::Int(micros)) }
54}
55
56/// Get monotonic nanoseconds for precise timing
57///
58/// Stack effect: ( -- Int )
59///
60/// Returns nanoseconds from an arbitrary starting point (process start).
61/// Uses a monotonic clock - values always increase, unaffected by system
62/// clock changes. Perfect for measuring elapsed time.
63///
64/// Note: Saturates at i64::MAX (~292 years of uptime) to prevent overflow.
65///
66/// # Safety
67/// - `stack` must be a valid stack pointer (may be null for empty stack)
68#[unsafe(no_mangle)]
69pub unsafe extern "C" fn patch_seq_time_nanos(stack: Stack) -> Stack {
70    let nanos = CLOCK_BASE.with(|base| base.elapsed().as_nanos().try_into().unwrap_or(i64::MAX));
71    unsafe { push(stack, Value::Int(nanos)) }
72}
73
74/// Sleep for a specified number of milliseconds
75///
76/// Stack effect: ( Int -- )
77///
78/// Yields the current strand to the scheduler while sleeping.
79/// Uses `may::coroutine::sleep` for cooperative scheduling.
80///
81/// # Safety
82/// - `stack` must be a valid, non-null stack pointer with an Int on top
83#[unsafe(no_mangle)]
84pub unsafe extern "C" fn patch_seq_time_sleep_ms(stack: Stack) -> Stack {
85    assert!(!stack.is_null(), "time.sleep-ms: stack is empty");
86
87    let (rest, value) = unsafe { pop(stack) };
88
89    match value {
90        Value::Int(ms) => {
91            if ms < 0 {
92                panic!("time.sleep-ms: duration must be non-negative, got {}", ms);
93            }
94
95            // Use may's coroutine-aware sleep for cooperative scheduling
96            may::coroutine::sleep(Duration::from_millis(ms as u64));
97
98            rest
99        }
100        _ => panic!(
101            "time.sleep-ms: expected Int duration on stack, got {:?}",
102            value
103        ),
104    }
105}
106
107// Public re-exports
108pub use patch_seq_time_nanos as time_nanos;
109pub use patch_seq_time_now as time_now;
110pub use patch_seq_time_sleep_ms as time_sleep_ms;
111
112#[cfg(test)]
113mod tests {
114    use super::*;
115    use crate::stack::pop;
116
117    #[test]
118    fn test_time_now_returns_positive() {
119        unsafe {
120            let stack = crate::stack::alloc_test_stack();
121            let stack = patch_seq_time_now(stack);
122            let (_, value) = pop(stack);
123
124            match value {
125                Value::Int(micros) => {
126                    // Should be a reasonable timestamp (after year 2020)
127                    assert!(micros > 1_577_836_800_000_000); // 2020-01-01
128                }
129                _ => panic!("Expected Int"),
130            }
131        }
132    }
133
134    #[test]
135    fn test_time_nanos_monotonic() {
136        unsafe {
137            let stack = crate::stack::alloc_test_stack();
138            let stack = patch_seq_time_nanos(stack);
139            let (_, value1) = pop(stack);
140
141            // Small delay
142            std::thread::sleep(Duration::from_micros(100));
143
144            let stack = crate::stack::alloc_test_stack();
145            let stack = patch_seq_time_nanos(stack);
146            let (_, value2) = pop(stack);
147
148            match (value1, value2) {
149                (Value::Int(t1), Value::Int(t2)) => {
150                    assert!(t2 > t1, "time.nanos should be monotonically increasing");
151                }
152                _ => panic!("Expected Int values"),
153            }
154        }
155    }
156
157    #[test]
158    fn test_time_sleep_ms() {
159        unsafe {
160            // Push 1ms sleep duration
161            let stack = crate::stack::alloc_test_stack();
162            let stack = push(stack, Value::Int(1));
163
164            let start = Instant::now();
165            let _stack = patch_seq_time_sleep_ms(stack);
166            let elapsed = start.elapsed();
167
168            // Should sleep at least 1ms
169            assert!(elapsed >= Duration::from_millis(1));
170            // Stack should be empty after popping the duration
171        }
172    }
173}
seq_runtime/time_ops.rs

seq_runtime/
time_ops.rs
