Class: Phronomy::Deadline

Inherits:
Object
  • Object
show all
Defined in:
lib/phronomy/deadline.rb

Overview

A point in time used as an upper bound for an operation.

Uses the monotonic clock (+Process::CLOCK_MONOTONIC+) internally to avoid skew from NTP adjustments or DST transitions.

Examples:

Create a 30-second deadline and check remaining time

deadline = Phronomy::Deadline.in(30)
sleep 1
deadline.remaining_seconds   # => ~29.0
deadline.expired?            # => false

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(monotonic_at) ⇒ Deadline

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Deadline.

Parameters:

  • monotonic_at (Float) —

    absolute monotonic timestamp of expiry



26
27
28
 
# File 'lib/phronomy/deadline.rb', line 26

def initialize(monotonic_at)
  @monotonic_at = monotonic_at
end

Class Method Details

.in(seconds) ⇒ Deadline

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Creates a deadline that expires +seconds+ from now.

Parameters:

  • seconds (Numeric) —

    seconds from now until expiry

Returns:



20
21
22
 
# File 'lib/phronomy/deadline.rb', line 20

def self.in(seconds)
  new(Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds)
end

Instance Method Details

#attach_to(token, timer_queue: Phronomy::Runtime.instance.timer_queue) ⇒ self

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Attaches this deadline to a CancellationToken by cancelling the token when the deadline expires. Uses the Runtime timer queue (a single background thread shared by all deadlines) instead of spawning one thread per deadline.

Parameters:

  • token (CancellationToken)
  • timer_queue (Runtime::TimerQueue, nil) (defaults to: Phronomy::Runtime.instance.timer_queue) —

    queue to register with; defaults to +Phronomy::Runtime.instance.timer_queue+

Returns:

  • (self) 


55
56
57
58
59
60
61
 
# File 'lib/phronomy/deadline.rb', line 55

def attach_to(token, timer_queue: Phronomy::Runtime.instance.timer_queue)
  seconds = remaining_seconds
  return self if seconds <= 0

  timer_queue.schedule(seconds: seconds) { token.cancel! }
  self
end

#expired? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns +true+ when the deadline has passed.

Returns:

  • (Boolean) 


33
34
35
 
# File 'lib/phronomy/deadline.rb', line 33

def expired?
  Process.clock_gettime(Process::CLOCK_MONOTONIC) >= @monotonic_at
end

#remaining_seconds ⇒ Float

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Seconds remaining until expiry. Returns 0 when already expired.

Returns:

  • (Float) 


40
41
42
43
 
# File 'lib/phronomy/deadline.rb', line 40

def remaining_seconds
  remaining = @monotonic_at - Process.clock_gettime(Process::CLOCK_MONOTONIC)
  [remaining, 0.0].max
end