Class: Phronomy::Runtime::SchedulerTimerAdapter Private

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

Overview

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

A drop-in replacement for TimerQueue that delegates timer scheduling to a DeterministicScheduler instead of spawning a dedicated background OS thread.

When a Phronomy::Runtime is backed by DeterministicScheduler (e.g. the +:fiber+ runtime backend), #timer_queue returns an instance of this adapter rather than a TimerQueue. This eliminates the +phronomy-timer-queue+ background thread for Fiber-based runtimes.

Timer callbacks are fired during DeterministicScheduler#run_until_idle when DeterministicScheduler#autorun? is +true+ (i.e. the +:fiber+ backend). They can also be fired explicitly by calling DeterministicScheduler#fire_real_timers.

== Known Limitation (Issue #331)

Timers that require an actual wall-clock sleep (e.g. a deadline of 10 s from now that will not be reached until real time elapses) will not fire automatically: +run_until_idle+ does not block waiting for future deadlines. This is an accepted limitation of the current stepping-stone implementation. Full resolution requires integrating the cooperative scheduler with the EventLoop tick cycle so that a single event-loop iteration checks both ready Fibers and expired wall-clock timers.

Use the +:thread+ runtime backend (default) for production workloads that depend on real-time deadline enforcement.

Bridges wall-clock timers to the cooperative DeterministicScheduler.

Registers a recurring timer callback with the scheduler's TimerQueue so that Fiber-based tasks can await real time without blocking OS threads.

See Also:

Instance Method Summary collapse

Constructor Details

#initialize(scheduler) ⇒ SchedulerTimerAdapter

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

Parameters:



41
42
43
 
# File 'lib/phronomy/runtime/scheduler_timer_adapter.rb', line 41

def initialize(scheduler)
  @scheduler = scheduler
end

Instance Method Details

#pending_count ⇒ Integer

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 the number of pending (not yet fired) callbacks.

Returns:

  • (Integer) 


74
75
76
 
# File 'lib/phronomy/runtime/scheduler_timer_adapter.rb', line 74

def pending_count
  @scheduler.pending_real_timer_count
end

#schedule(seconds:) { ... } ⇒ 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.

Schedules a one-shot callback to fire after +seconds+ from now. Delegates to DeterministicScheduler#schedule_real_after.

Raises PoolShutdownError after #shutdown has been called, matching the behaviour of TimerQueue#schedule.

Parameters:

  • seconds (Numeric) —

    delay before the callback fires

Yields:

  • called when the deadline is reached

Returns:

  • (self)

Raises:



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

def schedule(seconds:, &callback)
  raise Phronomy::PoolShutdownError, "SchedulerTimerAdapter has been shut down" if @stopped

  @scheduler.schedule_real_after(seconds, &callback)
  self
end

#shutdown ⇒ 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.

No-op: there is no background thread to stop. Present for API compatibility with TimerQueue.

Returns:

  • (self) 


66
67
68
69
 
# File 'lib/phronomy/runtime/scheduler_timer_adapter.rb', line 66

def shutdown
  @stopped = true
  self
end