shoryuken 7.0.2 → 7.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63763ea11f3377475150b2270c7162fa5cb9a35e39cdd2a534e353837dc3e6ff
-  data.tar.gz: f265d74ebdb8a087cb658a8f442489523305e7cd551e5fae4ae16f9709f238ae
+  metadata.gz: 988d29701fd4b73dea7d965b283ae8d3fccf5b9737a7e3acdfe5cc760ca82cc5
+  data.tar.gz: b91a7b40cab94ca17fb432433a81323deba9675a3398678c80db1b3a7aa454fb
 SHA512:
-  metadata.gz: 012a20c2c6cf74c8af2be01f046e137f74df8f6ca0746bc3c05f3dfc6eb45d0bf320a4a6493917c8c12371f94dafb0777873eb71d4298f097ecdb1bf9f9b2fd5
-  data.tar.gz: e257ec56be80a862449937cf882fd2dfb42037c4b9e1bbfe2987463a45e7bd0857a18a94bafd225ecb3e170180a62d59b4e3cd926d863246621d6c5683bce9a1
+  metadata.gz: e6bc156e3e5387ad74c4a740cae775f6f633b67c26395a3aac11e51b7cc47771785918e5ec457d3f2317148846ef3ad0b137b5f6e012f3f75aec6536a2eb2deb
+  data.tar.gz: 87f0feeae55309458dbd5eab9fea4fbdb83a5689bd526b0e22857cb89f0af7027346f2e1487614965b3208aafaf6167dc7bb2573e160d45cfb54e8133baa09c0

data/.github/workflows/push.yml

@@ -19,12 +19,12 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
         with:
           fetch-depth: 0
 
       - name: Set up Ruby
-        uses: ruby/setup-ruby@e65c17d16e57e481586a6a5a0282698790062f92 # v1.300.0
+        uses: ruby/setup-ruby@d45b1a4e94b71acab930e56e79c6aa188764e7f9 # v1.316.0
         with:
           bundler-cache: false
 
@@ -33,4 +33,4 @@ jobs:
           bundle install --jobs 4 --retry 3
 
       # Release
-      - uses: rubygems/release-gem@6317d8d1f7e28c24d28f6eff169ea854948bd9f7 # v1.2.0
+      - uses: rubygems/release-gem@052cc82692552de3ef2b81fd670e41d13cba8092 # v1.4.0

data/.github/workflows/specs.yml

@@ -11,17 +11,41 @@ jobs:
       matrix:
         ruby: ['3.2', '3.3', '3.4', '4.0']
     runs-on: ubuntu-latest
+    # Unit specs finish in under a minute; fail fast instead of letting a
+    # wedged runner occupy the job slot for the 6-hour default
+    timeout-minutes: 10
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
 
-      - uses: ruby/setup-ruby@e65c17d16e57e481586a6a5a0282698790062f92 # v1.300.0
+      - uses: ruby/setup-ruby@d45b1a4e94b71acab930e56e79c6aa188764e7f9 # v1.316.0
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
 
       - name: Run specs
-        run: bundle exec rake spec
+        run: |
+          # Run rspec directly (not via rake) so $SPEC_PID is the ruby process
+          # itself — the USR1 watchdog below sends the signal to that pid, and
+          # spec_helper registers a USR1 handler that prints a thread dump.
+          # Running via 'bundle exec rake spec' would send the signal to rake,
+          # which has no USR1 handler and would crash before the dump appears.
+          bundle exec rspec --format documentation &
+          SPEC_PID=$!
+          # Send USR1 after 8 minutes so the thread-dump handler in spec_helper
+          # prints a backtrace before the 10-minute job timeout kills everything.
+          ( sleep 480
+            if kill -0 $SPEC_PID 2>/dev/null; then
+              echo "=== specs still running after 8 minutes — requesting thread dump ==="
+              kill -USR1 $SPEC_PID 2>/dev/null || true
+              sleep 5
+            fi
+          ) &
+          WATCHDOG_PID=$!
+          wait $SPEC_PID
+          EXIT_CODE=$?
+          kill $WATCHDOG_PID 2>/dev/null || true
+          exit $EXIT_CODE
 
   integrations:
     name: Integrations
@@ -29,9 +53,11 @@ jobs:
       matrix:
         ruby: ['3.2', '3.3', '3.4', '4.0']
     runs-on: ubuntu-latest
+    # Integration specs normally take ~4 minutes
+    timeout-minutes: 15
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
 
       - name: Start ElasticMQ
         run: docker compose up -d
@@ -45,7 +71,7 @@ jobs:
           done
           '
 
-      - uses: ruby/setup-ruby@e65c17d16e57e481586a6a5a0282698790062f92 # v1.300.0
+      - uses: ruby/setup-ruby@d45b1a4e94b71acab930e56e79c6aa188764e7f9 # v1.316.0
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
@@ -56,6 +82,7 @@ jobs:
   ci-success:
     name: CI Success
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     if: always()
     needs:
       - specs

data/.github/workflows/verify-action-pins.yml

@@ -7,7 +7,7 @@ jobs:
   verify:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
       - name: Check SHA pins
         run: |
           if grep -E -r "uses: .*/.*@(v[0-9]+|main|master)($|[[:space:]]|$)" --include="*.yml" --include="*.yaml" .github/workflows/ | grep -v "#"; then

data/.ruby-version

@@ -1 +1 @@
-4.0.2
+4.0.5

data/CHANGELOG.md

@@ -1,3 +1,110 @@
+## [Unreleased]
+
+## [7.0.3] - 2026-07-10
+
+- Feature: `Shoryuken.active_job_fifo_message_deduplication` to opt out of FIFO dedup id generation (mensfeld)
+  - For FIFO queues the ActiveJob adapter derives a content-based `message_deduplication_id` from the
+    serialized job minus `job_id`/`enqueued_at` (#457 / #750), so two distinct enqueues of the same job
+    class and arguments within SQS's 5-minute window silently collapse into one - a "skipped message" trap
+  - Set `Shoryuken.active_job_fifo_message_deduplication = false` to stop generating that id, so identical
+    jobs are no longer silently dropped (rely on the queue's content-based deduplication or explicit ids)
+  - Defaults to `true`, preserving the existing behavior; an explicit `message_deduplication_id` is still honored
+
+- Fix: Polling strategies are now thread-safe, and WeightedRoundRobin unpauses processed queues reliably (mensfeld)
+  - `message_processed` runs on processor-completion threads (for FIFO queues) while `next_queue`/`messages_found`
+    run on the dispatch thread; they mutate the same state with no synchronization, which is benign on MRI (GVL)
+    but corrupts state on JRuby/TruffleRuby. Both `WeightedRoundRobin` and `StrictPriority` now serialize access
+    with a mutex
+  - `WeightedRoundRobin#unpause_queues` only checked the head of the paused list, so a queue marked ready by
+    `message_processed` could stay stuck behind an earlier-paused queue; it now unpauses the first expired entry
+    anywhere in the list
+
+- Fix: `TimerTask#kill` no longer deadlocks on Ruby 3.2 under concurrent callers (mensfeld)
+  - `kill` called `@thread.kill` while holding `@mutex`; the timer loop's `ensure` block calls
+    `@mutex.synchronize` to clear `@running`, so on Ruby 3.2 (where `Thread#kill` yields the GVL
+    to the killed thread for cleanup before returning) both threads waited on each other forever
+  - The thread is now killed after the mutex is released, so the ensure block can always acquire it
+
+- Fix: Stopping the launcher no longer destroys the process-global IO executor (mensfeld)
+  - With no `launcher_executor` configured, `Launcher#executor` fell back to `Concurrent.global_io_executor`,
+    and `Launcher#stop`/`#stop!` call `shutdown` (and `kill`) on it
+  - Shutting down that process-wide pool broke anything else relying on concurrent-ruby's `:io` pool
+    (including Shoryuken's own `ShoryukenConcurrentSendAdapter`) and prevented starting a fresh launcher
+    in the same process
+  - The launcher now owns a dedicated `Concurrent::CachedThreadPool`, so stopping it leaves the global
+    IO executor untouched
+
+- Fix: `Queue#delete_messages` now logs every batch-delete failure and returns a robust boolean (mensfeld)
+  - It used `failed.any? { |f| logger.error ... }`, which short-circuited after the first failure - so when
+    a batch had multiple failures only the first was logged - and only returned truthy because `Logger#error`
+    happens to return true (a custom logger returning falsey would have hidden the failure from callers)
+  - It now logs each failure and returns `failed.any?`, so `NonRetryableException`/`AutoDelete` reliably see
+    that some messages may remain and need reprocessing
+
+- Fix: Lifecycle events fired in reverse no longer alternate handler order (mensfeld)
+  - `Util#fire_event` reversed the stored handler array in place with `reverse!`, so an event fired more
+    than once with `reverse: true` (e.g. `:shutdown` via `stop` then `stop!`) flipped order each time
+  - It now reverses a copy, leaving the stored handler order untouched
+
+- Fix: A fatal dispatch error no longer hard-kills an embedded host process (mensfeld)
+  - `Manager#handle_dispatch_error` sent `Process.kill('USR1', Process.pid)` unconditionally after a
+    dispatch error (e.g. SQS still failing once the fetcher exhausted its retries)
+  - The CLI Runner traps USR1 and turns it into a graceful shutdown, but a host embedding
+    `Shoryuken::Launcher` directly has USR1's default disposition, so the whole process - and its
+    in-flight workers - was terminated
+  - When embedded (no CLI Runner), the failing manager now just stops itself and `Launcher#healthy?`
+    reports the failure; the USR1 signal is only sent in server (CLI) mode, preserving the
+    supervisor-restart behavior there
+
+- Fix: Graceful stop is now bounded by the configured timeout (mensfeld)
+  - `Launcher#stop` (the soft shutdown behind USR1/TSTP) called `executor.wait_for_termination` with no
+    argument - an unbounded wait - so a single hung worker blocked shutdown forever
+  - Both `Launcher#stop` and `Launcher#stop!` now share a `shutdown_executor` helper that waits up to
+    `Shoryuken.options[:timeout]` seconds for in-flight workers, then force-kills the executor so the
+    process can exit; the graceful stop still waits for workers, just no longer indefinitely
+
+- Docs: Correct the `retry_intervals` exponential backoff documentation (mensfeld)
+  - The `exponential_backoff?` docstring claimed retries stop ("before giving up") after the last configured
+    interval. They do not: once the intervals are exhausted, the last interval is reused for every later
+    attempt, and SQS's redrive policy (maxReceiveCount) is what ultimately moves a message to a dead-letter queue
+  - Added a spec pinning that far-later attempts keep reusing the last interval
+
+- Fix: `CurrentAttributes.persist` no longer drops a class when called once per class (mensfeld)
+  - The storage key was derived from the per-call index, so registering classes across separate `persist`
+    calls made the third call reuse `cattr_0` and silently overwrite the second class - its attributes were
+    then never serialized or restored
+  - The key now uses the running registry size, so incremental and single-call registration both yield
+    distinct, stable keys (single-call `persist(A, B, C)` keys are unchanged)
+
+- Fix: Busy-processor accounting no longer breaks when processor completion raises (mensfeld)
+  - `Manager#assign` chained `.then { processor_done }.rescue { processor_done }`, so an exception inside
+    `processor_done` (SQS lookups or a polling strategy's `message_processed` callback) ran completion twice
+  - The busy counter was decremented twice for one message and drifted negative, inflating `ready` and
+    silently breaking the configured concurrency limit for the life of the process
+  - Completion now runs in an `ensure` around processing (exactly once), and `processor_done` logs
+    instead of leaking exceptions from the FIFO bookkeeping
+
+- Fix: Repeated graceful stop no longer deadlocks the process (mensfeld)
+  - `Manager#await_dispatching_in_progress` popped a signal queue that received exactly one token,
+    so a second `Launcher#stop` blocked forever on an empty queue
+  - Operationally this was the TSTP -> USR1 sequence: both signals trigger a graceful stop, leaving
+    the process stuck in the signal loop where even TERM/INT were no longer handled (only SIGKILL worked)
+  - The dispatch loop now closes the signal queue instead of pushing a token, releasing every pending
+    and future waiter; the dispatch chain also releases waiters if the executor rejects a post during
+    a racing hard shutdown
+
+- Fix: `non_retryable_exceptions` is no longer ignored when `retry_intervals` is also configured (mensfeld)
+  - `ExponentialBackoffRetry` swallowed every exception after scheduling a retry, so `NonRetryableException`
+    (which sits outside it in the default middleware chain) never saw non-retryable errors - poison messages
+    were retried indefinitely (with the last interval repeated) instead of being deleted immediately
+  - `ExponentialBackoffRetry` now re-raises exceptions classified as non-retryable so the message gets deleted
+  - Exception classification is extracted to `NonRetryableException.non_retryable?` and shared by both middlewares
+
+- Enhancement: Use dynamic Ruby warning category opt-in in test helpers (mensfeld)
+  - Replace version-gated `Warning[:performance]` with `Warning.categories`-based auto-enablement
+  - Automatically enables all non-deprecated, non-experimental warning categories for forward compatibility
+  - Applied to both `spec/spec_helper.rb` and `spec/integrations_helper.rb`
+
 ## [7.0.2] - 2026-04-16
 
 - Enhancement: Replace LocalStack with ElasticMQ for SQS integration tests (mensfeld)

data/bin/cli/sqs.rb

@@ -146,6 +146,13 @@ module Shoryuken
                            value[:string_value].bytesize
                          elsif value[:binary_value]
                            value[:binary_value].bytesize
+                         else
+                           # List-type attributes (string_list_values /
+                           # binary_list_values) carry no scalar value here and
+                           # are intentionally not requeued (see
+                           # normalize_dump_message). Size them as 0 rather than
+                           # crashing the whole batch with `nil + Integer`.
+                           0
                          end
             name_size + data_type_size + value_size
           end

data/bin/integrations

@@ -70,21 +70,23 @@ class IntegrationRunner
   def run_specs(specs)
     results = []
 
-    specs.each do |spec|
+    specs.each_with_index do |spec, idx|
+      prefix = "[#{idx + 1}/#{specs.size}]"
+      puts "#{prefix} RUNNING  #{spec[:name]}"
+      $stdout.flush
+
       result = run_spec(spec)
       results << result
 
-      if result[:skipped]
-        print 'S'
-      elsif result[:success]
-        print '.'
-      else
-        print 'F'
-      end
+      elapsed = result[:duration] ? format('%.1fs', result[:duration]) : '?'
+      status  = if result[:skipped] then 'SKIPPED'
+                elsif result[:success] then 'OK     '
+                else                       'FAILED '
+                end
+      puts "#{prefix} #{status} #{spec[:name]} (#{elapsed})"
       $stdout.flush
     end
 
-    puts
     results
   end
 
@@ -132,34 +134,50 @@ class IntegrationRunner
     output = []
     start_time = Time.now
 
-    begin
-      Timeout.timeout(TIMEOUT) do
-        # Use unbundled env to prevent pollution from previous test runs
-        # This is especially important after Rails integration tests that use
-        # bundle install --standalone with different gem versions
-        Bundler.with_unbundled_env do
-          IO.popen(env, cmd, chdir: spec[:directory], err: [:child, :out]) do |io|
-            io.each_line { |line| output << line }
-          end
+    Bundler.with_unbundled_env do
+      # Use non-block popen so we control when waitpid runs.  The block form
+      # calls io.close (which calls waitpid internally) as part of its own
+      # ensure, so if the child is still running when Timeout::Error fires,
+      # io.close blocks indefinitely before we can rescue the error.
+      io = IO.popen(env, cmd, chdir: spec[:directory], err: [:child, :out])
+      timed_out = false
+
+      begin
+        Timeout.timeout(TIMEOUT) do
+          io.each_line { |line| output << line }
+        end
+      rescue Timeout::Error
+        timed_out = true
+      ensure
+        # Kill before closing: io.close calls waitpid, which blocks if the
+        # child is still alive.  Sending SIGKILL first guarantees the child
+        # exits promptly so waitpid (inside io.close) returns immediately.
+        begin
+          Process.kill('KILL', io.pid)
+        rescue Errno::ESRCH
+          # Child already exited on its own — nothing to kill
         end
+        io.close rescue nil
       end
 
-      {
-        spec: spec,
-        success: $?.success?,
-        exit_code: $?.exitstatus,
-        duration: Time.now - start_time,
-        output: output.join
-      }
-    rescue Timeout::Error
-      {
-        spec: spec,
-        success: false,
-        exit_code: -1,
-        error: 'Timeout',
-        duration: Time.now - start_time,
-        output: output.join
-      }
+      if timed_out
+        {
+          spec: spec,
+          success: false,
+          exit_code: -1,
+          error: 'Timeout',
+          duration: Time.now - start_time,
+          output: output.join
+        }
+      else
+        {
+          spec: spec,
+          success: $?.success?,
+          exit_code: $?.exitstatus,
+          duration: Time.now - start_time,
+          output: output.join
+        }
+      end
     end
   end
 

data/lib/active_job/queue_adapters/shoryuken_adapter.rb

@@ -177,9 +177,11 @@ module ActiveJob
           message_attributes: attributes.merge(MESSAGE_ATTRIBUTES)
         }
 
-        if queue.fifo?
+        if queue.fifo? && Shoryuken.active_job_fifo_message_deduplication?
           # See https://github.com/ruby-shoryuken/shoryuken/issues/457 and
           # https://github.com/ruby-shoryuken/shoryuken/pull/750#issuecomment-1781317929
+          # Disable via Shoryuken.active_job_fifo_message_deduplication = false when distinct
+          # enqueues of the same job class and arguments must not be silently deduplicated.
           msg[:message_deduplication_id] = Digest::SHA256.hexdigest(
             JSON.dump(body.except('job_id', 'enqueued_at'))
           )

data/lib/shoryuken/active_job/current_attributes.rb

@@ -11,7 +11,12 @@ module Shoryuken
     # This ensures that request-scoped context (like current user, tenant, locale)
     # automatically flows from the code that enqueues a job to the job's execution.
     #
-    # Based on Sidekiq's approach to persisting current attributes.
+    # Based on Sidekiq's approach to persisting current attributes, with one
+    # deliberate difference in cleanup: Sidekiq only touches the classes carried
+    # by a job and leaves the general reset to the Rails executor it runs jobs
+    # inside. Shoryuken does not run jobs inside that executor by default, so the
+    # loader resets every registered class after each job itself - see the note
+    # on {Loading#perform}.
     #
     # @example Setup in initializer
     #   require 'shoryuken/active_job/current_attributes'
@@ -58,8 +63,12 @@ module Shoryuken
         def persist(*klasses)
           @cattrs ||= {}
 
-          klasses.flatten.each_with_index do |klass, idx|
-            key = @cattrs.empty? ? 'cattr' : "cattr_#{idx}"
+          klasses.flatten.each do |klass|
+            # Key off the running registry size, not the per-call index, so that
+            # registering classes across separate persist calls still produces
+            # distinct keys (a per-call index restarts at 0 each call and would
+            # overwrite earlier registrations).
+            key = @cattrs.empty? ? 'cattr' : "cattr_#{@cattrs.size}"
             @cattrs[key] = klass.to_s
           end
 
@@ -109,13 +118,10 @@ module Shoryuken
         # @param hash [Hash] the deserialized job data
         # @return [void]
         def perform(sqs_msg, hash)
-          klasses_to_reset = []
-
           CurrentAttributes.cattrs&.each do |key, klass_name|
             next unless hash.key?(key)
 
             klass = klass_name.constantize
-            klasses_to_reset << klass
 
             begin
               attrs = Serializer.deserialize(hash[key])
@@ -131,7 +137,29 @@ module Shoryuken
 
           super
         ensure
-          klasses_to_reset.each(&:reset)
+          # Reset every registered CurrentAttributes class after the job - not
+          # only the ones whose key was in this message.
+          #
+          # Why unconditional (and why this differs from Sidekiq): Sidekiq's
+          # loader only touches classes present in the job and relies on the
+          # Rails executor - which it runs every job inside - to reset all
+          # CurrentAttributes between units of work. Shoryuken has no such safety
+          # net: it wraps a job in the reloader/executor only when
+          # `enable_reloading` is set, which is off by default, so nothing else
+          # clears CurrentAttributes between jobs.
+          #
+          # A blanket reset here is therefore the only thing guaranteeing a clean
+          # thread. Resetting only the present keys leaks whenever a value ends up
+          # set during a job whose message carried no cattr key - e.g. the worker
+          # (or code it calls) writes to Current, on a keyless message (empty
+          # context at enqueue, a different producer, or persist configured after
+          # the message was queued). CurrentAttributes are thread-local and the
+          # pool reuses threads, so that value would surface in the next job.
+          CurrentAttributes.cattrs&.each_value do |klass_name|
+            klass_name.constantize.reset
+          rescue => e
+            Shoryuken.logger.warn("Failed to reset CurrentAttributes #{klass_name}: #{e.message}")
+          end
         end
       end
     end

data/lib/shoryuken/fetcher.rb

@@ -72,12 +72,18 @@ module Shoryuken
 
       shoryuken_queue = Shoryuken::Client.queues(queue.name)
 
-      options[:max_number_of_messages]  = max_number_of_messages(shoryuken_queue, limit, options)
       options[:message_attribute_names] = %w[All]
       options[:attribute_names]         = %w[All]
 
+      # Merge per-queue options BEFORE computing the cap so the FIFO
+      # one-at-a-time guard (and FETCH_LIMIT) always win. Computing the cap last
+      # means a queue option of max_number_of_messages can only lower the count,
+      # never raise a non-batch FIFO queue above 1 - which would let SQS return
+      # several messages from the same group and break ordering.
       options.merge!(queue.options)
 
+      options[:max_number_of_messages] = max_number_of_messages(shoryuken_queue, limit, options)
+
       shoryuken_queue.receive_messages(options)
     end
 

data/lib/shoryuken/helpers/timer_task.rb

@@ -42,14 +42,21 @@ module Shoryuken
       #
       # @return [Boolean] true if killed, false if already killed
       def kill
+        thread_to_kill = nil
+
         @mutex.synchronize do
           return false if @killed
 
           @killed = true
           @running = false
-
-          @thread.kill if @thread&.alive?
+          thread_to_kill = @thread
         end
+
+        # Kill the thread AFTER releasing the mutex. The timer loop's ensure
+        # block calls @mutex.synchronize to clear @running; killing the thread
+        # while holding that mutex deadlocks on Ruby 3.2, where Thread#kill
+        # yields the GVL to the killed thread for cleanup before returning.
+        thread_to_kill&.kill if thread_to_kill&.alive?
         true
       end
 
@@ -59,6 +66,16 @@ module Shoryuken
       #
       # @return [void]
       def run_timer_loop
+        # The timer thread inherits the priority of the thread that called
+        # #execute. Shoryuken runs workers at a lowered priority
+        # (Shoryuken.thread_priority, default -1) and starts the
+        # auto-visibility-extension timer from inside that worker thread, so the
+        # timer would otherwise inherit -1. A latency-sensitive timer must not
+        # run below normal priority: under CPU contention a delayed extension can
+        # miss the visibility timeout and let the message be redelivered (double
+        # processed). Reset to normal priority.
+        Thread.current.priority = 0
+
         until @killed
           sleep(@execution_interval)
           break if @killed

data/lib/shoryuken/launcher.rb

@@ -43,8 +43,7 @@ module Shoryuken
       # Don't await here so the timeout below is not delayed
       stop_new_dispatching
 
-      executor.shutdown
-      executor.kill unless executor.wait_for_termination(Shoryuken.options[:timeout])
+      shutdown_executor
 
       fire_event(:stopped)
     end
@@ -61,8 +60,7 @@ module Shoryuken
       stop_new_dispatching
       await_dispatching_in_progress
 
-      executor.shutdown
-      executor.wait_for_termination
+      shutdown_executor
 
       fire_event(:stopped)
     end
@@ -93,11 +91,29 @@ module Shoryuken
       @managers.each(&:await_dispatching_in_progress)
     end
 
+    # Shuts the executor down, giving in-flight workers up to the configured
+    # timeout to finish before force-killing them so the process can exit.
+    # Used by both the graceful ({#stop}) and immediate ({#stop!}) shutdowns:
+    # a graceful stop still waits for workers, but must not block forever on a
+    # hung one.
+    #
+    # @return [void]
+    def shutdown_executor
+      executor.shutdown
+      executor.kill unless executor.wait_for_termination(Shoryuken.options[:timeout])
+    end
+
     # Returns the executor for running async operations
     #
+    # Owns a dedicated executor rather than borrowing Concurrent.global_io_executor:
+    # {#stop} and {#stop!} shut down and kill this executor, and destroying the
+    # process-global pool would break anything else relying on it (including
+    # Shoryuken's own ShoryukenConcurrentSendAdapter) and prevent a fresh launcher
+    # from starting in the same process.
+    #
     # @return [Concurrent::ExecutorService] the executor service
     def executor
-      @_executor ||= Shoryuken.launcher_executor || Concurrent.global_io_executor
+      @_executor ||= Shoryuken.launcher_executor || Concurrent::CachedThreadPool.new(auto_terminate: true)
     end
 
     # Starts all managers in parallel futures

data/lib/shoryuken/manager.rb

@@ -57,6 +57,9 @@ module Shoryuken
       # There might still be a dispatching on-going, as the response from SQS could take some time
       # We don't want to stop the process before processing incoming messages, as they would stay "in-flight" for some time on SQS
       # We use a queue, as the dispatch_loop is running on another thread, and this is a efficient way of communicating between threads.
+      # The dispatch loop closes the queue when it observes the stop flag; pop on a closed queue
+      # returns immediately, so this stays safe when stop is requested more than once
+      # (e.g. TSTP followed by USR1, which both trigger a graceful stop).
       @dispatching_release_signal.pop
     end
 
@@ -74,11 +77,23 @@ module Shoryuken
     # @return [void]
     def dispatch_loop
       if @stop_new_dispatching.true? || !running?
-        @dispatching_release_signal << 1
+        # Close (instead of push) so every pending and future
+        # await_dispatching_in_progress call returns, not just the first one
+        @dispatching_release_signal.close
         return
       end
 
       @executor.post { dispatch }
+    rescue Concurrent::RejectedExecutionError
+      # The executor was shut down between the running? check and the post
+      # (e.g. a hard stop racing the dispatch loop); release any waiters as
+      # the dispatch chain ends here
+      @dispatching_release_signal.close
+    rescue StandardError
+      # Unexpected error from post (e.g. ThreadError if the OS thread limit is
+      # hit); the dispatch chain ends here so release waiters before re-raising
+      @dispatching_release_signal.close
+      raise
     end
 
     # Dispatches messages from a queue
@@ -129,6 +144,12 @@ module Shoryuken
       return unless @polling_strategy.respond_to?(:message_processed)
 
       @polling_strategy.message_processed(queue)
+    rescue => e
+      # Swallow (but log) failures from the SQS lookups or the strategy callback:
+      # the busy counter was already decremented above and the caller's ensure
+      # must not run completion twice
+      logger.error { "Processor completion failed for #{queue}: #{e.message}" }
+      logger.debug { e.backtrace.join("\n") } unless e.backtrace.nil?
     end
 
     # Assigns a message to a processor
@@ -144,6 +165,11 @@ module Shoryuken
       @busy_processors.increment
       fire_utilization_update_event
 
+      # Completion runs in an ensure so it executes exactly once whether
+      # processing succeeds or raises. The previous `.then { processor_done }
+      # .rescue { processor_done }` chain ran completion twice when
+      # processor_done itself raised, double decrementing the busy counter
+      # and silently breaking the concurrency limit
       Concurrent::Promise
         .execute(executor: @executor) do
           original_priority = Thread.current.priority
@@ -152,10 +178,9 @@ module Shoryuken
             Processor.process(queue_name, sqs_msg)
           ensure
             Thread.current.priority = original_priority
+            processor_done(queue_name)
           end
         end
-        .then { processor_done(queue_name) }
-        .rescue { processor_done(queue_name) }
     end
 
     # Dispatches a batch of messages from a queue
@@ -208,9 +233,17 @@ module Shoryuken
       logger.error { "Manager failed: #{ex.message}" }
       logger.error { ex.backtrace.join("\n") } unless ex.backtrace.nil?
 
-      Process.kill('USR1', Process.pid)
-
+      # Stop this manager first so Launcher#healthy? surfaces the failure to
+      # whoever is supervising us (the CLI Runner, or an embedding application).
       @running.make_false
+
+      # In server (CLI) mode the Runner traps USR1 and turns it into a graceful
+      # shutdown of the whole process, so a process supervisor can restart us.
+      # When embedded (no Runner), USR1 keeps its default disposition and would
+      # terminate the host process - and any in-flight workers - so we must not
+      # send it. The stopped manager above is enough for Launcher#healthy? to
+      # report the failure to the embedding application.
+      Process.kill('USR1', Process.pid) if Shoryuken.server?
     end
 
     # Fires a utilization update event