diff options
Diffstat (limited to 'crates/tor-rtmock')
| -rw-r--r-- | crates/tor-rtmock/src/runtime.rs | 23 |
1 files changed, 20 insertions, 3 deletions
diff --git a/crates/tor-rtmock/src/runtime.rs b/crates/tor-rtmock/src/runtime.rs index 16914110c..d7a3e485a 100644 --- a/crates/tor-rtmock/src/runtime.rs +++ b/crates/tor-rtmock/src/runtime.rs @@ -15,11 +15,23 @@ use crate::net::MockNetProvider; use crate::simple_time::SimpleMockTimeProvider; use crate::task::{MockExecutor, SchedulingPolicy}; -/// Completely mock runtime +/// Completely mock runtime, with simulated time /// /// Suitable for test cases that wish to completely control /// the environment experienced by the code under test. /// +/// ### Useful properties +/// +/// The execution order is deterministic. +/// Time will advance only in a controlled fashion. +/// Typically, the main task in a test will call +/// [`advance_until_stalled`](MockRuntime::advance_until_stalled). +/// +/// Reliable sequencing techniques which can be used in tests include: +/// sleeping for carefully chosen durations; +/// interlocking via intertask channels; or, +/// sequenced control of requests to the code under test. +/// /// ### Restrictions /// /// The test case must advance the mock time explicitly as desired, @@ -28,6 +40,10 @@ use crate::task::{MockExecutor, SchedulingPolicy}; /// Tests that use this runtime *must not* interact with the outside world; /// everything must go through this runtime (and its pieces). /// +/// There is no mocking of filesystem access; +/// the `MockRuntime`'s time will disagree with `SystemTime`'s +/// obtained from (for example) `std::fs::Metadata`. +/// /// #### Allowed /// /// * Inter-future communication facilities from `futures` @@ -49,8 +65,9 @@ use crate::task::{MockExecutor, SchedulingPolicy}; /// /// #### Not allowed /// -/// * Direct access to the real-world clock (`SystemTime::now`, `Instant::now`). -/// Including `coarsetime`, which is not mocked. +/// * Direct access to the real-world clock (`SystemTime::now`, `Instant::now`), +/// including direct use of `coarsetime`. +/// Instead, use [`SleepProvider`] and [`CoarseTimeProvider`] methods on the runtime. /// Exception: CPU use measurements. /// /// * Anything that spawns threads and then communicates with those threads |