async-signals 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da817e6b406c01f5ac110ec773c2500ffe01bf6f1715163583a702291512dffc
-  data.tar.gz: 0f0b1eb81532e10ae0b06871b1607458716c021ebc180a100707db1127c6e4d3
+  metadata.gz: d11c9736e5b39139e1875619f776b0ffa1153c6782e3aaed48b0703ec50865ad
+  data.tar.gz: c5eca9092f34e538c9b76bc3feebdc005ca9a7fe8ac1283f77aac16602b245e3
 SHA512:
-  metadata.gz: a158082bb2d16860eb6ade8b1ff4dfbb5270feda5b38300b027563de348244af545f7b2e0e547ed134d3ebb0b0dedd14adec3be9477148e6bbfc8bea5ffef2c5
-  data.tar.gz: d22714bf8e6421f7f762c4819fe3fc73c7ac3f702e8ff77c9ee13209341b9fb26448c01149bf4aa88253695a9c612a106afccb0cf3b5b19c01f47720292870d6
+  metadata.gz: 832500ae1ef771269fa4d05eb6322332ab70e1d9003594001d2ef18831bcd8c4430c65005ca087b167efde19ba765ef5f273f7add5ec639f9b840769dcbf1488
+  data.tar.gz: 937153c1ddf69d8211150f428d5f674f6992cd88526b4b82e1a4a0e26395d238e427a96e378cc69b46b3415a323d087354df9a8c932f881378f22a0fa260389f

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.
@@ -128,6 +129,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.

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.
@@ -128,6 +129,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.

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.2.0"
 	end
 end

data/lib/async/signals.rb

@@ -6,6 +6,7 @@
 require_relative "signals/version"
 require_relative "signals/handlers"
 require_relative "signals/controller"
+require_relative "signals/ignore"
 
 module Async
 	# Provides composable process signal handling.
@@ -18,6 +19,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,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.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,9 @@
 # Releases
 
+## 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.

metadata

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