async 2.14.2 → 2.23.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12cf95e2d70376d5634d24377bb7d3d3974f14f20227fc33450fb103b17f5783
-  data.tar.gz: e0c89541d8d039ec1672b68ef1ae90a86a00c065f6143769734bcbf7cc01d7de
+  metadata.gz: 36ac96ecf26e32e4804f8e89909dcb7b5f8cdfbed24a4da1a189d027586bd0b1
+  data.tar.gz: 35fb378abd8183a2a4950a2b57fd4ba6360c740b51a12ff3e67af5a2c443583c
 SHA512:
-  metadata.gz: cec85cadb861dd14ed374930963e94785e066b8584537e2ef0cc28d8a804372bcf7895f9836d436bd72e20d3f4e0027820ea005dff60120f3d0b66192571e82a
-  data.tar.gz: f11f62065e7fb9072f06b26514e98c33b6aac2988a485ebaf814792a68abe18711f9842187fcfa66282c8ce0290a1064c575a6d1f8cc5a18269f85f82886fc04
+  metadata.gz: 5ff90e092ac86b1dd3e5991e48d44d2b6a9abaa1b72d785d3e9419630f3f8fadd241ab21837bbd5ddd4038792e3ac970bf2aa4b2f67f5a473d4be1caa067f1d5
+  data.tar.gz: 5b71b8eae39aee81b3918f1012c76a4306529292626bf6dc95e79ecebcfa53cda304840655eee56c3392b5a912478ff3178ab4624a2f519ad02d6ce70098f1e2

data/lib/async/barrier.md

@@ -18,7 +18,7 @@ Sync do
 	# Sleep sort the numbers:
 	numbers.each do |number|
 		barrier.async do |task|
-			task.sleep(number)
+			sleep(number)
 			sorted << number
 		end
 	end

data/lib/async/barrier.rb

@@ -1,19 +1,19 @@
 # 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}.
 	#
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class Barrier
 		# Initialize the barrier.
 		# @parameter parent [Task | Semaphore | Nil] The parent for holding any children tasks.
-		# @public Since `stable-v1`.
+		# @public Since *Async v1*.
 		def initialize(parent: nil)
 			@tasks = List.new
 			

data/lib/async/clock.rb

@@ -5,7 +5,7 @@
 
 module Async
 	# A convenient wrapper around the internal monotonic clock.
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class Clock
 		# Get the current elapsed monotonic time.
 		def self.now
@@ -61,5 +61,14 @@ module Async
 			
 			return total
 		end
+		
+		# Reset the total elapsed time. If the clock is currently running, reset the start time to now.
+		def reset!
+			@total = 0
+			
+			if @started
+				@started = Clock.now
+			end
+		end
 	end
 end

data/lib/async/condition.md

@@ -15,7 +15,7 @@ Sync do
 	end
 	
 	Async do |task|
-		task.sleep(1)
+		sleep(1)
 		Console.info "Signalling condition..."
 		condition.signal("Hello World")
 	end

data/lib/async/condition.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2022, by Samuel Williams.
+# 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.
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class Condition
 		# Create a new condition.
 		def initialize

data/lib/async/console.rb

@@ -0,0 +1,42 @@
+# 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
+		# Log a message at the debug level. The shim is silent.
+		def self.debug(...)
+		end
+		
+		# Log a message at the info level. The shim is silent.
+		def self.info(...)
+		end
+		
+		# Log a message at the warn level. The shim redirects to `Kernel#warn`.
+		def self.warn(*arguments, exception: nil, **options)
+			if exception
+				super(*arguments, exception.full_message, **options)
+			else
+				super(*arguments, **options)
+			end
+		end
+		
+		# Log a message at the error level. The shim redirects to `Kernel#warn`.
+		def self.error(...)
+			self.warn(...)
+		end
+		
+		# Log a message at the fatal level. The shim redirects to `Kernel#warn`.
+		def self.fatal(...)
+			self.warn(...)
+		end
+	end
+end

data/lib/async/idler.rb

@@ -7,7 +7,8 @@ module Async
 	# A load balancing mechanism that can be used process work when the system is idle.
 	class Idler
 		# Create a new idler.
-		# @public Since `stable-v2`.
+		#
+		# @public Since *Async v2*.
 		#
 		# @parameter maximum_load [Numeric] The maximum load before we start shedding work.
 		# @parameter backoff [Numeric] The initial backoff time, used for delaying work.
@@ -41,7 +42,8 @@ module Async
 			backoff = nil
 			
 			while true
-				load = scheduler.load 
+				load = scheduler.load
+				
 				break if load < @maximum_load
 				
 				if backoff

data/lib/async/limited_queue.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+# The implementation lives in `queue.rb` but later we may move it here for better autoload/inference.
+require_relative "queue"

data/lib/async/list.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022, by Samuel Williams.
+# Copyright, 2022-2024, by Samuel Williams.
 
 module Async
 	# A general doublely linked list. This is used internally by {Async::Barrier} and {Async::Condition} to manage child tasks.

data/lib/async/node.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2023, by Samuel Williams.
+# Copyright, 2017-2024, by Samuel Williams.
 # 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.
@@ -34,6 +34,19 @@ module Async
 			empty?
 		end
 		
+		# Adjust the number of transient children, assuming it has changed.
+		#
+		# Despite being public, this is not intended to be called directly. It is used internally by {Node#transient=}.
+		#
+		# @parameter transient [Boolean] Whether to increment or decrement the transient count.
+		def adjust_transient_count(transient)
+			if transient
+				@transient_count += 1
+			else
+				@transient_count -= 1
+			end
+		end
+		
 		private
 		
 		def added(node)
@@ -110,6 +123,19 @@ module Async
 			@transient
 		end
 		
+		# Change the transient state of the node.
+		#
+		# A transient node is not considered when determining if a node is finished, and propagates up if the parent is consumed.
+		#
+		# @parameter value [Boolean] Whether the node is transient.
+		def transient=(value)
+			if @transient != value
+				@transient = value
+				
+				@parent&.children&.adjust_transient_count(value)
+			end
+		end
+		
 		# Annotate the node with a description.
 		#
 		# @parameter annotation [String] The description to annotate the node with.

data/lib/async/notification.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2022, by Samuel Williams.
+# 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.
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class Notification < Condition
 		# Signal to a given task that it should resume operations.
 		def signal(value = nil, task: Task.current)

data/lib/async/queue.rb

@@ -1,18 +1,18 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2022, by Samuel Williams.
+# Copyright, 2018-2024, by Samuel Williams.
 # 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.
 	#
 	# It has a compatible interface with {Notification} and {Condition}, except that it's multi-value.
 	#
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class Queue
 		# Create a new queue.
 		#
@@ -38,12 +38,17 @@ module Async
 		end
 		
 		# Add an item to the queue.
-		def <<(item)
+		def push(item)
 			@items << item
 			
 			@available.signal unless self.empty?
 		end
 		
+		# Compatibility with {::Queue#push}.
+		def <<(item)
+			self.push(item)
+		end
+		
 		# Add multiple items to the queue.
 		def enqueue(*items)
 			@items.concat(items)
@@ -60,6 +65,11 @@ module Async
 			@items.shift
 		end
 		
+		# Compatibility with {::Queue#pop}.
+		def pop
+			self.dequeue
+		end
+		
 		# Process each item in the queue.
 		#
 		# @asynchronous Executes the given block concurrently for each item.
@@ -82,7 +92,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
 		
@@ -93,7 +103,7 @@ module Async
 	end
 	
 	# A queue which limits the number of items that can be enqueued.
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	class LimitedQueue < Queue
 		# Create a new limited queue.
 		#
@@ -119,7 +129,7 @@ module Async
 		# If the queue is full, this method will block until there is space available.
 		#
 		# @parameter item [Object] The item to add to the queue.
-		def <<(item)
+		def push(item)
 			while limited?
 				@full.wait
 			end

data/lib/async/reactor.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2022, by Samuel Williams.
+# Copyright, 2017-2024, by Samuel Williams.
 # 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.