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

Class Method Details

.monotonic ⇒ Float

Seconds on the monotonic clock (CLOCK_MONOTONIC): for waiting and measuring, which a travel never touches.

Returns:

  • (Float)


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.

Returns:



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).

Returns:



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).

Returns:

  • (nil)


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.

Parameters:

Returns:

  • (nil)


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.

Returns:



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.

Returns:

  • (Boolean)


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).

Returns:



137
138
139
# File 'cybertrain/clock.rb', line 137

def self.zone
  @zone
end

.zone=(zone) ⇒ TimeZone

Sets zone. Takes a TimeZone (TimeZone.find("Asia/Tokyo")); a test that sets it puts the one it found back when it ends.

Parameters:

Returns:



146
147
148
# File 'cybertrain/clock.rb', line 146

def self.zone=(zone)
  @zone = zone
end