Module: Cybertrain::Clock
- Defined in:
- cybertrain/clock.rb
Overview
The one clock of the framework (spec section 2.2): real time, or the
instant a test travelled to. The test helpers travel_to,
travel, freeze_time and travel_back move it;
an application never needs to. Time.current answers Clock.now.
The clock also holds the zone whose calendar the methods of
cybertrain/time_ext.rb and Date.current use (Clock.zone, Time.zone):
UTC until something sets it.
The state is module-level ivars (rules 18 and 64): a flag and the
instant as Integer microseconds since the epoch (an ivar holding a
nullable Time miscompiles, rule 7), and the zone (never nil). Real
time is read with Process.clock_gettime(Process::CLOCK_REALTIME,
:microsecond), never through Time.now, so that a test program’s
override of Time.now (cybertrain/test/time_now.rb) cannot recurse.
Threads: the state is process-wide, so a job or server thread sees a
test’s travel. Two ivars cannot change at once, and nothing locks them.
The order of the writes is a best-effort guard, with no barrier: within
one thread @micros is only ever written with a travelled instant and
before @travelling becomes true, going back to real time clears
@travelling alone and leaves @micros as it was, and Clock.now reads the
flag before the instant; but neither CRuby’s nor Spinel’s compiled code
promises that another thread observes the two writes in that order (a
plain ivar load is not a publication barrier on Spinel; compare the
Mutex of TimeZone’s cache). So a thread that reads the clock while a
test travels may, rarely, see the old instant beside the new flag
(1970 before the first travel). Travel is a test-only operation, made
from the test’s own thread; threads still running beside it (a server,
a worker) see each travel eventually, not at a defined point. Reads are
not locked because Clock.now is on every request’s path and a test needs
no more than this.
Each write of the state is followed by Logger.follow_clock (docs/design.md D86): the log line’s time follows a travel, while cybertrain/logger.rb, in the HTTP layer, never names the Clock.
Class Method Summary collapse
-
.monotonic ⇒ Float
Seconds on the monotonic clock (
CLOCK_MONOTONIC): for waiting and measuring, which a travel never touches. -
.now ⇒ Time
The current time as a UTC Time: real time, or the travelled instant.
-
.real_now ⇒ Time
The real time as a UTC Time, whatever a test travelled to (file ages and other readings of the outside world).
-
.travel_back ⇒ nil
Back to real time.
-
.travel_to(time) ⇒ nil
Sets the clock to
timewithout its sub-second part (Rails’with_usec: false) and holds it there until Clock.travel_back or another travel. -
.travelled_micros ⇒ Integer
The travelled instant in microseconds since the epoch (a multiple of 1_000_000); 0 when not travelling.
-
.travelling? ⇒ Boolean
Whether a travel holds the clock.
-
.zone ⇒ TimeZone
The zone whose calendar
beginning_of_day,advanceand the other calendar methods on Time, andDate.current, follow. -
.zone=(zone) ⇒ TimeZone
Sets Clock.zone.
Class Method Details
.monotonic ⇒ Float
Seconds on the monotonic clock (CLOCK_MONOTONIC): for waiting and
measuring, which a travel never touches.
70 71 72 |
# File 'cybertrain/clock.rb', line 70 def self.monotonic Process.clock_gettime(Process::CLOCK_MONOTONIC) end |
.now ⇒ Time
The current time as a UTC Time: real time, or the travelled instant.
51 52 53 54 55 |
# File 'cybertrain/clock.rb', line 51 def self.now # The flag first, then the instant (best effort: the module's comment). us = @travelling ? @micros : Process.clock_gettime(Process::CLOCK_REALTIME, :microsecond) Time.at(us / 1_000_000, us % 1_000_000).utc end |
.real_now ⇒ Time
The real time as a UTC Time, whatever a test travelled to (file ages and other readings of the outside world).
61 62 63 64 |
# File 'cybertrain/clock.rb', line 61 def self.real_now us = Process.clock_gettime(Process::CLOCK_REALTIME, :microsecond) Time.at(us / 1_000_000, us % 1_000_000).utc end |
.travel_back ⇒ nil
Back to real time. Clears the flag only: @micros keeps the last
travelled instant, so a thread reading the clock meanwhile never sees
the flag set beside a cleared instant (see the module’s comment).
119 120 121 122 123 |
# File 'cybertrain/clock.rb', line 119 def self.travel_back @travelling = false Logger.follow_clock(-1) nil end |
.travel_to(time) ⇒ nil
Sets the clock to time without its sub-second part (Rails’
with_usec: false) and holds it there until travel_back or another
travel.
80 81 82 83 84 85 86 |
# File 'cybertrain/clock.rb', line 80 def self.travel_to(time) # The instant first, then the flag (the module's comment). @micros = time.to_i * 1_000_000 @travelling = true Logger.follow_clock(@micros) nil end |
.travelled_micros ⇒ Integer
The travelled instant in microseconds since the epoch (a multiple of 1_000_000); 0 when not travelling.
154 155 156 |
# File 'cybertrain/clock.rb', line 154 def self.travelled_micros @travelling ? @micros : 0 end |
.travelling? ⇒ Boolean
Whether a travel holds the clock.
128 129 130 |
# File 'cybertrain/clock.rb', line 128 def self.travelling? @travelling end |
.zone ⇒ TimeZone
The zone whose calendar beginning_of_day, advance and the other
calendar methods on Time, and Date.current, follow. UTC by default.
Values stay UTC instants whatever the zone (spec section 4).
137 138 139 |
# File 'cybertrain/clock.rb', line 137 def self.zone @zone end |