Struct Clock

Source

#[non_exhaustive]
pub struct Clock { /* private fields */ }

Expand description

A clock that reads real time, or a test’s time that moves only on command.

Clones share one clock. Equality compares identity, so all real clocks are equal and a test clock equals only the handles of its own TestClock.

It cannot be built from a struct literal and it has a destructor in every build, so code that compiles without test-clock compiles with it too.

Implementations§

Source §

impl Clock

Source

pub fn after(&self, duration: Duration) -> Receiver<Instant>

Available on crate feature crossbeam only.

Returns a receiver that gets the instant duration from now once this clock reaches it.

It mirrors crossbeam_channel::after, which it is on the real clock. On a test clock, it is Self::at for the instant duration from now. A duration past the end of Instant’s range returns a receiver that never fires.

Wait for a job or a timeout, driven from a test through wait_timers, since wait_blocked cannot see a thread blocked in select!:

use darkbio_clock::TestClock;
use darkbio_clock::crossbeam_channel::{select, unbounded};
use std::thread;
use std::time::Duration;

let mut tester = TestClock::new();
let clock = tester.clock();
let (_jobs, queue) = unbounded::<u32>();

let worker = thread::spawn(move || {
    select! {
        recv(queue) -> job => job.ok(),
        recv(clock.after(Duration::from_secs(5))) -> _ => None,
    }
});
tester.wait_timers(1);
tester.advance(Duration::from_secs(5));
assert_eq!(worker.join().unwrap(), None);

Source

pub fn at(&self, deadline: Instant) -> Receiver<Instant>

Available on crate feature crossbeam only.

Returns a receiver that gets deadline once this clock reaches it, at once if it already has.

It mirrors crossbeam_channel::at, which it is on the real clock. On a test clock, an advance that reaches the deadline delivers it, even one that overshoots, before any thread can read the new time. The channel stays connected until the TestClock and every Clock handle are gone.

An advance sends its due timers one at a time, in deadline order and then in the order they were armed, and a select! already waiting takes the first one sent. So a waiting select_biased! over timers due at the same instant takes the one armed first, where the real clock’s takes the first of their arms.

Source

pub fn recv_timeout<T>( &self, receiver: &Receiver<T>, timeout: Duration, ) -> Result<T, RecvTimeoutError>

Available on crate feature crossbeam only.

Receives a message, waiting up to timeout on this clock.

It mirrors crossbeam’s Receiver::recv_timeout, which it is on the real clock. A buffered message or a disconnection wins over the timeout. On a test clock, it is Self::recv_deadline for the instant timeout from now. A timeout past the end of Instant’s range waits like Receiver::recv.

Source

pub fn recv_deadline<T>( &self, receiver: &Receiver<T>, deadline: Instant, ) -> Result<T, RecvTimeoutError>

Available on crate feature crossbeam only.

Receives a message, waiting until this clock reaches deadline.

It mirrors crossbeam’s Receiver::recv_deadline, which it is on the real clock. A buffered message or a disconnection wins over the deadline. On a test clock, a clock timer due by the deadline holds its message before the receive can time out, so it wins too. A waiting receive arms a timer, which wait_timers counts until it fires or the receive returns.

Source §