Struct MockSleepProvider

pub struct MockSleepProvider {
    state: Arc<Mutex<SleepSchedule>>,
}

👎Deprecated since 0.29.0

A dummy SleepProvider instance for testing.

The MockSleepProvider ignores the current time, and instead keeps its own view of the current Instant and SystemTime. You can advance them in-step by calling advance(), and you can simulate jumps in the system clock by calling jump().

This is not for production use.

Deprecated

This mock time facility has some limitations, notably lack of support for tasks, and a confusing API for controlling the mock time.

New test cases should probably use MockRuntime which incorporates MockSimpletimeProvider.

Comparison of MockSleepProvider with SimpleMockTimeProvider:

• SimpleMockTimeProvider does not support, or expect the use of, block_advance et al. Instead, the advancement of simulated time is typically done automatically in cooperation with the executor, using MockRuntime’s advance_* methods.

• Consequently, SimpleMockTimeProvider can be used in test cases that spawn tasks and perform sleeps in them.

• And, consequently, SimpleMockTimeProvider does not need non-test code to contain calls which are solely related to getting the time mocking to work right.

• SimpleMockTimeProvider gives correct sleeping locations with MockExecutor‘s dump of sleeping tasks’ stack traces.

• Conversely, to use SimpleMockTimeProvider in all but the most simple test cases, coordination with the executor is required. This coordination is provided by the integrated MockRuntime; SimpleMockTimeProvider is of limited usefulness by itself.

Examples

Suppose you’ve written a function that relies on making a connection to the network and possibly timing out:

use tor_rtcompat::{Runtime,SleepProviderExt};
use std::{net::SocketAddr, io::Result, time::Duration, io::Error};
use futures::io::AsyncWriteExt;

async fn say_hi(runtime: impl Runtime, addr: &SocketAddr) -> Result<()> {
   let delay = Duration::new(5,0);
   runtime.timeout(delay, async {
      let mut conn = runtime.connect(addr).await?;
      conn.write_all(b"Hello world!\r\n").await?;
      conn.close().await?;
      Ok::<_,Error>(())
   }).await??;
   Ok(())
}

But how should you test this function?

You might try connecting to a well-known website to test the connection case, and to a well-known black hole to test the timeout case… but that’s a bit undesirable. Your tests might be running in a container with no internet access; and even if they aren’t, it isn’t so great for your tests to rely on the actual state of the internet. Similarly, if you make your timeout too long, your tests might block for a long time; but if your timeout is too short, the tests might fail on a slow machine or on a slow network.

Or, you could solve both of these problems by using tor-rtmock to replace the internet and the passage of time. (Here we’re only replacing the internet.)

use tor_rtmock::{MockSleepRuntime,MockNetRuntime,net::MockNetwork};
use tor_rtcompat::{NetStreamProvider,NetStreamListener};
use futures::io::AsyncReadExt;
use std::net::SocketAddr;
use futures::StreamExt as _;

tor_rtcompat::test_with_all_runtimes!(|rt| async move {

   let addr1 = "198.51.100.7".parse().unwrap();
   let addr2 = "198.51.100.99".parse().unwrap();
   let sockaddr: SocketAddr = "198.51.100.99:101".parse().unwrap();

   // Make a runtime that pretends that we are at the first address...
   let fake_internet = MockNetwork::new();
   let rt1 = fake_internet.builder().add_address(addr1).runtime(rt.clone());
   // ...and one that pretends we're listening at the second address.
   let rt2 = fake_internet.builder().add_address(addr2).runtime(rt);
   let listener = rt2.listen(&sockaddr).await.unwrap();
   let mut incoming_stream = listener.incoming();

   // Now we can test our function!
   let (result1,output) = futures::join!(
          say_hi(rt1, &sockaddr),
          async {
              let (mut conn,addr) = incoming_stream.next().await.unwrap().unwrap();
              assert_eq!(addr.ip(), addr1);
              let mut output = Vec::new();
              conn.read_to_end(&mut output).await.unwrap();
              output
          });

   assert!(result1.is_ok());
   assert_eq!(&output[..], b"Hello world!\r\n");
});

Fields

state: Arc<Mutex<SleepSchedule>>

👎Deprecated since 0.29.0

The shared backend for this MockSleepProvider and its futures.

Implementations

impl MockSleepProvider

pub fn new(wallclock: SystemTime) -> Self

Create a new MockSleepProvider, starting at a given wall-clock time.

pub async fn advance(&self, dur: Duration)

Advance the simulated timeline forward by dur.

Calling this function will wake any pending futures as appropriate, and yield to the scheduler so they get a chance to run.

Limitations

This function advances time in one big step. We might instead want to advance in small steps and make sure that each step’s futures can get run before the ones scheduled to run after it.

pub(crate) fn advance_noyield(&self, dur: Duration)

Advance the simulated timeline forward by dur.

Calling this function will wake any pending futures as appropriate, but not yield to the scheduler. Mostly you should call advance instead.

pub fn jump_to(&self, new_wallclock: SystemTime)

Simulate a discontinuity in the system clock, by jumping to new_wallclock.

Panics

Panics if we have already panicked while holding the lock on the internal timer state, and the lock is poisoned.

pub(crate) fn time_until_next_timeout(&self) -> Option<Duration>

Return the amount of virtual time until the next timeout should elapse.

If there are no more timeouts, return None. If the next timeout should elapse right now, return Some(0).

pub(crate) fn should_advance(&mut self) -> bool

Return true if a WaitFor driving this sleep provider should advance time in order for futures blocked on sleeping to make progress.

NOTE: This function has side-effects; if it returns true, the caller is expected to do an advance before calling it again.

pub(crate) fn register_waitfor_waker(&mut self, waker: Waker)

Register a Waker to be woken up when an advance in time is required to make progress.

This is used by WaitFor.

pub(crate) fn clear_waitfor_waker(&mut self)

Remove a previously registered Waker registered with register_waitfor_waker().

pub(crate) fn has_waitfor_waker(&self) -> bool

Returns true if a Waker has been registered with register_waitfor_waker().

This is used to ensure that you don’t have two concurrent WaitFors running.

Trait Implementations

impl Clone for MockSleepProvider

fn clone(&self) -> MockSleepProvider

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl CoarseTimeProvider for MockSleepProvider

fn now_coarse(&self) -> CoarseInstant

Return the CoarseTimeProvider’s view of the current instant.

impl Debug for MockSleepProvider

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for MockSleepProvider

fn default() -> Self

Returns the “default value” for a type.

impl SleepProvider for MockSleepProvider

type SleepFuture = Sleeping

A future returned by SleepProvider::sleep()

fn sleep(&self, duration: Duration) -> Self::SleepFuture

Return a future that will be ready after duration has elapsed.

fn block_advance<T: Into<String>>(&self, reason: T)

Signify that a test running under mock time shouldn’t advance time yet, with a given unique reason string. This is useful for making sure (mock) time doesn’t advance while things that might require some (real-world) time to complete do so, such as spawning a task on another thread.

fn release_advance<T: Into<String>>(&self, reason: T)

Signify that the reason to withhold time advancing provided in a call to block_advance no longer exists, and it’s fine to move time forward if nothing else is blocking advances.

fn allow_one_advance(&self, dur: Duration)

Allow a test running under mock time to advance time by the provided duration, even if the above block_advance API has been used.

fn now(&self) -> Instant

Return the SleepProvider’s view of the current instant.

fn wallclock(&self) -> SystemTime

Return the SleepProvider’s view of the current wall-clock time.