simple_thread_pool 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ebc46aeec19e5a7572363d8a16e3cb76a1120bfecd31467cc8c232fb5c2480c
-  data.tar.gz: 93ca2bddde18af8b14c88c2b6d346966c115d398f575467c1d5989b7025af80e
+  metadata.gz: 199a48fe6964d0d8ffc112ee6c77da07f49e9111173d36549b6e9e9886a84584
+  data.tar.gz: 4b2d69ac3933cbe8b01ca9a8f4ada69bf29b775d8d465772f7434fa1f2a880c1
 SHA512:
-  metadata.gz: b14225a854eccedd484d1230dcc57276ee1e71cee72654d4f3030d42c9882c3a8321bdff8b148980b9e8662f8f497e814013368ec5eb26d5894807af5e7738f5
-  data.tar.gz: b8f1358b7615e9ab485416222b74fd60c8557f7462fa4088127c3aedc4b7dddc1bbcdea8a4a961ff07de73d4a4a2b8044cd05b95a006c3fc07768713a24c3f08
+  metadata.gz: 587d77f7a33035cfd359f7ba35496eddbcaad070c38244e333b2e4c653eddbe6973f67a346fdb100ad657b23e1e32ee94bc92ef1d91f93adfa3a2cd5a069882d
+  data.tar.gz: ed5801ac689401bef0caa1c66bf5813d8468cb4fca0d28fa3609312914ae195938a181168fa35cf8a06961bd10432fcb3f4b6bce5ea19943f3923db49f843a7b

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 1.0.1
+
+### Fixed
+
+- Threads finishing their work no longer call `Thread#wakeup` on the thread that scheduled them, which could interrupt unrelated `sleep` calls in application code.
+- `finish` now waits for all threads even if a block raised an unhandled exception. Previously `Thread#join` could re-raise the block's exception, causing `finish` to raise and skip joining the remaining threads.
+- Thread scheduling now waits on a condition variable instead of polling in a busy-wait loop, which also removes unsynchronized reads of internal state.
+- An identifier is no longer permanently marked as processing if the thread for it could not be created.
+- `SimpleThreadPool.new` now raises an `ArgumentError` if `max_threads` is less than 1 instead of hanging forever on `execute`.
+- Fatal errors (non-StandardError) raised in threads will now be propagated to the calling thread either in the next call to `execute` or `finish`, instead of being silently swallowed. This allows the calling thread to handle the error appropriately.
+- Removed unnecessary Redis dependency.
+
+## 1.0.0
+
+### Added
+
+- Initial release

data/README.md

@@ -1,4 +1,8 @@
-# SimpleThreadPool
+# Simple Thread Pool
+
+[![Continuous Integration](https://github.com/bdurand/simple_thread_pool/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/bdurand/simple_thread_pool/actions/workflows/continuous_integration.yml)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
+[![Gem Version](https://badge.fury.io/rb/simple_thread_pool.svg)](https://badge.fury.io/rb/simple_thread_pool)
 
 Simple implementation of the thread pool to manage executing tasks in parallel. The thread pool implemented by this code is designed to allow throttled, parallel execution of tasks.
 
@@ -26,7 +30,7 @@ Or install it yourself as:
 
 ```ruby
 # Create a pool of 10 threads to work with.
-thread_pool = SimpleThreadPoolnew(10)
+thread_pool = SimpleThreadPool.new(10)
 
 # Execute a block of code in a thread.
 # If there are no free threads in the pool, then this will block until one is freed up.
@@ -35,8 +39,9 @@ thread_pool.execute do
 end
 
 # Execute a block of code with an identifier.
-# The thread pool will not run code with the same identifier in parallel
-# and will execute them in the order they are called
+# The thread pool will not run code with the same identifier in parallel.
+# Blocks scheduled with the same identifier from a single thread will be
+# executed in the order they are called.
 thread_pool.execute("foo") do
   # Do some work here
 end
@@ -48,7 +53,7 @@ thread_pool.finish
 
 ### Error handling.
 
-All error handling must be conducted inside the execute block. The main thread will not be notified of any exceptions. You can use the `synchronized` method on the thread pool if you need to work data from the main thread.
+All error handling must be conducted inside the execute block. The main thread will not be notified of any exceptions. You can use the `synchronize` method on the thread pool if you need to work with data from the main thread.
 
 Example of how you can track any errors in a shared array.
 
@@ -59,7 +64,7 @@ thread_pool.execute do
   begin
     # Do something
   rescue Error => e
-    thread_pool.synchronized { errors << e }
+    thread_pool.synchronize { errors << e }
     raise e
   end
 end

data/VERSION

@@ -1 +1 @@
-1.0.0
+1.0.1

data/lib/simple_thread_pool.rb

@@ -1,85 +1,170 @@
 # frozen_string_literal: true
 
-require 'thread'
-require 'set'
-
 # Simple thread pool for executing blocks in parallel in a controlled manner.
 # Threads are not re-used by the pool to prevent any thread local variables from
 # leaking out.
 class SimpleThreadPool
+  # Thread variable used to record the exception that terminated a worker thread.
+  WORKER_EXCEPTION = :simple_thread_pool_worker_exception
+  private_constant :WORKER_EXCEPTION
 
+  # @param max_threads [Integer] The maximum number of threads to spawn.
   def initialize(max_threads)
+    raise ArgumentError, "max_threads must be at least 1" unless max_threads >= 1
     @max_threads = max_threads
     @lock = Mutex.new
+    @condition = ConditionVariable.new
     @threads = []
     @processing_ids = []
+    @fatal_exception = nil
   end
 
   # Call this method to spawn a thread to run the block. If the thread pool
   # is already full, this method will block until a thread is free. The block
-  # is responsible for handling any exceptions that could be raised.
+  # is responsible for handling any StandardError that could be raised.
+  #
+  # If a block dies from an exception that is not a StandardError (i.e. an
+  # Exception that indicates the process itself is no longer healthy, such as
+  # NoMemoryError or SystemStackError), the pool is stopped. Blocks passed to
+  # this method after that point are not run; instead this method waits for the
+  # in-flight threads to finish and then raises the exception that stopped the
+  # pool, so that callers never silently lose work. The exception is cleared
+  # when it is raised, so it is delivered to exactly one caller and the pool can
+  # be used again afterwards.
   #
   # The optional id argument can be used to provide an identifier for a block.
   # If one is provided, processing will be blocked if the same id is already
   # being processed. This ensures that each unique id is executed one at a time
   # sequentially.
+  #
+  # @param id [String, Symbol] An optional identifier for the block.
+  # @yield The block to execute in a thread.
+  # @return [void]
   def execute(id = nil, &block)
     loop do
-      # Check if a new thread can be added without blocking.
-      while !can_add_thread?(id)
-        sleep(0.001)
-      end
-      
-      @lock.synchronize do
-        # Check again inside a synchronized block if the thread can still be added.
-        if can_add_thread?(id)
+      stopped = @lock.synchronize do
+        until @fatal_exception || can_add_thread?(id)
+          @condition.wait(@lock)
+        end
+
+        if @fatal_exception
+          true
+        else
           @processing_ids << id unless id.nil?
-          add_thread(id, block)
-          return
+          thread_added = false
+          begin
+            add_thread(id, block)
+            thread_added = true
+          ensure
+            unless thread_added
+              @processing_ids.delete(id) unless id.nil?
+              @condition.broadcast
+            end
+          end
+          false
         end
       end
+
+      break unless stopped
+
+      # The pool has been stopped. Drain the in-flight threads and raise the
+      # exception that stopped it. This has to happen outside of the synchronize
+      # block above because #finish acquires the same lock. If another caller
+      # claimed the exception first then #finish returns normally and the pool
+      # is usable again, so retry rather than silently dropping the block.
+      finish
     end
+
+    nil
   end
 
   # Call this method to block until all current threads have finished executing.
+  #
+  # Exceptions raised by the blocks are not propagated; they are the block's
+  # responsibility to handle. The exception is that if a block died from an
+  # exception that was not a StandardError, that exception is re-raised here
+  # after every in-flight thread has finished. In-flight threads are always
+  # allowed to run to completion rather than being killed, so that they can run
+  # their own ensure blocks. That exception is cleared as it is raised, so it is
+  # delivered to exactly one caller and the pool can be used again afterwards.
+  #
+  # @return [void]
   def finish
-    active_threads = @lock.synchronize { @threads.select(&:alive?) }
-    active_threads.each(&:join)
+    active_threads = @lock.synchronize do
+      # Exclude the calling thread so that this is safe to call from inside a
+      # block running in the pool; Thread#join raises if given the current
+      # thread. #execute calls this method, so that is reachable indirectly.
+      @threads.select { |thread| thread.alive? && !thread.equal?(Thread.current) }
+    end
+    active_threads.each do |thread|
+      thread.join
+    rescue Exception => e # standard:disable Lint/RescueException
+      # Joining a thread that died with an unhandled exception re-raises that
+      # exception; those are the block's responsibility to handle, so they are
+      # not propagated here. Worker threads record the exception that killed
+      # them, so anything else caught here was raised on the calling thread
+      # (e.g. an Interrupt from a signal) and is always re-raised immediately so
+      # that the calling thread stays responsive to signals.
+      raise unless e.equal?(thread.thread_variable_get(WORKER_EXCEPTION))
+    end
+
+    # Claim the exception under the lock and clear it before raising so that it
+    # is delivered to exactly one caller. The pool is usable again afterwards.
+    fatal_exception = @lock.synchronize do
+      exception = @fatal_exception
+      @fatal_exception = nil
+      exception
+    end
+    raise fatal_exception if fatal_exception
+
     nil
   end
 
   # Synchronize data access across the thread pool. This method will block
   # waiting on the same internal Mutex the thread pool uses to manage scheduling
   # threads.
+  #
+  # @yield The block to execute in a synchronized manner.
+  # @return [Object] The return value of the block.
   def synchronize(&block)
     @lock.synchronize(&block)
   end
-  
+
   private
-  
+
   def can_add_thread?(id)
     @threads.size < @max_threads && (id.nil? || !@processing_ids.include?(id))
   end
-  
+
   # Spawn a thread in this method to ensure that it doesn't accidentally pick up any local variables.
   def add_thread(id, block)
-    main_thread = Thread.current
-    
     @threads << Thread.new do
+      fatal_exception = nil
       begin
         block.call
         # Return nil to ensure no objects are leaked.
         nil
+      rescue Exception => e # standard:disable Lint/RescueException
+        # Record the exception so that #finish can tell an exception re-raised
+        # by Thread#join apart from one raised on the calling thread. It is
+        # re-raised so the normal Thread.report_on_exception behavior is kept.
+        Thread.current.thread_variable_set(WORKER_EXCEPTION, e)
+        # Anything that isn't a StandardError means the process is no longer
+        # healthy, so it stops the pool instead of being left to the block.
+        fatal_exception = e unless e.is_a?(StandardError)
+        raise
       ensure
         @lock.synchronize do
+          # Set under the same lock as the broadcast so that callers waiting in
+          # #execute see the stopped pool as soon as they wake up.
+          @fatal_exception ||= fatal_exception
           @processing_ids.delete(id) unless id.nil?
           @threads.delete(Thread.current)
+          @condition.broadcast
         end
-        main_thread.wakeup if main_thread.alive?
       end
     end
 
     nil
   end
-
 end

data/simple_thread_pool.gemspec

@@ -1,23 +1,36 @@
 Gem::Specification.new do |spec|
-  spec.name          = "simple_thread_pool"
-  spec.version       = File.read(File.expand_path("VERSION", __dir__)).chomp
-  spec.authors       = ["Brian Durand"]
-  spec.email         = ["bbdurand@gmail.com"]
+  spec.name = "simple_thread_pool"
+  spec.version = File.read(File.expand_path("VERSION", __dir__)).strip
+  spec.authors = ["Brian Durand"]
+  spec.email = ["bbdurand@gmail.com"]
 
-  spec.summary       = %q{Simple thread pool implementation to manage running tasks in parallel.}
-  spec.homepage      = "https://github.com/bdurand/simple_thread_pool"
-  spec.license       = "MIT"
+  spec.summary = "Simple thread pool implementation to manage running tasks in parallel."
+  spec.homepage = "https://github.com/bdurand/simple_thread_pool"
+  spec.license = "MIT"
+
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => spec.homepage,
+    "changelog_uri" => "#{spec.homepage}/blob/main/CHANGELOG.md"
+  }
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  ignore_files = %w[
+    .
+    Appraisals
+    Gemfile
+    Gemfile.lock
+    Rakefile
+    bin/
+    gemfiles/
+    spec/
+  ]
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject { |f| ignore_files.any? { |path| f.start_with?(path) } }
   end
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.16"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec", "~> 3.8"
+  spec.required_ruby_version = ">= 2.6"
 end

metadata

@@ -1,78 +1,33 @@
 --- !ruby/object:Gem::Specification
 name: simple_thread_pool
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Brian Durand
-autorequire: 
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2019-02-08 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.16'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.16'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '10.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '10.0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.8'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.8'
-description: 
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
 email:
 - bbdurand@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- CHANGE_LOG.md
-- Gemfile
-- LICENSE.txt
+- CHANGELOG.md
+- MIT_LICENSE.txt
 - README.md
-- Rakefile
 - VERSION
 - lib/simple_thread_pool.rb
 - simple_thread_pool.gemspec
 homepage: https://github.com/bdurand/simple_thread_pool
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  homepage_uri: https://github.com/bdurand/simple_thread_pool
+  source_code_uri: https://github.com/bdurand/simple_thread_pool
+  changelog_uri: https://github.com/bdurand/simple_thread_pool/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -80,16 +35,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
-signing_key: 
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Simple thread pool implementation to manage running tasks in parallel.
 test_files: []

data/.gitignore

@@ -1,8 +0,0 @@
-/.bundle/
-/.yardoc
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/

data/CHANGE_LOG.md

@@ -1,3 +0,0 @@
-# 1.0.0
-
-* Initial release

data/Gemfile

@@ -1,6 +0,0 @@
-source "https://rubygems.org"
-
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
-
-# Specify your gem's dependencies in simple_thread_pool.gemspec
-gemspec

data/Rakefile

@@ -1,6 +0,0 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-task :default => :spec