Better types.

Author: ioquatix

lib/async/barrier.rb

@@ -13,7 +13,7 @@ module Async
 	# @public Since *Async v1*.
 	class Barrier
 		# Initialize the barrier.
-		# @parameter parent [Task | Semaphore | Nil] The parent for holding any children tasks.
+		# @parameter parent [_Asyncable?] The parent for holding any children tasks.
 		# @public Since *Async v1*.
 		def initialize(parent: nil)
 			@tasks = List.new
@@ -32,16 +32,17 @@ def initialize(task)
 
 		private_constant :TaskNode
 
-		# Number of tasks being held by the barrier.
+		# @returns [Integer] Number of tasks being held by the barrier.
 		def size
 			@tasks.size
 		end
 
-		# All tasks which have been invoked into the barrier.
+		# @attribute [Array(Task)] All tasks which have been invoked into the barrier.
 		attr :tasks
 
 		# Execute a child task and add it to the barrier.
 		# @asynchronous Executes the given block concurrently.
+		# @rbs [T] (*untyped, parent: _Asyncable, **untyped) {(Task, *untyped) -> T} -> Task[T]
 		def async(*arguments, parent: (@parent or Task.current), **options, &block)
 			waiting = nil
 
@@ -54,8 +55,7 @@ def async(*arguments, parent: (@parent or Task.current), **options, &block)
 			end
 		end
 
-		# Whether there are any tasks being held by the barrier.
-		# @returns [Boolean]
+		# @returns [Boolean] Whether there are any tasks being held by the barrier.
 		def empty?
 			@tasks.empty?
 		end
@@ -65,6 +65,7 @@ def empty?
 		# @yields {|task| ...} If a block is given, the unwaited task is yielded. You must invoke {Task#wait} yourself. In addition, you may `break` if you have captured enough results.
 		#
 		# @asynchronous Will wait for tasks to finish executing.
+		# @rbs () ?{(Task) -> untyped} -> void
 		def wait
 			while !@tasks.empty?
 				# Wait for a task to finish (we get the task node):
@@ -88,6 +89,7 @@ def wait
 
 		# Stop all tasks held by the barrier.
 		# @asynchronous May wait for tasks to finish executing.
+		# @rbs () -> void
 		def stop
 			@tasks.each do |waiting|
 				waiting.task.stop

lib/async/idler.rb

@@ -12,7 +12,7 @@ class Idler
 		#
 		# @parameter maximum_load [Numeric] The maximum load before we start shedding work.
 		# @parameter backoff [Numeric] The initial backoff time, used for delaying work.
-		# @parameter parent [Interface(:async) | Nil] The parent task to use for async operations.
+		# @parameter parent [Interface(Asyncable) | Nil] The parent task to use for async operations.
 		def initialize(maximum_load = 0.8, backoff: 0.01, parent: nil)
 			@maximum_load = maximum_load
 			@backoff = backoff
@@ -24,7 +24,7 @@ def initialize(maximum_load = 0.8, backoff: 0.01, parent: nil)
 		# @asynchronous Executes the given block concurrently.
 		#
 		# @parameter arguments [Array] The arguments to pass to the block.
-		# @parameter parent [Interface(:async) | Nil] The parent task to use for async operations.
+		# @parameter parent [Interface(Asyncable) | Nil] The parent task to use for async operations.
 		# @parameter options [Hash] The options to pass to the task.
 		# @yields {|task| ...} When the system is idle, the block will be executed in a new task.
 		def async(*arguments, parent: (@parent or Task.current), **options, &block)

lib/async/queue.rb

@@ -23,7 +23,7 @@ class ClosedError < RuntimeError
 
 		# Create a new queue.
 		#
-		# @parameter parent [Interface(:async) | Nil] The parent task to use for async operations.
+		# @parameter parent [Interface(Asyncable) | Nil] The parent task to use for async operations.
 		# @parameter available [Notification] The notification to use for signaling when items are available.
 		def initialize(parent: nil, available: Notification.new)
 			@items = []
@@ -104,7 +104,7 @@ def pop
 		# @asynchronous Executes the given block concurrently for each item.
 		#
 		# @parameter arguments [Array] The arguments to pass to the block.
-		# @parameter parent [Interface(:async) | Nil] The parent task to use for async operations.
+		# @parameter parent [Interface(Asyncable) | Nil] The parent task to use for async operations.
 		# @parameter options [Hash] The options to pass to the task.
 		# @yields {|task| ...} When the system is idle, the block will be executed in a new task.
 		def async(parent: (@parent or Task.current), **options, &block)

lib/async/task.rb

@@ -370,7 +370,7 @@ def self.current
 		end
 
 		# Check if there is a task defined for the current fiber.
-		# @returns [Interface(:async) | Nil]
+		# @returns [Interface(Asyncable) | Nil]
 		def self.current?
 			Fiber.current.async_task
 		end

lib/async/waiter.rb

@@ -10,7 +10,7 @@ module Async
 	class Waiter
 		# Create a waiter instance.
 		#
-		# @parameter parent [Interface(:async) | Nil] The parent task to use for asynchronous operations.
+		# @parameter parent [Interface(Asyncable) | Nil] The parent task to use for asynchronous operations.
 		# @parameter finished [::Async::Condition] The condition to signal when a task completes.
 		def initialize(parent: nil, finished: Async::Condition.new)
 			warn("`Async::Waiter` is deprecated, use `Async::Barrier` instead.", uplevel: 1, category: :deprecated) if $VERBOSE

sig/async.rbs

@@ -3,22 +3,20 @@ 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}.
   class Barrier
     # Initialize the barrier.
-    public def initialize: (Task | Semaphore | nil parent) -> void
+    public def initialize: (_Asyncable? parent) -> void
 
-    # Number of tasks being held by the barrier.
-    public def size: () -> untyped
+    public def size: () -> Integer
 
     # Execute a child task and add it to the barrier.
-    public def async: () -> untyped
+    public def async: [T] (*untyped, parent: _Asyncable, **untyped) { (Task, *untyped) -> T } -> Task[T]
 
-    # Whether there are any tasks being held by the barrier.
     public def empty?: () -> bool
 
     # Wait for all tasks to complete by invoking {Task#wait} on each waiting task, which may raise an error. As long as the task has completed, it will be removed from the barrier.
-    public def wait: () { () -> void } -> untyped
+    public def wait: () ?{ (Task) -> untyped } -> void
 
     # Stop all tasks held by the barrier.
-    public def stop: () -> untyped
+    public def stop: () -> void
   end
 
   # A convenient wrapper around the internal monotonic clock.
@@ -91,10 +89,10 @@ module Async
   # A load balancing mechanism that can be used process work when the system is idle.
   class Idler
     # Create a new idler.
-    public def initialize: (Numeric maximum_load, Numeric backoff, Interface parent) -> void
+    public def initialize: (Numeric maximum_load, Numeric backoff, Interface[Asyncable] | nil parent) -> void
 
     # Wait until the system is idle, then execute the given block in a new task.
-    public def async: (Types::Array arguments, Interface parent, Types::Hash options) { () -> void } -> untyped
+    public def async: (Array arguments, Interface[Asyncable] | nil parent, Hash options) { () -> void } -> untyped
 
     # Wait until the system is idle, according to the maximum load specified.
     #
@@ -122,7 +120,7 @@ module Async
     # Add multiple items to the queue.
     #
     # If the queue is full, this method will block until there is space available.
-    public def enqueue: (Types::Array items) -> untyped
+    public def enqueue: (Array items) -> untyped
 
     # Remove and return the next item from the queue.
     #
@@ -251,7 +249,7 @@ module Async
     public def consume: () -> untyped
 
     # Traverse the task tree.
-    public def traverse: () { () -> void } -> Types::Enumerator
+    public def traverse: () { () -> void } -> Enumerator
 
     # Immediately terminate all children tasks, including transient tasks. Internally invokes `stop(false)` on all children. This should be considered a last ditch effort and is used when closing the scheduler.
     public def terminate: () -> untyped
@@ -277,7 +275,7 @@ module Async
   # It has a compatible interface with {Notification} and {Condition}, except that it's multi-value.
   class Queue
     # Create a new queue.
-    public def initialize: (Interface parent, Notification available) -> void
+    public def initialize: (Interface[Asyncable] | nil parent, Notification available) -> void
 
     # Close the queue, causing all waiting tasks to return `nil`. Any subsequent calls to {enqueue} will raise an exception.
     public def close: () -> untyped
@@ -302,7 +300,7 @@ module Async
     public def pop: () -> untyped
 
     # Process each item in the queue.
-    public def async: (Types::Array arguments, Interface parent, Types::Hash options) { () -> void } -> untyped
+    public def async: (Array arguments, Interface[Asyncable] | nil parent, Hash options) { () -> void } -> untyped
 
     # Enumerate each item in the queue.
     public def each: () -> untyped
@@ -365,15 +363,15 @@ module Async
     public def yield: () -> untyped
 
     # Schedule a fiber (or equivalent object) to be resumed on the next loop through the reactor.
-    public def push: (Fiber | Object fiber) -> self
+    public def push: (Any[Fiber, Object] fiber) -> self
 
     # Raise an exception on a specified fiber with the given arguments.
     #
     # This internally schedules the current fiber to be ready, before raising the exception, so that it will later resume execution.
-    public def raise: (Fiber fiber, Types::Array `*arguments`) -> untyped
+    public def raise: (Fiber fiber, Array `*arguments`) -> untyped
 
     # Resume execution of the specified fiber.
-    public def resume: (Fiber fiber, Types::Array arguments) -> untyped
+    public def resume: (Fiber fiber, Array arguments) -> untyped
 
     # Invoked when a fiber tries to perform a blocking operation which cannot continue. A corresponding call {unblock} must be performed to allow this fiber to continue.
     public def block: (Object blocker, Float | nil timeout) -> untyped
@@ -567,7 +565,7 @@ module Async
     public def self.current: () -> Task
 
     # Check if there is a task defined for the current fiber.
-    public def self.current?: () -> Interface
+    public def self.current?: () -> (Interface[Asyncable] | nil)
 
     public def current?: () -> bool
 
@@ -638,7 +636,7 @@ module Async
   # A composable synchronization primitive, which allows one task to wait for a number of other tasks to complete. It can be used in conjunction with {Semaphore} and/or {Barrier}.
   class Waiter
     # Create a waiter instance.
-    public def initialize: (Interface parent, ::Async::Condition finished) -> void
+    public def initialize: (Interface[Asyncable] | nil parent, ::Async::Condition finished) -> void
 
     # Execute a child task and add it to the waiter.
     public def async: () -> untyped

sig/async/asyncable.rbs

@@ -0,0 +1,5 @@
+module Async
+	interface _Asyncable
+		def async: [T] (*untyped, **untyped) { (Task) -> T } -> Task[T]
+	end
+end