async-signals 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d11c9736e5b39139e1875619f776b0ffa1153c6782e3aaed48b0703ec50865ad
-  data.tar.gz: c5eca9092f34e538c9b76bc3feebdc005ca9a7fe8ac1283f77aac16602b245e3
+  metadata.gz: 892b6d001f6a23c4190ecb71cd652d63aea1a7331932a68f3b0f057f8cdf762e
+  data.tar.gz: fd8a403c5abfe0a943ce0ec4c684ea5b6ba390f6c76006ed6772d0e12532d903
 SHA512:
-  metadata.gz: 832500ae1ef771269fa4d05eb6322332ab70e1d9003594001d2ef18831bcd8c4430c65005ca087b167efde19ba765ef5f273f7add5ec639f9b840769dcbf1488
-  data.tar.gz: 937153c1ddf69d8211150f428d5f674f6992cd88526b4b82e1a4a0e26395d238e427a96e378cc69b46b3415a323d087354df9a8c932f881378f22a0fa260389f
+  metadata.gz: cc9458635104d6f45cdcde03512d1e5e3dcaf09f21fa345bad891f678e2a5f6d80177c5dd7f84bc11e0a2d2b4b0c4582bba5cea9871bae6aafefaf320b05b124
+  data.tar.gz: f885189f0ae71ef8c529bf17ae23c9ad080c22641716fd30e4c54c11bc0659786c030536b6448472ac9fb66667ed0736e180e0e746bfe3972cd9ad26589a8022

data/context/getting-started.md

@@ -55,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.
@@ -169,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

@@ -55,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.
@@ -169,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/version.rb

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

data/lib/async/signals.rb

@@ -4,6 +4,7 @@
 # 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"

data/readme.md

@@ -24,6 +24,10 @@ 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.

data/releases.md

@@ -1,5 +1,9 @@
 # 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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-signals
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -47,6 +47,7 @@ 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