Add scoped signal handling.

Assisted-By: devx/3236e566-7538-432e-a30a-2bdf37265ed4

Author: samuel-williams-shopify

lib/async/container.rb

@@ -3,6 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2017-2025, by Samuel Williams.
 
+require_relative "container/signals"
 require_relative "container/controller"
 
 # @namespace

lib/async/container/signals.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Async
+	module Container
+		# Represents a collection of process signal handlers which enqueue events.
+		class Signals
+			# Represents a trapped signal event.
+			class Event
+				# Initialize the signal event.
+				# @parameter signal [Symbol | String | Integer] The signal that was received.
+				# @parameter handler [Proc] The handler to invoke when the event is applied.
+				def initialize(signal, handler)
+					@signal = signal
+					@handler = handler
+				end
+				
+				# @attribute [Symbol | String | Integer] The signal that was received.
+				attr :signal
+				
+				# Apply the signal event by invoking its handler.
+				def apply
+					@handler.call
+				end
+			end
+			
+			# Initialize the signal handler collection.
+			# @parameter events [Thread::Queue] The queue used to receive signal events.
+			def initialize(events = ::Thread::Queue.new)
+				@events = events
+				@handlers = {}
+			end
+			
+			# @attribute [Thread::Queue] The queue used to receive signal events.
+			attr :events
+			
+			# Register a signal handler.
+			# If no block is provided, the signal will be ignored while trapped.
+			# @parameter signal [Symbol | String | Integer] The signal to trap.
+			def trap(signal, &block)
+				@handlers[signal] = block
+			end
+			
+			# Ignore a signal while trapped.
+			# @parameter signal [Symbol | String | Integer] The signal to ignore.
+			def ignore(signal)
+				trap(signal)
+			end
+			
+			# Wait for the next signal event.
+			# @returns [Event] The next signal event.
+			def wait
+				@events.pop
+			end
+			
+			# Install the registered signal handlers for the duration of the block.
+			# @yields {|signals| ...} The block to run while signal handlers are installed.
+			def trapped
+				previous = {}
+				
+				@handlers.each do |signal, handler|
+					previous[signal] = install(signal, handler)
+				end
+				
+				yield self
+			ensure
+				previous&.each do |signal, handler|
+					::Signal.trap(signal, handler)
+				end
+			end
+			
+			private
+			
+			def install(signal, handler)
+				if handler
+					::Signal.trap(signal) do
+						@events << Event.new(signal, handler)
+					end
+				else
+					::Signal.trap(signal, "IGNORE")
+				end
+			end
+		end
+	end
+end

releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## Unreleased
+
+  - Add `Async::Container::Signals` for installing scoped signal traps that enqueue signal events.
+
 ## v0.37.0
 
   - Rename `ASYNC_CONTAINER_GRACEFUL_TIMEOUT` to `ASYNC_CONTAINER_GRACEFUL_STOP` and apply it at the controller level as `GRACEFUL_STOP`. `Group#stop` now only applies the shutdown policy it is given.

test/async/container/signals.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async/container/signals"
+
+describe Async::Container::Signals do
+	let(:events) {::Thread::Queue.new}
+	let(:signals) {subject.new(events)}
+	
+	with Async::Container::Signals::Event do
+		it "applies the handler" do
+			applied = false
+			
+			event = Async::Container::Signals::Event.new(:USR1, proc{applied = true})
+			
+			expect(event.signal).to be == :USR1
+			
+			event.apply
+			
+			expect(applied).to be == true
+		end
+	end
+	
+	with "#events" do
+		it "exposes the event queue" do
+			expect(signals.events).to be == events
+		end
+	end
+	
+	with "#wait" do
+		it "waits for queued events" do
+			event = Async::Container::Signals::Event.new(:USR1, proc{})
+			
+			events << event
+			
+			expect(signals.wait).to be == event
+		end
+	end
+	
+	with "#trapped" do
+		it "queues trapped signal events" do
+			applied = false
+			
+			signals.trap(:USR1) do
+				applied = true
+			end
+			
+			signals.trapped do
+				::Process.kill(:USR1, ::Process.pid)
+				
+				event = signals.wait
+				
+				expect(event.signal).to be == :USR1
+				
+				event.apply
+			end
+			
+			expect(applied).to be == true
+		end
+		
+		it "ignores signals without a handler" do
+			signals.trap(:USR1)
+			
+			signals.trapped do
+				::Process.kill(:USR1, ::Process.pid)
+				
+				expect do
+					events.pop(true)
+				end.to raise_exception(ThreadError)
+			end
+		end
+		
+		it "can ignore signals explicitly" do
+			signals.ignore(:USR1)
+			
+			signals.trapped do
+				::Process.kill(:USR1, ::Process.pid)
+				
+				expect do
+					events.pop(true)
+				end.to raise_exception(ThreadError)
+			end
+		end
+		
+		it "restores previous signal handlers" do
+			previous = ::Thread::Queue.new
+			original = ::Signal.trap(:USR1) do
+				previous << :handled
+			end
+			
+			begin
+				signals.ignore(:USR1)
+				
+				signals.trapped do
+					::Process.kill(:USR1, ::Process.pid)
+					
+					expect do
+						previous.pop(true)
+					end.to raise_exception(ThreadError)
+				end
+				
+				::Process.kill(:USR1, ::Process.pid)
+				
+				expect(previous.pop).to be == :handled
+			ensure
+				::Signal.trap(:USR1, original)
+			end
+		end
+	end
+end