Class: Concurrent::TimerSet — Concurrent Ruby

# Class: Concurrent::TimerSet

Inherits:
  RubyExecutorService
  - Object
  - Synchronization::LockableObject
  - AbstractExecutorService
  - RubyExecutorService
  - Concurrent::TimerSet
  show all

Defined in:
  lib/concurrent-ruby/concurrent/executor/timer_set.rb

## Overview

Note:

Time calculations on all platforms and languages are sensitive to changes to the system clock. To alleviate the potential problems associated with changing the system clock while an application is running, most modern operating systems provide a monotonic clock that operates independently of the system clock. A monotonic clock cannot be used to determine human-friendly clock times. A monotonic clock is used exclusively for calculating time intervals. Not all Ruby platforms provide access to an operating system monotonic clock. On these platforms a pure-Ruby monotonic clock will be used as a fallback. An operating system monotonic clock is both faster and more reliable than the pure-Ruby implementation. The pure-Ruby implementation should be fast and reliable enough for most non-realtime operations. At this time the common Ruby platforms that provide access to an operating system monotonic clock are MRI 2.1 and above and JRuby (all versions).

Executes a collection of tasks, each after a given delay. A master task monitors the set and schedules each task for execution at the appropriate time. Tasks are run on the global thread pool or on the supplied executor. Each task is represented as a `ScheduledTask`.

See Also:

- ScheduledTask
- Linux clock_gettime(3)

## Instance Method Summary collapse

- #initialize(opts = {}) ⇒ TimerSet constructor

  Create a new set of timed tasks.

- #kill ⇒ undocumented

  Begin an immediate shutdown.

- #post(delay, *args) { ... } ⇒ Concurrent::ScheduledTask, false

  Post a task to be execute run after a given delay (in seconds).

## Constructor Details

### #initialize(opts = {}) ⇒ `TimerSet`

Create a new set of timed tasks.

Parameters:

- opts (`Hash`) (defaults to: `{}`) —

  the options used to specify the executor on which to perform actions

Options Hash (`opts`):

- :executor (`Executor`) —

  when set use the given `Executor` instance. Three special values are also supported: `:task` returns the global task pool, `:operation` returns the global operation pool, and `:immediate` returns a new `ImmediateExecutor` object.

    30
    31
    32
    # File 'lib/concurrent-ruby/concurrent/executor/timer_set.rb', line 30

    def initialize(opts = {})
      super(opts)
    end

## Instance Method Details

### #kill ⇒ `undocumented`

Begin an immediate shutdown. In-progress tasks will be allowed to complete but enqueued tasks will be dismissed and no new tasks will be accepted. Has no additional effect if the thread pool is not running.

    62
    63
    64
    # File 'lib/concurrent-ruby/concurrent/executor/timer_set.rb', line 62

    def kill
      shutdown
    end

### #post(delay, *args) { ... } ⇒ `Concurrent::ScheduledTask`, `false`

Post a task to be execute run after a given delay (in seconds). If the delay is less than 1/100th of a second the task will be immediately post to the executor.

Parameters:

- delay (`Float`) —

  the number of seconds to wait for before executing the task.

- args (`Array<Object>`) —

  the arguments passed to the task on execution.

Yields:

- the task to be performed.

Returns:

- (`Concurrent::ScheduledTask`, `false`) —

  IVar representing the task if the post is successful; false after shutdown.

Raises:

- (`ArgumentError`) —

  if the intended execution time is not in the future.

- (`ArgumentError`) —

  if no block is given.

    48
    49
    50
    51
    52
    53
    54
    55
    56
    # File 'lib/concurrent-ruby/concurrent/executor/timer_set.rb', line 48

    def post(delay, *args, &task)
      raise ArgumentError.new('no block given') unless block_given?
      return false unless running?
      opts = { executor:  @task_executor,
               args:      args,
               timer_set: self }
      task = ScheduledTask.execute(delay, opts, &task) # may raise exception
      task.unscheduled? ? false : task
    end