Class: Phronomy::Runtime::Scheduler

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

Overview

Abstract base class for Runtime scheduler backends.

A scheduler is responsible for turning Runtime#spawn calls into runnable Task objects. Concrete subclasses decide whether tasks execute on threads, Fibers, or some other execution primitive.

The interface is intentionally minimal: callers only see Task objects and never interact with the scheduler directly.

Constant Summary collapse

SCHEDULER_KEY =

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

Thread-local key under which the active scheduler is stored. Shared with Task::FiberBackend (same symbol).

:phronomy_deterministic_scheduler

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.current ⇒ Scheduler?

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 scheduler currently dispatching on this OS thread, or nil when running outside a cooperative (Fiber-based) scheduler context.

Uses Thread#thread_variable_get (not Thread#[]) so that the value is visible across all Fibers running on the same OS thread.

Returns:



27
28
29
 
# File 'lib/phronomy/engine/runtime/scheduler.rb', line 27

def self.current
  Thread.current.thread_variable_get(SCHEDULER_KEY)
end

Instance Method Details

#new_signal ⇒ Object

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 new scheduler-aware signal object for this scheduler. Signalling primitives use this instead of ConditionVariable when a cooperative scheduler is active.

Default implementation raises NotImplementedError. Subclasses that support cooperative suspension (e.g. DeterministicScheduler) must override this.

Returns:

Raises:

  • (NotImplementedError) 


42
43
44
 
# File 'lib/phronomy/engine/runtime/scheduler.rb', line 42

def new_signal
  raise NotImplementedError, "#{self.class}#new_signal is not implemented"
end

#raise_signal(signal) ⇒ void

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.

This method returns an undefined value.

Wakes up one waiter suspended on signal.

Parameters:

  • signal (Object) —

    signal handle returned by #new_signal

Raises:

  • (NotImplementedError) 


61
62
63
 
# File 'lib/phronomy/engine/runtime/scheduler.rb', line 61

def raise_signal(signal)
  raise NotImplementedError, "#{self.class}#raise_signal is not implemented"
end

#raise_signal_all(signal) ⇒ void

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.

This method returns an undefined value.

Wakes up all waiters suspended on signal.

Parameters:

  • signal (Object) —

    signal handle returned by #new_signal

Raises:

  • (NotImplementedError) 


70
71
72
 
# File 'lib/phronomy/engine/runtime/scheduler.rb', line 70

def raise_signal_all(signal)
  raise NotImplementedError, "#{self.class}#raise_signal_all is not implemented"
end

#spawn(name:, parent:) { ... } ⇒ Task

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.

Spawns a new task.

Parameters:

  • name (String, nil) —

    optional human-readable label

  • parent (Task, nil) —

    parent task for cancellation propagation

Yields:

  • block to execute concurrently (or synchronously, depending on the concrete scheduler)

Returns:

Raises:

  • (NotImplementedError) 


82
83
84
 
# File 'lib/phronomy/engine/runtime/scheduler.rb', line 82

def spawn(name:, parent:, &block)
  raise NotImplementedError, "#{self.class}#spawn is not implemented"
end

#wait_for_signal(signal) ⇒ void

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.

This method returns an undefined value.

Suspends the current execution unit (Fiber or Thread) until signal is raised via #raise_signal.

Parameters:

  • signal (Object) —

    signal handle returned by #new_signal

Raises:

  • (NotImplementedError) 


52
53
54
 
# File 'lib/phronomy/engine/runtime/scheduler.rb', line 52

def wait_for_signal(signal)
  raise NotImplementedError, "#{self.class}#wait_for_signal is not implemented"
end

#yield ⇒ void

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.

This method returns an undefined value.

Cooperative yield point.

Default implementation is a no-op. Thread-based subclasses should override with Thread.pass; fiber-based subclasses should switch to the next runnable fiber.



93
94
95
 
# File 'lib/phronomy/engine/runtime/scheduler.rb', line 93

def yield
  # no-op by default; subclasses override
end