Select default signals only at top level. (#5)

Author: samuel-williams-shopify

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.

lib/async/signals.rb

@@ -20,14 +20,17 @@ def self.controller
 			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.

releases.md

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

test/async/signals.rb

@@ -11,6 +11,34 @@
 describe Async::Signals do
 	include Async::Signals::QueueAssertions
 
+	def make_scheduler
+		Object.new.tap do |scheduler|
+			scheduler.define_singleton_method(:block) do |*|
+			end
+			
+			scheduler.define_singleton_method(:unblock) do |*|
+			end
+			
+			scheduler.define_singleton_method(:kernel_sleep) do |*|
+			end
+			
+			scheduler.define_singleton_method(:io_wait) do |*|
+			end
+			
+			scheduler.define_singleton_method(:fiber_interrupt) do |*|
+			end
+		end
+	end
+	
+	def with_scheduler
+		previous_scheduler = ::Fiber.scheduler
+		::Fiber.set_scheduler(make_scheduler)
+		
+		yield
+	ensure
+		::Fiber.set_scheduler(previous_scheduler)
+	end
+	
 	it "has a version number" do
 		expect(subject::VERSION).to be_a(String)
 	end
@@ -23,17 +51,25 @@
 	end
 
 	with ".default" do
-		it "returns process signals on the main thread" do
+		it "returns process signals on the main thread without a scheduler" do
 			expect(subject.default).to be == subject
 		end
 
-		it "ignores process signals on other threads" do
+		it "ignores process signals outside the top level" do
 			default = ::Thread.new do
 				subject.default
 			end.value
 
 			expect(default).to be == subject::Ignore
 		end
+		
+		it "ignores process signals when a scheduler is installed" do
+			skip "Fiber.set_scheduler is not supported." unless ::Fiber.respond_to?(:set_scheduler)
+			
+			with_scheduler do
+				expect(subject.default).to be == subject::Ignore
+			end
+		end
 	end
 
 	with ".install" do