async-signals 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da817e6b406c01f5ac110ec773c2500ffe01bf6f1715163583a702291512dffc
-  data.tar.gz: 0f0b1eb81532e10ae0b06871b1607458716c021ebc180a100707db1127c6e4d3
+  metadata.gz: 892b6d001f6a23c4190ecb71cd652d63aea1a7331932a68f3b0f057f8cdf762e
+  data.tar.gz: fd8a403c5abfe0a943ce0ec4c684ea5b6ba390f6c76006ed6772d0e12532d903
 SHA512:
-  metadata.gz: a158082bb2d16860eb6ade8b1ff4dfbb5270feda5b38300b027563de348244af545f7b2e0e547ed134d3ebb0b0dedd14adec3be9477148e6bbfc8bea5ffef2c5
-  data.tar.gz: d22714bf8e6421f7f762c4819fe3fc73c7ac3f702e8ff77c9ee13209341b9fb26448c01149bf4aa88253695a9c612a106afccb0cf3b5b19c01f47720292870d6
+  metadata.gz: cc9458635104d6f45cdcde03512d1e5e3dcaf09f21fa345bad891f678e2a5f6d80177c5dd7f84bc11e0a2d2b4b0c4582bba5cea9871bae6aafefaf320b05b124
+  data.tar.gz: f885189f0ae71ef8c529bf17ae23c9ad080c22641716fd30e4c54c11bc0659786c030536b6448472ac9fb66667ed0736e180e0e746bfe3972cd9ad26589a8022

data/context/getting-started.md

@@ -25,6 +25,7 @@ Ruby signal handlers are process-wide. Calling `Signal.trap` for the same signal
 - {ruby Async::Signals::Handlers} represents a configurable set of signal handlers for one consumer.
 - {ruby Async::Signals::Controller} owns the process-wide `Signal.trap` entries while handler sets are installed.
 - {ruby Async::Signals.install} installs a handler set using the default process-wide controller.
+- {ruby Async::Signals::Ignore} provides a no-op signal backend for code that should not install process signal traps.
 - {ruby Async::Signals.reset!} removes all active handlers and restores the previous signal traps.
 
 Each handler set can trap or ignore signals independently. When multiple handler sets trap the same signal, `async-signals` installs one Ruby signal trap and dispatches the signal to each active handler.
@@ -54,6 +55,14 @@ end
 
 When the block exits, the handler set is removed and any previous signal trap is restored.
 
+Handlers may also accept the context that installed the handler set. This is useful when a signal should interrupt the component that installed the handlers, regardless of which thread dispatches the signal trap.
+
+```ruby
+handlers.trap(:INT) do |signal, context|
+	context.raise(Interrupt)
+end
+```
+
 ### Multiple Consumers
 
 Multiple parts of an application can listen for the same signal. This is useful when a service, supervisor, and application component each need to observe shutdown signals without taking ownership of the process-wide trap.
@@ -128,6 +137,26 @@ end
 
 The installed handlers are snapshotted when they are installed. Later changes to the handler set do not affect an existing registration.
 
+### Choosing a Signal Backend
+
+Use {ruby Async::Signals.default} when a component should install process signal handlers only while running on the main thread. It returns {ruby Async::Signals} on the main thread and {ruby Async::Signals::Ignore} on other threads.
+
+```ruby
+require "async/signals"
+
+handlers = Async::Signals::Handlers.new
+handlers.trap(:TERM) do
+	puts "Stopping..."
+end
+
+Async::Signals.default.install(handlers) do
+	# Process signal handlers are active only on the main thread.
+	sleep
+end
+```
+
+Use {ruby Async::Signals::Ignore} directly when a component is controlled by its parent and should not subscribe to process-wide signals.
+
 ## Forking
 
 Signal traps are inherited across `fork`. On Ruby implementations that support `Process._fork`, `async-signals` automatically resets inherited signal state in the forked child so the child does not keep handler registrations from the parent process.
@@ -148,6 +177,8 @@ Avoid calling `Signal.trap` for the same signals while `async-signals` handlers
 
 Keep signal handlers thread safe. Ruby implementations may dispatch signal traps from an implementation-specific thread, so handlers should avoid mutating shared state directly. Prefer doing minimal work in the handler and forwarding the event to a thread-safe mechanism such as `Thread::Queue`.
 
+Handler exceptions propagate from dispatch. If multiple handler sets observe the same signal and one handler raises, later handlers may not run.
+
 ## Troubleshooting
 
 If a handler is not invoked, check that the handler set is installed at the time the signal is delivered. Handler sets are only active inside the `Async::Signals.install` block, or until the returned registration is closed.

data/guides/getting-started/readme.md

@@ -25,6 +25,7 @@ Ruby signal handlers are process-wide. Calling `Signal.trap` for the same signal
 - {ruby Async::Signals::Handlers} represents a configurable set of signal handlers for one consumer.
 - {ruby Async::Signals::Controller} owns the process-wide `Signal.trap` entries while handler sets are installed.
 - {ruby Async::Signals.install} installs a handler set using the default process-wide controller.
+- {ruby Async::Signals::Ignore} provides a no-op signal backend for code that should not install process signal traps.
 - {ruby Async::Signals.reset!} removes all active handlers and restores the previous signal traps.
 
 Each handler set can trap or ignore signals independently. When multiple handler sets trap the same signal, `async-signals` installs one Ruby signal trap and dispatches the signal to each active handler.
@@ -54,6 +55,14 @@ end
 
 When the block exits, the handler set is removed and any previous signal trap is restored.
 
+Handlers may also accept the context that installed the handler set. This is useful when a signal should interrupt the component that installed the handlers, regardless of which thread dispatches the signal trap.
+
+```ruby
+handlers.trap(:INT) do |signal, context|
+	context.raise(Interrupt)
+end
+```
+
 ### Multiple Consumers
 
 Multiple parts of an application can listen for the same signal. This is useful when a service, supervisor, and application component each need to observe shutdown signals without taking ownership of the process-wide trap.
@@ -128,6 +137,26 @@ end
 
 The installed handlers are snapshotted when they are installed. Later changes to the handler set do not affect an existing registration.
 
+### Choosing a Signal Backend
+
+Use {ruby Async::Signals.default} when a component should install process signal handlers only while running on the main thread. It returns {ruby Async::Signals} on the main thread and {ruby Async::Signals::Ignore} on other threads.
+
+```ruby
+require "async/signals"
+
+handlers = Async::Signals::Handlers.new
+handlers.trap(:TERM) do
+	puts "Stopping..."
+end
+
+Async::Signals.default.install(handlers) do
+	# Process signal handlers are active only on the main thread.
+	sleep
+end
+```
+
+Use {ruby Async::Signals::Ignore} directly when a component is controlled by its parent and should not subscribe to process-wide signals.
+
 ## Forking
 
 Signal traps are inherited across `fork`. On Ruby implementations that support `Process._fork`, `async-signals` automatically resets inherited signal state in the forked child so the child does not keep handler registrations from the parent process.
@@ -148,6 +177,8 @@ Avoid calling `Signal.trap` for the same signals while `async-signals` handlers
 
 Keep signal handlers thread safe. Ruby implementations may dispatch signal traps from an implementation-specific thread, so handlers should avoid mutating shared state directly. Prefer doing minimal work in the handler and forwarding the event to a thread-safe mechanism such as `Thread::Queue`.
 
+Handler exceptions propagate from dispatch. If multiple handler sets observe the same signal and one handler raises, later handlers may not run.
+
 ## Troubleshooting
 
 If a handler is not invoked, check that the handler set is installed at the time the signal is delivered. Handler sets are only active inside the `Async::Signals.install` block, or until the returned registration is closed.

data/lib/async/signals/context.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Async
+	module Signals
+		# Represents the execution context that installed a signal handler set.
+		class Context
+			# Initialize the context.
+			def initialize
+				# Capture both primitives so the public interface can evolve without
+				# changing the handler arguments.
+				@thread = ::Thread.current
+				@fiber = ::Fiber.current
+			end
+			
+			# Raise an exception in the thread that installed the handler set.
+			# @parameter arguments [Array] The arguments to pass to {Thread#raise}.
+			def raise(*arguments)
+				@thread.raise(*arguments)
+			end
+		end
+	end
+end

data/lib/async/signals/controller.rb

@@ -6,6 +6,7 @@
 require "thread"
 
 require_relative "handlers"
+require_relative "context"
 
 module Async
 	module Signals
@@ -74,9 +75,11 @@ module Async
 				end
 				
 				# The active callable signal handlers.
-				# @returns [Array(Proc)] The active handlers.
+				# @returns [Array(Array(Proc, Context))] The active handlers and the contexts that installed them.
 				def callbacks
-					@handlers.values.freeze
+					@handlers.map do |registration, handler|
+						[handler, registration.context]
+					end.freeze
 				end
 			end
 			
@@ -88,8 +91,12 @@ module Async
 				def initialize(controller, handlers)
 					@controller = controller
 					@handlers = handlers
+					@context = Context.new
 				end
 				
+				# @attribute [Context] The context that installed this registration.
+				attr :context
+				
 				# Remove this registration from the controller.
 				def close
 					if handlers = @handlers
@@ -138,12 +145,8 @@ module Async
 			def dispatch(signal)
 				number = ::Signal.list.fetch(signal)
 				
-				@dispatch[signal]&.each do |handler|
-					begin
-						handler.call(number)
-					rescue Exception => error
-						warn "Async::Signals handler failed: #{error.class}: #{error.message}"
-					end
+				@dispatch[signal]&.each do |handler, context|
+					handler.call(number, context)
 				end
 			end
 			

data/lib/async/signals/handlers.rb

@@ -16,6 +16,7 @@ module Async
 			
 			# Trap a signal while these handlers are installed.
 			# @parameter signal [Symbol | String | Integer] The signal to trap.
+			# @yields {|signal, context| ...} The signal number and the context that installed the handler set.
 			def trap(signal, &block)
 				@signals[normalize(signal)] = block
 			end

data/lib/async/signals/ignore.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Async
+	module Signals
+		# Provides a no-op signal backend.
+		module Ignore
+			# Represents a no-op signal registration.
+			class Registration
+				# Close the registration.
+				def close
+				end
+			end
+			
+			REGISTRATION = Registration.new.freeze
+			
+			# Ignore signal handlers.
+			# @parameter handlers [Handlers] The handlers to ignore.
+			# @returns [Registration] The no-op registration.
+			def self.install(handlers)
+				if block_given?
+					yield handlers
+				else
+					REGISTRATION
+				end
+			end
+		end
+	end
+end

data/lib/async/signals/version.rb

@@ -7,6 +7,6 @@
 module Async
 	# @namespace
 	module Signals
-		VERSION = "0.1.0"
+		VERSION = "0.3.0"
 	end
 end

data/lib/async/signals.rb

@@ -4,8 +4,10 @@
 # Copyright, 2026, by Samuel Williams.
 
 require_relative "signals/version"
+require_relative "signals/context"
 require_relative "signals/handlers"
 require_relative "signals/controller"
+require_relative "signals/ignore"
 
 module Async
 	# Provides composable process signal handling.
@@ -18,6 +20,16 @@ module Async
 			CONTROLLER
 		end
 		
+		# The default signal backend for the current thread.
+		# @returns [Async::Signals | Async::Signals::Ignore] The default signal backend.
+		def self.default
+			if ::Thread.current == ::Thread.main
+				self
+			else
+				Ignore
+			end
+		end
+		
 		# Install signal handlers using the process-wide signal controller.
 		# @parameter handlers [Handlers] The handlers to install.
 		# @returns [Controller::Registration] The active registration.

data/readme.md

@@ -9,6 +9,7 @@ Composable process signal handling for Ruby.
   - Coordinates process-wide signal traps across multiple consumers.
   - Supports overlapping signal handlers without replacing each other.
   - Supports scoped ignore handlers for specific signals.
+  - Provides a no-op signal backend for components that should not install process signal traps.
   - Restores previous signal traps when handlers are removed.
   - Resets inherited signal state in forked children on Ruby implementations with `Process._fork`.
   - Documents thread-safe signal handler design for portable signal delivery.
@@ -23,6 +24,14 @@ Please see the [project documentation](https://socketry.github.io/async-signals/
 
 Please see the [project releases](https://socketry.github.io/async-signals/releases/index) for all releases.
 
+### v0.3.0
+
+  - Pass the installing context as the second signal handler argument and allow handler exceptions to propagate.
+
+### v0.2.0
+
+  - Add `Async::Signals.default` and `Async::Signals::Ignore` for selecting process signal handling based on the current thread.
+
 ### v0.1.0
 
   - Initial release.

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v0.3.0
+
+  - Pass the installing context as the second signal handler argument and allow handler exceptions to propagate.
+
+## v0.2.0
+
+  - Add `Async::Signals.default` and `Async::Signals::Ignore` for selecting process signal handling based on the current thread.
+
 ## v0.1.0
 
   - Initial release.

data.tar.gz.sig

@@ -1,3 +1,2 @@
-5
-���}��yBYj����Ur��`�^���x3�+f*����q�m���&�KN�n�����Şap�>UfPա��s��9�T1f �+n۵rz3Î��Ԇ��d�a}�a[N�o�s�3��D/w¨F~2��"��>͎8���c�3�h�����d��
-k�obI��E�F7yB���BF+C�:����,�ƥ�:k�ۻc�W�ry��QQRU�u�	��:�d���	9w}q��2���6�@zy�.�<��?c�,n��H�`N6۹�/�m�7Y�B���z�SK5�$��T�~e��)-��-Kf����_%�O��<��L�u�K�1�;ޠS6:��-
+,�7Hk22�"�9������;-U�`X�D*ց;7�O�ї_��C孛���1��<E���v�4����C$�b"i����c�Çy�P�@������<���K�Q?\8����O��U:��)|S�;�(A� 
�
+�nn������J�f�޼Ԁ�~!��X�ٜP�(��8b�D�$��B�vwz��fs�-G/E�K*~�X��&_���

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-signals
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -47,8 +47,10 @@ files:
 - guides/getting-started/readme.md
 - guides/links.yaml
 - lib/async/signals.rb
+- lib/async/signals/context.rb
 - lib/async/signals/controller.rb
 - lib/async/signals/handlers.rb
+- lib/async/signals/ignore.rb
 - lib/async/signals/version.rb
 - license.md
 - readme.md