| // Copyright 2019 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| library fuchsia.testing; |
| using zx; |
| |
| /// Allows access to fake clocks managed by `FakeClockControl`. |
| [Discoverable] |
| protocol FakeClock { |
| /// Gets the current time. |
| Get() -> (zx.time time); |
| /// Registers the event handle `event` to be signaled with `ZX_EVENTPAIR_SIGNALED` when the |
| /// provided `time` is reached by the fake clock. |
| /// The `FakeClock` instance will retain this event (even after it's fired) for as long as the |
| /// client-side of the provided event pair `event` is open. |
| RegisterEvent(zx.handle:EVENTPAIR event, zx.time time); |
| /// Reschedules an event to be signalled with `ZX_EVENTPAIR_SIGNALED` at the new deadline in |
| /// `time`. |
| /// `event` is a duplicate of the client-side of the event pair, and it's used to retrieve the |
| /// originally registered event through its kernel object identifier. |
| RescheduleEvent(zx.handle:EVENTPAIR event, zx.time time) -> (); |
| /// Cancels a previously registered event. |
| /// `event` is a duplicate of the client-side of the event pair, and it's used to retrieve the |
| /// originally registered event through its kernel object identifier. |
| CancelEvent(zx.handle:EVENTPAIR event) -> (); |
| }; |
| |
| /// A fake clock increment in a uniform random range. |
| struct RandomRange { |
| /// The lower bound (inclusive) for the random duration. |
| zx.duration min_rand; |
| /// The upper bound (exclusive) for the random duration. |
| zx.duration max_rand; |
| }; |
| |
| /// A fake clock increment step. |
| union Increment { |
| /// Increments the fake clock by the `determined` duration. |
| 1: zx.duration determined; |
| /// Increments the fake clock by a random duration chosen uniformly from the range in `random`. |
| 2: RandomRange random; |
| }; |
| |
| /// Provides control over fake clocks. |
| /// |
| /// `FakeClockControl` provides complete control of the fake clocks that it provides, and serves |
| /// over `FakeClock`. |
| /// |
| /// Upon start up, all the clocks are set to free-running with increments set to 1ms:1ms (same as |
| /// calling `SetIncrements` with a `real` duration of 1ms and a `determined` `increment` of 1ms as |
| /// well). |
| /// |
| /// The initial time value for every fake clock is read from the corresponding real clock at start |
| /// up. |
| [Discoverable] |
| protocol FakeClockControl { |
| /// Advances the fake clock `increment` once. |
| /// Returns `ZX_ERR_INVALID_ARGS` if the provided `increment` is invalid (such as a badly formed |
| /// RandomRange). Returns `ZX_ERR_ACCESS_DENIED` if called while the FakeClock is free-running. |
| Advance(Increment increment) -> () error zx.status; |
| /// Resumes free-running increments on the fake clock. |
| /// `real` is the period based on the real monotonic clock over which `increment` is going to be |
| /// applied. Returns `ZX_ERR_INVALID_ARGS` if the provided `increment` is invalid (such as a |
| /// badly formed RandomRange). |
| ResumeWithIncrements(zx.duration real, Increment increment) -> () error zx.status; |
| /// Pauses free-running increments on the fake clock. |
| Pause() -> (); |
| }; |