123456789_123456789_123456789_123456789_123456789_

Class: Concurrent::SingleThreadExecutor

Relationships & Source Files
Inherits: Concurrent::SingleThreadExecutorImplementation
  • ::Object
Defined in: lib/concurrent-ruby/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

Instance Method Summary

Instance Attribute Details

#fallback_policy ⇒ Symbol (readonly)

Returns:

  • (Symbol) —

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

[ GitHub ] 

  


# File 'lib/concurrent-ruby/concurrent/executor/single_thread_executor.rb', line 37



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
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/executor/single_thread_executor.rb', line 37



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 
  



  

    
Deprecated. 


Has no effect





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.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/executor/single_thread_executor.rb', line 37



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.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/executor/single_thread_executor.rb', line 37



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.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/executor/single_thread_executor.rb', line 37



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  
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/executor/single_thread_executor.rb', line 37



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
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/executor/single_thread_executor.rb', line 37



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
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/executor/single_thread_executor.rb', line 37



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.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/executor/single_thread_executor.rb', line 37



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  
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/executor/single_thread_executor.rb', line 37



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
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/executor/single_thread_executor.rb', line 37



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
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/executor/single_thread_executor.rb', line 37



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
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/concurrent-ruby/concurrent/executor/single_thread_executor.rb', line 37



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