# Class: Concurrent::SingleThreadExecutor

Inherits:
  SingleThreadExecutorImplementation
  - Object
  - Concurrent::SingleThreadExecutor
  show all

Defined in:
  lib/concurrent/executor/single_thread_executor.rb

## Overview

A thread pool with a single thread an unlimited queue. Should the thread die for any reason it will be removed and replaced, thus ensuring that the executor will always remain viable and available to process jobs.

A common pattern for background processing is to create a single thread on which an infinite loop is run. The thread's loop blocks on an input source (perhaps blocking I/O or a queue) and processes each input as it is received. This pattern has several issues. The thread itself is highly susceptible to errors during processing. Also, the thread itself must be constantly monitored and restarted should it die. `SingleThreadExecutor` encapsulates all these bahaviors. The task processor is highly resilient to errors from within tasks. Also, should the thread die it will automatically be restarted.

The API and behavior of this class are based on Java's `SingleThreadExecutor`.

## Instance Attribute Summary collapse

- #fallback_policy ⇒ Symbol readonly

  The fallback policy in effect.

## Instance Method Summary collapse

- #<<(task) ⇒ self

  Submit a task to the executor for asynchronous processing.

- #auto_terminate=(value) ⇒ Boolean

  Set the auto-terminate behavior for this executor.

- #auto_terminate? ⇒ Boolean

  Is the executor auto-terminate when the application exits?.

- #can_overflow? ⇒ Boolean

  Does the task queue have a maximum size?.

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

  Create a new thread pool.

- #kill ⇒ undocumented

  Begin an immediate shutdown.

- #post(*args) { ... } ⇒ Boolean

  Submit a task to the executor for asynchronous processing.

- #running? ⇒ Boolean

  Is the executor running?.

- #serialized? ⇒ Boolean

  Does this executor guarantee serialization of its operations?.

- #shutdown ⇒ undocumented

  Begin an orderly shutdown.

- #shutdown? ⇒ Boolean

  Is the executor shutdown?.

- #shuttingdown? ⇒ Boolean

  Is the executor shuttingdown?.

- #wait_for_termination(timeout = nil) ⇒ Boolean

  Block until executor shutdown is complete or until `timeout` seconds have passed.

## Constructor Details

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

Create a new thread pool.

Options Hash (`opts`):

- :fallback_policy (`Symbol`) — default: `:discard` —

  the policy for handling new tasks that are received when the queue size has reached `max_queue` or the executor has shut down

Raises:

- (`ArgumentError`) —

  if `:fallback_policy` is not one of the values specified in `FALLBACK_POLICIES`

See Also:

- http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
- http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
- http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html

    # File 'lib/concurrent/executor/single_thread_executor.rb', line 55

## Instance Attribute Details

### #fallback_policy ⇒ `Symbol` (readonly)

Returns The fallback policy in effect. Either `:abort`, `:discard`, or `:caller_runs`.

Returns:

- (`Symbol`) —

  The fallback policy in effect. Either `:abort`, `:discard`, or `:caller_runs`.

    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55

    # File 'lib/concurrent/executor/single_thread_executor.rb', line 36

    class SingleThreadExecutor < SingleThreadExecutorImplementation

      # @!macro single_thread_executor_method_initialize
      #
      #   Create a new thread pool.
      #
      #   @option opts [Symbol] :fallback_policy (:discard) the policy for handling new
      #     tasks that are received when the queue size has reached
      #     `max_queue` or the executor has shut down
      #
      #   @raise [ArgumentError] if `:fallback_policy` is not one of the values specified
      #     in `FALLBACK_POLICIES`
      #
      #   @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
      #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
      #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html

      # @!method initialize(opts = {})
      #   @!macro single_thread_executor_method_initialize
    end

## Instance Method Details

### #<<(task) ⇒ `self`

Submit a task to the executor for asynchronous processing.

Parameters:

- task (`Proc`) —

  the asynchronous task to perform

Returns:

- (`self`) —

  returns itself

    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55

    # File 'lib/concurrent/executor/single_thread_executor.rb', line 36

    class SingleThreadExecutor < SingleThreadExecutorImplementation

      # @!macro single_thread_executor_method_initialize
      #
      #   Create a new thread pool.
      #
      #   @option opts [Symbol] :fallback_policy (:discard) the policy for handling new
      #     tasks that are received when the queue size has reached
      #     `max_queue` or the executor has shut down
      #
      #   @raise [ArgumentError] if `:fallback_policy` is not one of the values specified
      #     in `FALLBACK_POLICIES`
      #
      #   @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
      #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
      #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html

      # @!method initialize(opts = {})
      #   @!macro single_thread_executor_method_initialize
    end

### #auto_terminate=(value) ⇒ `Boolean`

Set the auto-terminate behavior for this executor.

Parameters:

- value (`Boolean`) —

  The new auto-terminate value to set for this executor.

Returns:

- (`Boolean`) —

  `true` when auto-termination is enabled else `false`.

    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55

    # File 'lib/concurrent/executor/single_thread_executor.rb', line 36

    class SingleThreadExecutor < SingleThreadExecutorImplementation

      # @!macro single_thread_executor_method_initialize
      #
      #   Create a new thread pool.
      #
      #   @option opts [Symbol] :fallback_policy (:discard) the policy for handling new
      #     tasks that are received when the queue size has reached
      #     `max_queue` or the executor has shut down
      #
      #   @raise [ArgumentError] if `:fallback_policy` is not one of the values specified
      #     in `FALLBACK_POLICIES`
      #
      #   @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
      #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
      #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html

      # @!method initialize(opts = {})
      #   @!macro single_thread_executor_method_initialize
    end

### #auto_terminate? ⇒ `Boolean`

Is the executor auto-terminate when the application exits?

Returns:

- (`Boolean`) —

  `true` when auto-termination is enabled else `false`.

    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55

    # File 'lib/concurrent/executor/single_thread_executor.rb', line 36

    class SingleThreadExecutor < SingleThreadExecutorImplementation

      # @!macro single_thread_executor_method_initialize
      #
      #   Create a new thread pool.
      #
      #   @option opts [Symbol] :fallback_policy (:discard) the policy for handling new
      #     tasks that are received when the queue size has reached
      #     `max_queue` or the executor has shut down
      #
      #   @raise [ArgumentError] if `:fallback_policy` is not one of the values specified
      #     in `FALLBACK_POLICIES`
      #
      #   @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
      #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
      #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html

      # @!method initialize(opts = {})
      #   @!macro single_thread_executor_method_initialize
    end

### #can_overflow? ⇒ `Boolean`

Does the task queue have a maximum size?

Returns:

- (`Boolean`) —

  True if the task queue has a maximum size else false.

    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55

    # File 'lib/concurrent/executor/single_thread_executor.rb', line 36

    class SingleThreadExecutor < SingleThreadExecutorImplementation

      # @!macro single_thread_executor_method_initialize
      #
      #   Create a new thread pool.
      #
      #   @option opts [Symbol] :fallback_policy (:discard) the policy for handling new
      #     tasks that are received when the queue size has reached
      #     `max_queue` or the executor has shut down
      #
      #   @raise [ArgumentError] if `:fallback_policy` is not one of the values specified
      #     in `FALLBACK_POLICIES`
      #
      #   @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
      #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
      #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html

      # @!method initialize(opts = {})
      #   @!macro single_thread_executor_method_initialize
    end

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

    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55

    # File 'lib/concurrent/executor/single_thread_executor.rb', line 36

    class SingleThreadExecutor < SingleThreadExecutorImplementation

      # @!macro single_thread_executor_method_initialize
      #
      #   Create a new thread pool.
      #
      #   @option opts [Symbol] :fallback_policy (:discard) the policy for handling new
      #     tasks that are received when the queue size has reached
      #     `max_queue` or the executor has shut down
      #
      #   @raise [ArgumentError] if `:fallback_policy` is not one of the values specified
      #     in `FALLBACK_POLICIES`
      #
      #   @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
      #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
      #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html

      # @!method initialize(opts = {})
      #   @!macro single_thread_executor_method_initialize
    end

### #post(*args) { ... } ⇒ `Boolean`

Submit a task to the executor for asynchronous processing.

Parameters:

- args (`Array`) —

  zero or more arguments to be passed to the task

Yields:

- the asynchronous task to perform

Returns:

- (`Boolean`) —

  `true` if the task is queued, `false` if the executor is not running

Raises:

- (`ArgumentError`) —

  if no task is given

    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55

    # File 'lib/concurrent/executor/single_thread_executor.rb', line 36

    class SingleThreadExecutor < SingleThreadExecutorImplementation

      # @!macro single_thread_executor_method_initialize
      #
      #   Create a new thread pool.
      #
      #   @option opts [Symbol] :fallback_policy (:discard) the policy for handling new
      #     tasks that are received when the queue size has reached
      #     `max_queue` or the executor has shut down
      #
      #   @raise [ArgumentError] if `:fallback_policy` is not one of the values specified
      #     in `FALLBACK_POLICIES`
      #
      #   @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
      #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
      #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html

      # @!method initialize(opts = {})
      #   @!macro single_thread_executor_method_initialize
    end

### #running? ⇒ `Boolean`

Is the executor running?

Returns:

- (`Boolean`) —

  `true` when running, `false` when shutting down or shutdown

    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55

    # File 'lib/concurrent/executor/single_thread_executor.rb', line 36

    class SingleThreadExecutor < SingleThreadExecutorImplementation

      # @!macro single_thread_executor_method_initialize
      #
      #   Create a new thread pool.
      #
      #   @option opts [Symbol] :fallback_policy (:discard) the policy for handling new
      #     tasks that are received when the queue size has reached
      #     `max_queue` or the executor has shut down
      #
      #   @raise [ArgumentError] if `:fallback_policy` is not one of the values specified
      #     in `FALLBACK_POLICIES`
      #
      #   @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
      #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
      #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html

      # @!method initialize(opts = {})
      #   @!macro single_thread_executor_method_initialize
    end

### #serialized? ⇒ `Boolean`

Does this executor guarantee serialization of its operations?

Returns:

- (`Boolean`) —

  True if the executor guarantees that all operations will be post in the order they are received and no two operations may occur simultaneously. Else false.

    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55

    # File 'lib/concurrent/executor/single_thread_executor.rb', line 36

    class SingleThreadExecutor < SingleThreadExecutorImplementation

      # @!macro single_thread_executor_method_initialize
      #
      #   Create a new thread pool.
      #
      #   @option opts [Symbol] :fallback_policy (:discard) the policy for handling new
      #     tasks that are received when the queue size has reached
      #     `max_queue` or the executor has shut down
      #
      #   @raise [ArgumentError] if `:fallback_policy` is not one of the values specified
      #     in `FALLBACK_POLICIES`
      #
      #   @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
      #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
      #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html

      # @!method initialize(opts = {})
      #   @!macro single_thread_executor_method_initialize
    end

### #shutdown ⇒ `undocumented`

Begin an orderly shutdown. Tasks already in the queue will be executed, but no new tasks will be accepted. Has no additional effect if the thread pool is not running.

    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55

    # File 'lib/concurrent/executor/single_thread_executor.rb', line 36

    class SingleThreadExecutor < SingleThreadExecutorImplementation

      # @!macro single_thread_executor_method_initialize
      #
      #   Create a new thread pool.
      #
      #   @option opts [Symbol] :fallback_policy (:discard) the policy for handling new
      #     tasks that are received when the queue size has reached
      #     `max_queue` or the executor has shut down
      #
      #   @raise [ArgumentError] if `:fallback_policy` is not one of the values specified
      #     in `FALLBACK_POLICIES`
      #
      #   @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
      #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
      #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html

      # @!method initialize(opts = {})
      #   @!macro single_thread_executor_method_initialize
    end

### #shutdown? ⇒ `Boolean`

Is the executor shutdown?

Returns:

- (`Boolean`) —

  `true` when shutdown, `false` when shutting down or running

    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55

    # File 'lib/concurrent/executor/single_thread_executor.rb', line 36

    class SingleThreadExecutor < SingleThreadExecutorImplementation

      # @!macro single_thread_executor_method_initialize
      #
      #   Create a new thread pool.
      #
      #   @option opts [Symbol] :fallback_policy (:discard) the policy for handling new
      #     tasks that are received when the queue size has reached
      #     `max_queue` or the executor has shut down
      #
      #   @raise [ArgumentError] if `:fallback_policy` is not one of the values specified
      #     in `FALLBACK_POLICIES`
      #
      #   @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
      #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
      #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html

      # @!method initialize(opts = {})
      #   @!macro single_thread_executor_method_initialize
    end

### #shuttingdown? ⇒ `Boolean`

Is the executor shuttingdown?

Returns:

- (`Boolean`) —

  `true` when not running and not shutdown, else `false`

    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55

    # File 'lib/concurrent/executor/single_thread_executor.rb', line 36

    class SingleThreadExecutor < SingleThreadExecutorImplementation

      # @!macro single_thread_executor_method_initialize
      #
      #   Create a new thread pool.
      #
      #   @option opts [Symbol] :fallback_policy (:discard) the policy for handling new
      #     tasks that are received when the queue size has reached
      #     `max_queue` or the executor has shut down
      #
      #   @raise [ArgumentError] if `:fallback_policy` is not one of the values specified
      #     in `FALLBACK_POLICIES`
      #
      #   @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
      #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
      #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html

      # @!method initialize(opts = {})
      #   @!macro single_thread_executor_method_initialize
    end

### #wait_for_termination(timeout = nil) ⇒ `Boolean`

Note:

Does not initiate shutdown or termination. Either `shutdown` or `kill` must be called before this method (or on another thread).

Block until executor shutdown is complete or until `timeout` seconds have passed.

Parameters:

- timeout (`Integer`) (defaults to: `nil`) —

  the maximum number of seconds to wait for shutdown to complete

Returns:

- (`Boolean`) —

  `true` if shutdown complete or false on `timeout`

    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55

    # File 'lib/concurrent/executor/single_thread_executor.rb', line 36

    class SingleThreadExecutor < SingleThreadExecutorImplementation

      # @!macro single_thread_executor_method_initialize
      #
      #   Create a new thread pool.
      #
      #   @option opts [Symbol] :fallback_policy (:discard) the policy for handling new
      #     tasks that are received when the queue size has reached
      #     `max_queue` or the executor has shut down
      #
      #   @raise [ArgumentError] if `:fallback_policy` is not one of the values specified
      #     in `FALLBACK_POLICIES`
      #
      #   @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
      #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
      #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html

      # @!method initialize(opts = {})
      #   @!macro single_thread_executor_method_initialize
    end