Use async-signals for controller traps.

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

Author: samuel-williams-shopify

async-container.gemspec

@@ -25,4 +25,5 @@ Gem::Specification.new do |spec|
 	spec.required_ruby_version = ">= 3.3"
 
 	spec.add_dependency "async", "~> 2.22"
+	spec.add_dependency "async-signals", "~> 0.1"
 end

lib/async/container.rb

@@ -4,7 +4,6 @@
 # Copyright, 2017-2025, by Samuel Williams.
 
 require_relative "container/events"
-require_relative "container/signals"
 require_relative "container/controller"
 
 # @namespace

lib/async/container/controller.rb

@@ -10,7 +10,8 @@
 require_relative "notify"
 require_relative "policy"
 require_relative "events"
-require_relative "signals"
+
+require "async/signals"
 
 module Async
 	module Container
@@ -29,6 +30,25 @@ module Container
 		# Manages the life-cycle of one or more containers in order to support a persistent system.
 		# e.g. a web server, job server or some other long running system.
 		class Controller
+			# Represents a trapped process signal as a queued controller event.
+			class SignalEvent
+				# 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 processed.
+				def initialize(signal, handler)
+					@signal = signal
+					@handler = handler
+				end
+				
+				# @attribute [Symbol | String | Integer] The signal that was received.
+				attr :signal
+				
+				# Process the signal event by invoking the registered handler.
+				def call
+					@handler.call
+				end
+			end
+			
 			SIGHUP = Signal.list["HUP"]
 			SIGINT = Signal.list["INT"]
 			SIGTERM = Signal.list["TERM"]
@@ -44,7 +64,7 @@ def initialize(notify: Notify.open!, container_class: Container, graceful_stop:
 
 				@container = nil
 				@events = Events.new
-				@signals = Signals.new(@events)
+				@signals = Async::Signals::Handlers.new
 
 				self.trap(SIGHUP) do
 					self.restart
@@ -101,7 +121,15 @@ def to_s
 			# @parameters signal [Symbol] The signal to trap, e.g. `:INT`.
 			# @parameters block [Proc] The signal handler to invoke.
 			def trap(signal, &block)
-				@signals.trap(signal, &block)
+				if block
+					event = SignalEvent.new(signal, block).freeze
+					
+					@signals.trap(signal) do
+						@events << event
+					end
+				else
+					@signals.ignore(signal)
+				end
 			end
 
 			# Create a policy for managing child lifecycle events.
@@ -247,7 +275,7 @@ def reload
 			def run
 				@notify&.status!("Initializing controller...")
 
-				@signals.trapped do
+				Async::Signals.install(@signals) do
 					self.start
 
 					while event = @events.pop(timeout: 0)

lib/async/container/signals.rb

@@ -2,7 +2,7 @@
 
 ## Unreleased
 
-  - Add `Async::Container::Signals` for installing scoped signal traps that enqueue signal events.
+  - Use `async-signals` to coordinate controller signal traps while queueing signal events through the controller event loop.
 
 ## v0.37.0
 

releases.md

@@ -210,6 +210,27 @@ def controller.setup(container)
 	with "signals" do
 		include_context Async::Container::AController, "dots"
 
+		it "queues trapped signal events" do
+			controller = Async::Container::Controller.new(notify: nil)
+			applied = false
+			
+			controller.trap(:USR1) do
+				applied = true
+			end
+			
+			Async::Signals.install(controller.instance_variable_get(:@signals)) do
+				Process.kill(:USR1, Process.pid)
+				
+				event = controller.instance_variable_get(:@events).pop(timeout: 1)
+				
+				expect(event.signal).to be == :USR1
+				
+				event.call
+			end
+			
+			expect(applied).to be == true
+		end
+		
 		it "restarts children when receiving SIGHUP" do
 			expect(input.read(1)).to be == "."
 

test/async/container/controller.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async/container/controller"
+
+describe Async::Container::Controller::SignalEvent do
+	it "calls the handler" do
+		applied = false
+		
+		event = subject.new(:USR1, proc{applied = true})
+		
+		expect(event.signal).to be == :USR1
+		
+		event.call
+		
+		expect(applied).to be == true
+	end
+end
+
+describe Async::Container::Events do
+	let(:events) {subject.new}
+	
+	it "wakes IO.select when an event is queued" do
+		event = Object.new
+		
+		events << event
+		
+		readable, _, _ = IO.select([events.io], nil, nil, 0)
+		
+		expect(readable).to be == [events.io]
+		expect(events.pop(timeout: 0)).to be == event
+	end
+	
+	it "returns nil when no event is queued" do
+		expect(events.pop(timeout: 0)).to be_nil
+	end
+end