async-signals 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a6895e75a37685b99999d04d6fa72f0bf38956f5d2022a953348b69461986ff
-  data.tar.gz: b0a98e3b79cb845a4e676b0e3b4f2df64d94fca1903734162fb83784d76c27a0
+  metadata.gz: 969ede7a2ae47c0fe9599becb2508e5c967fae6f9794724441b0c26bb206d94c
+  data.tar.gz: 7498cf8e1e038d238655cfb86d942990d41fa1bd8defde3e31d746c05b7229b1
 SHA512:
-  metadata.gz: 4dfb3560ef7de426d9166ac8b7ada5b0b38013126a871c7890c53ccb6c6c2061eb872ab7d829d8cfaeb84ba1c0ee337fb3cdf773ee82759ebdcb1771785ff83b
-  data.tar.gz: 33508c77b77fadac45d0d58413d7c84fc787ca1cbc89be6cd505ca100677926075d5e800132123b1127f80badf5236452b1337b250bdd4d1a31a9147ec55165c
+  metadata.gz: 5fa34ee6b5d702e0da640a56654f57c1dee5e3d6190ed37d9d78d5d3ea249d7acba78c5d7ad3c01c7e08cd882ab49b08e4dcbba0bf5e9914218c6fd954df6574
+  data.tar.gz: 9861c7a96dbbd194ccf2243599e77e66bf50b949ce593d0f4b369da238d7e0b6b69aaebbabd25979b2e8187af2a66e692312618f86635ae747d588767bcc8f6e

data/context/getting-started.md

@@ -139,7 +139,7 @@ The installed handlers are snapshotted when they are installed. Later changes to
 
 ### 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.
+Use {ruby Async::Signals.default} when a component should install process signal handlers only when it appears to own the process signal boundary. It returns {ruby Async::Signals} on the main thread when no fiber scheduler is installed, and {ruby Async::Signals::Ignore} otherwise.
 
 ```ruby
 require "async/signals"
@@ -150,13 +150,53 @@ handlers.trap(:TERM) do
 end
 
 Async::Signals.default.install(handlers) do
-	# Process signal handlers are active only on the main thread.
+	# Process signal handlers are active only when using the default signal backend.
 	sleep
 end
 ```
 
 Use {ruby Async::Signals::Ignore} directly when a component is controlled by its parent and should not subscribe to process-wide signals.
 
+### Using Signals with Async
+
+When a component runs inside an existing Async event loop, it should not implicitly take ownership of process-wide signals. In that case, {ruby Async::Signals.default} returns {ruby Async::Signals::Ignore}, so installing handlers through the default backend becomes a no-op.
+
+```ruby
+require "async"
+require "async/signals"
+
+handlers = Async::Signals::Handlers.new
+handlers.trap(:TERM) do
+	puts "Stopping..."
+end
+
+Async do
+	Async::Signals.default.install(handlers) do
+		# No process signal traps are installed here.
+		sleep
+	end
+end
+```
+
+If a component running inside an Async event loop is intended to own process signal handling, pass {ruby Async::Signals} explicitly instead of using the default backend.
+
+```ruby
+require "async"
+require "async/signals"
+
+handlers = Async::Signals::Handlers.new
+handlers.trap(:TERM) do |signal, context|
+	context.raise(Interrupt)
+end
+
+Async do
+	Async::Signals.install(handlers) do
+		# Process signal traps are explicitly installed here.
+		sleep
+	end
+end
+```
+
 ## 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

@@ -139,7 +139,7 @@ The installed handlers are snapshotted when they are installed. Later changes to
 
 ### 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.
+Use {ruby Async::Signals.default} when a component should install process signal handlers only when it appears to own the process signal boundary. It returns {ruby Async::Signals} on the main thread when no fiber scheduler is installed, and {ruby Async::Signals::Ignore} otherwise.
 
 ```ruby
 require "async/signals"
@@ -150,13 +150,53 @@ handlers.trap(:TERM) do
 end
 
 Async::Signals.default.install(handlers) do
-	# Process signal handlers are active only on the main thread.
+	# Process signal handlers are active only when using the default signal backend.
 	sleep
 end
 ```
 
 Use {ruby Async::Signals::Ignore} directly when a component is controlled by its parent and should not subscribe to process-wide signals.
 
+### Using Signals with Async
+
+When a component runs inside an existing Async event loop, it should not implicitly take ownership of process-wide signals. In that case, {ruby Async::Signals.default} returns {ruby Async::Signals::Ignore}, so installing handlers through the default backend becomes a no-op.
+
+```ruby
+require "async"
+require "async/signals"
+
+handlers = Async::Signals::Handlers.new
+handlers.trap(:TERM) do
+	puts "Stopping..."
+end
+
+Async do
+	Async::Signals.default.install(handlers) do
+		# No process signal traps are installed here.
+		sleep
+	end
+end
+```
+
+If a component running inside an Async event loop is intended to own process signal handling, pass {ruby Async::Signals} explicitly instead of using the default backend.
+
+```ruby
+require "async"
+require "async/signals"
+
+handlers = Async::Signals::Handlers.new
+handlers.trap(:TERM) do |signal, context|
+	context.raise(Interrupt)
+end
+
+Async do
+	Async::Signals.install(handlers) do
+		# Process signal traps are explicitly installed here.
+		sleep
+	end
+end
+```
+
 ## 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/version.rb

@@ -7,6 +7,6 @@
 module Async
 	# @namespace
 	module Signals
-		VERSION = "0.4.0"
+		VERSION = "0.5.0"
 	end
 end

data/lib/async/signals.rb

@@ -20,14 +20,17 @@ module Async
 			CONTROLLER
 		end
 		
-		# The default signal backend for the current thread.
+		# The default signal backend for the current context.
 		# @returns [Async::Signals | Async::Signals::Ignore] The default signal backend.
 		def self.default
 			if ::Thread.current == ::Thread.main
-				self
-			else
-				Ignore
+				# TruffleRuby does not currently expose `Fiber.scheduler`:
+				unless ::Fiber.respond_to?(:scheduler) && ::Fiber.scheduler
+					return self
+				end
 			end
+			
+			return Ignore
 		end
 		
 		# Install signal handlers using the process-wide signal controller.

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.5.0
+
+  - Change `Async::Signals.default` to select process signal handling only on the main thread when no fiber scheduler is installed.
+
 ### v0.4.0
 
   - Use `Fiber::Scheduler#fiber_interrupt` from `Context#raise` when available, falling back to `Thread#raise`.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.5.0
+
+  - Change `Async::Signals.default` to select process signal handling only on the main thread when no fiber scheduler is installed.
+
 ## v0.4.0
 
   - Use `Fiber::Scheduler#fiber_interrupt` from `Context#raise` when available, falling back to `Thread#raise`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-signals
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Samuel Williams