async 2.17.0 → 2.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a017a6f3304bf910379aeb0f16a40daa7fce7a3de0a3e56c97a359879a3910d1
-  data.tar.gz: '09a048a8b24b6779d23540f85ba8e5a1d6317d9cfc87f91e74af22960a21fd29'
+  metadata.gz: f095de1e8131ef68c86aeb0176f159d529614e0cc4550e09942c740602e5684c
+  data.tar.gz: 110037688f349d660617df61c86bd637c367a7f0bde68a1920aaac6c508b9de4
 SHA512:
-  metadata.gz: 415e7d9d23c06c60c752bb5b1ecbc336a98bd14b01b33c08bac56e4b8062b6b64761f4fcd8a412455705fb3908b715630beda5eaec7b62e3569e33cb37d235ea
-  data.tar.gz: 8f31cdb2fa5aded62f174683f7a5c62589191bd9263fc9c1d07c78c319592d47f4d3eb46cf92ac0f3005dad219756d16961a6a93823564de1e0263c4f1e70cb3
+  metadata.gz: d287fb690ce18f7b75df003cc7f8a93752c347dc7c0dbcdfcd23fa42827368f228ffcb867482e69f94df87fb140b7bcf0da4ca666692504b1221052dd8c6f6ec
+  data.tar.gz: 8689282009332c05d4e6a958d1e612c77316f2e6084979b2201f073d5afc8e2d05e778d814f35de1a5c83f33c29e08221ca124c4367811f1bc5d92820de61e6b

checksums.yaml.gz.sig

@@ -1,2 +1,2 @@
-Y�exuQ��h����p��.\��Ѽ�Ѱ�@6��fL��b�o�+fo+*5>2e��bچ��2Jx�	C0pw+w1��.�L�Ĭq#�E��{�����
-��
+~	��zv	G���d7���U']XF
��ZE�+l�U�:
+?�(���t��>�oPlKOf�終qO����ݏ��|�u�i�vCT�ЬP�Z��WjH/�璐k��N�F����7���I)��T{�8�=��ȳژ�{Z6�1�G����Q`C�"�zrÛ[e�Pep�

data/lib/async/barrier.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2022, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 
-require_relative 'list'
-require_relative 'task'
+require_relative "list"
+require_relative "task"
 
 module Async
 	# A general purpose synchronisation primitive, which allows one task to wait for a number of other tasks to complete. It can be used in conjunction with {Semaphore}.

data/lib/async/condition.rb

@@ -4,8 +4,8 @@
 # Copyright, 2017-2024, by Samuel Williams.
 # Copyright, 2017, by Kent Gruber.
 
-require 'fiber'
-require_relative 'list'
+require "fiber"
+require_relative "list"
 
 module Async
 	# A synchronization primitive, which allows fibers to wait until a particular condition is (edge) triggered.

data/lib/async/console.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+module Async
+	# Shims for the console gem, redirecting warnings and above to `Kernel#warn`.
+	#
+	# If you require this file, the `async` library will not depend on the `console` gem.
+	#
+	# That includes any gems that sit within the `Async` namespace.
+	#
+	# This is an experimental feature.
+	module Console
+		def self.debug(...)
+		end
+		
+		def self.info(...)
+		end
+		
+		def self.warn(*arguments, exception: nil, **options)
+			if exception
+				super(*arguments, exception.full_message, **options)
+			else
+				super(*arguments, **options)
+			end
+		end
+		
+		def self.error(...)
+			self.warn(...)
+		end
+		
+		def self.fatal(...)
+			self.warn(...)
+		end
+	end
+end

data/lib/async/node.rb

@@ -5,9 +5,9 @@
 # Copyright, 2017, by Kent Gruber.
 # Copyright, 2022, by Shannon Skipper.
 
-require 'fiber/annotation'
+require "fiber/annotation"
 
-require_relative 'list'
+require_relative "list"
 
 module Async
 	# A list of children tasks.

data/lib/async/notification.rb

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2018-2024, by Samuel Williams.
 
-require_relative 'condition'
+require_relative "condition"
 
 module Async
 	# A synchronization primitive, which allows fibers to wait until a notification is received. Does not block the task which signals the notification. Waiting tasks are resumed on next iteration of the reactor.

data/lib/async/queue.rb

@@ -5,7 +5,7 @@
 # Copyright, 2019, by Ryan Musgrave.
 # Copyright, 2020-2022, by Bruno Sutic.
 
-require_relative 'notification'
+require_relative "notification"
 
 module Async
 	# A queue which allows items to be processed in order.
@@ -88,7 +88,7 @@ module Async
 		end
 		
 		# Signal the queue with a value, the same as {#enqueue}.
-		def signal(value)
+		def signal(value = nil)
 			self.enqueue(value)
 		end
 		

data/lib/async/reactor.rb

@@ -5,7 +5,7 @@
 # Copyright, 2017, by Kent Gruber.
 # Copyright, 2018, by Sokolov Yura.
 
-require_relative 'scheduler'
+require_relative "scheduler"
 
 module Async
 	# A wrapper around the the scheduler which binds it to the current thread automatically.

data/lib/async/scheduler.rb

@@ -5,13 +5,13 @@
 # Copyright, 2020, by Jun Jiang.
 # Copyright, 2021, by Julien Portalier.
 
-require_relative 'clock'
-require_relative 'task'
+require_relative "clock"
+require_relative "task"
 
-require 'io/event'
+require "io/event"
 
-require 'console'
-require 'resolv'
+require "console"
+require "resolv"
 
 module Async
 	# Handles scheduling of fibers. Implements the fiber scheduler interface.
@@ -388,6 +388,11 @@ module Async
 				end
 			rescue Interrupt => interrupt
 				Thread.handle_interrupt(::SignalException => :never) do
+					Console.debug(self) do |buffer|
+						buffer.puts "Scheduler interrupted: #{interrupt.inspect}"
+						self.print_hierarchy(buffer)
+					end
+					
 					self.stop
 				end
 				
@@ -395,7 +400,9 @@ module Async
 			end
 			
 			# If the event loop was interrupted, and we finished exiting normally (due to the interrupt), we need to re-raise the interrupt so that the caller can handle it too.
-			Kernel.raise(interrupt) if interrupt
+			if interrupt
+				Kernel.raise(interrupt)
+			end
 		end
 		
 		# Run the reactor until all tasks are finished. Proxies arguments to {#async} immediately before entering the loop, if a block is provided.

data/lib/async/semaphore.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2023, by Samuel Williams.
+# Copyright, 2018-2024, by Samuel Williams.
 
-require_relative 'list'
+require_relative "list"
 
 module Async
 	# A synchronization primitive, which limits access to a given resource.

data/lib/async/task.rb

@@ -7,11 +7,11 @@
 # Copyright, 2020, by Patrik Wenger.
 # Copyright, 2023, by Math Ieu.
 
-require 'fiber'
-require 'console/event/failure'
+require "fiber"
+require "console"
 
-require_relative 'node'
-require_relative 'condition'
+require_relative "node"
+require_relative "condition"
 
 Fiber.attr_accessor :async_task
 
@@ -198,9 +198,7 @@ module Async
 				rescue => error
 					# I'm not completely happy with this overhead, but the alternative is to not log anything which makes debugging extremely difficult. Maybe we can introduce a debug wrapper which adds extra logging.
 					if @finished.nil?
-						Console::Event::Failure.for(error).emit(self, "Task may have ended with unhandled exception.", severity: :warn)
-					else
-						# Console::Event::Failure.for(error).emit(self, severity: :debug)
+						Console.warn(self, "Task may have ended with unhandled exception.", exception: error)
 					end
 					
 					raise

data/lib/async/variable.rb

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2021-2024, by Samuel Williams.
 
-require_relative 'condition'
+require_relative "condition"
 
 module Async
 	# A synchronization primitive that allows one task to wait for another task to resolve a value.

data/lib/async/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2017-2024, by Samuel Williams.
 
 module Async
-	VERSION = "2.17.0"
+	VERSION = "2.19.0"
 end

data/lib/kernel/sync.rb

@@ -3,6 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2019-2024, by Samuel Williams.
 # Copyright, 2020, by Brian Morearty.
+# Copyright, 2024, by Patrik Wenger.
 
 require_relative "../async/reactor"
 
@@ -15,9 +16,13 @@ module Kernel
 	#
 	# @public Since `stable-v1`.
 	# @asynchronous Will block until given block completes executing.
-	def Sync(&block)
+	def Sync(annotation: nil, &block)
 		if task = ::Async::Task.current?
-			yield task
+			if annotation
+				task.annotate(annotation) {yield task}
+			else
+				yield task
+			end
 		elsif scheduler = Fiber.scheduler
 			::Async::Task.run(scheduler, &block).wait
 		else
@@ -25,7 +30,7 @@ module Kernel
 			reactor = Async::Reactor.new
 			
 			begin
-				return reactor.run(finished: ::Async::Condition.new, &block).wait
+				return reactor.run(annotation: annotation, finished: ::Async::Condition.new, &block).wait
 			ensure
 				Fiber.set_scheduler(nil)
 			end

data/readme.md

@@ -35,8 +35,19 @@ Please see the [project documentation](https://socketry.github.io/async/) for mo
 
 Please see the [project releases](https://socketry.github.io/async/releases/index) for all releases.
 
+### v2.19.0
+
+  - [Async::Scheduler Debugging](https://socketry.github.io/async/releases/index#async::scheduler-debugging)
+  - [Console Shims](https://socketry.github.io/async/releases/index#console-shims)
+
+### v2.18.0
+
+  - Add support for `Sync(annotation:)`, so that you can annotate the block with a description of what it does, even if it doesn't create a new task.
+
 ### v2.17.0
 
+  - Introduce `Async::Queue#push` and `Async::Queue#pop` for compatibility with `::Queue`.
+
 ### v2.16.0
 
   - [Better Handling of Async and Sync in Nested Fibers](https://socketry.github.io/async/releases/index#better-handling-of-async-and-sync-in-nested-fibers)

data/releases.md

@@ -1,5 +1,52 @@
 # Releases
 
+## v2.19.0
+
+### Async::Scheduler Debugging
+
+Occasionally on issues, I encounter people asking for help and I need more information. Pressing Ctrl-C to exit a hung program is common, but it usually doesn't provide enough information to diagnose the problem. Setting the `CONSOLE_LEVEL=debug` environment variable will now print additional information about the scheduler when you interrupt it, including a backtrace of the current tasks.
+
+    > CONSOLE_LEVEL=debug bundle exec ruby ./test.rb
+    ^C  0.0s    debug: Async::Reactor [oid=0x974] [ec=0x988] [pid=9116] [2024-11-08 14:12:03 +1300]
+                   | Scheduler interrupted: Interrupt
+                   | #<Async::Reactor:0x0000000000000974 1 children (running)>
+                   | 	#<Async::Task:0x000000000000099c /Users/samuel/Developer/socketry/async/lib/async/scheduler.rb:185:in `transfer' (running)>
+                   | 	→ /Users/samuel/Developer/socketry/async/lib/async/scheduler.rb:185:in `transfer'
+                   | 	  /Users/samuel/Developer/socketry/async/lib/async/scheduler.rb:185:in `block'
+                   | 	  /Users/samuel/Developer/socketry/async/lib/async/scheduler.rb:207:in `kernel_sleep'
+                   | 	  /Users/samuel/Developer/socketry/async/test.rb:7:in `sleep'
+                   | 	  /Users/samuel/Developer/socketry/async/test.rb:7:in `sleepy'
+                   | 	  /Users/samuel/Developer/socketry/async/test.rb:12:in `block in <top (required)>'
+                   | 	  /Users/samuel/Developer/socketry/async/lib/async/task.rb:197:in `block in run'
+                   | 	  /Users/samuel/Developer/socketry/async/lib/async/task.rb:420:in `block in schedule'
+    /Users/samuel/Developer/socketry/async/lib/async/scheduler.rb:317:in `select': Interrupt
+    ... (backtrace continues) ...
+
+This gives better visibility into what the scheduler is doing, and should help diagnose issues.
+
+### Console Shims
+
+The `async` gem depends on `console` gem, because my goal was to have good logging by default without thinking about it too much. However, some users prefer to avoid using the `console` gem for logging, so I've added an experimental set of shims which should allow you to bypass the `console` gem entirely.
+
+``` ruby
+require 'async/console'
+require 'async'
+
+Async{raise "Boom"}
+```
+
+Will now use `Kernel#warn` to print the task failure warning:
+
+    #<Async::Task:0x00000000000012d4 /home/samuel/Developer/socketry/async/lib/async/task.rb:104:in `backtrace' (running)>
+    Task may have ended with unhandled exception.
+    (irb):4:in `block in <top (required)>': Boom (RuntimeError)
+    	from /home/samuel/Developer/socketry/async/lib/async/task.rb:197:in `block in run'
+    	from /home/samuel/Developer/socketry/async/lib/async/task.rb:420:in `block in schedule'
+
+## v2.18.0
+
+  - Add support for `Sync(annotation:)`, so that you can annotate the block with a description of what it does, even if it doesn't create a new task.
+
 ## v2.17.0
 
   - Introduce `Async::Queue#push` and `Async::Queue#pop` for compatibility with `::Queue`.

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.17.0
+  version: 2.19.0
 platform: ruby
 authors:
 - Samuel Williams
 - Bruno Sutic
 - Jeremy Jung
 - Olle Jonsson
-- Devin Christensen
 - Patrik Wenger
+- Devin Christensen
 - Emil Tin
 - Jamie McCarthy
 - Kent Gruber
@@ -63,7 +63,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-09-05 00:00:00.000000000 Z
+date: 2024-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: console
@@ -71,14 +71,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.26'
+        version: '1.29'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.26'
+        version: '1.29'
 - !ruby/object:Gem::Dependency
   name: fiber-annotation
   requirement: !ruby/object:Gem::Requirement
@@ -125,6 +125,7 @@ files:
 - lib/async/clock.rb
 - lib/async/condition.md
 - lib/async/condition.rb
+- lib/async/console.rb
 - lib/async/idler.rb
 - lib/async/list.rb
 - lib/async/node.rb
@@ -161,7 +162,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.1
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="