async 2.4.2 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d64eb10a6e308731e79afd4591092d17ef5d4ffca9e40d9ee128a1d14b30669
-  data.tar.gz: 8c5fda19ac8eb203bdd6a27100f90b47295d1ff882811d78da257342ae240258
+  metadata.gz: c732b7d676e5d1248189f0e3b9fbce25c44026633bd2094c30a94c7a82ee40a3
+  data.tar.gz: a668963f5721f56883ca4fecd7fda0b198f9b8ec2e4276fb126d30d547d18589
 SHA512:
-  metadata.gz: b1b8f7644eda45639f9a53e314b195ad2955b10358148edf6e698be89cb7232c22be15d3a0214f14a2053bc4a6e3e78683f1ef22d1da02a1fc7cd83e1a71b2fc
-  data.tar.gz: 109375f5cd3c217341316c4b5f390d7a2a57bda847bbaa8d98ec13e93fa9dbc6905978bad00641182b7d4daf4e87c0ac7286b43ca5a6522f0610b37e8206d7df
+  metadata.gz: 2480c08bd9dcd8ebfefcabb02d347f3b1aa3f4485202f101b351ac3b585390c2f5471f21fa34c959483ad2b976d6491b49c8dd63b869776f40157011e25a3404
+  data.tar.gz: 68b04041436ba8080614878d6903b7658ffe8a6c092b6ba38efa41e0fa9e9bdb1cffbcff7ed299f206c431b56ef8bbb089b1a07689c60c0eda3e34cd32ed9337

data/lib/async/task.rb

@@ -38,6 +38,25 @@ module Async
 	end
 	
 	# Encapsulates the state of a running task and it's result.
+	#
+	# ```mermaid
+	# stateDiagram-v2
+	# [*] --> Initialized
+	# Initialized --> Running : Run
+	# 
+	# Running --> Completed : Return Value
+	# Running --> Failed : Exception
+	# 
+	# Completed --> [*]
+	# Failed --> [*]
+	# 
+	# Running --> Stopped : Stop
+	# Stopped --> [*]
+	# Completed --> Stopped : Stop
+	# Failed --> Stopped : Stop
+	# Initialized --> Stopped : Stop
+	# ```
+	#
 	# @public Since `stable-v1`.
 	class Task < Node
 		# @deprecated With no replacement.
@@ -51,22 +70,24 @@ module Async
 		def initialize(parent = Task.current?, finished: nil, **options, &block)
 			super(parent, **options)
 			
+			# These instance variables are critical to the state of the task.
+			# In the initialized state, the @block should be set, but the @fiber should be nil.
+			# In the running state, the @fiber should be set.
+			# In a finished state, the @block should be nil, and the @fiber should be nil.
+			@block = block
+			@fiber = nil
+			
 			@status = :initialized
 			@result = nil
 			@finished = finished
-			
-			@block = block
-			@fiber = nil
 		end
 		
 		def reactor
 			self.root
 		end
 		
-		if Fiber.current.respond_to?(:backtrace)
-			def backtrace(*arguments)
-				@fiber&.backtrace(*arguments)
-			end
+		def backtrace(*arguments)
+			@fiber&.backtrace(*arguments)
 		end
 		
 		def to_s
@@ -91,10 +112,40 @@ module Async
 		# @attr fiber [Fiber] The fiber which is being used for the execution of this task.
 		attr :fiber
 		
+		# Whether the internal fiber is alive, i.e. it 
 		def alive?
 			@fiber&.alive?
 		end
 		
+		# Whether we can remove this node from the reactor graph.
+		# @returns [Boolean]
+		def finished?
+			# If the block is nil and the fiber is nil, it means the task has finished execution. This becomes true after `finish!` is called.
+			super && @block.nil? && @fiber.nil?
+		end
+		
+		# Whether the task is running.
+		# @returns [Boolean]
+		def running?
+			@status == :running
+		end
+		
+		def failed?
+			@status == :failed
+		end
+		
+		# The task has been stopped
+		def stopped?
+			@status == :stopped
+		end
+		
+		# The task has completed execution and generated a result.
+		def completed?
+			@status == :completed
+		end
+		
+		alias complete? completed?
+		
 		# @attr status [Symbol] The status of the execution of the fiber, one of `:initialized`, `:running`, `:complete`, `:stopped` or `:failed`.
 		attr :status
 		
@@ -131,7 +182,8 @@ module Async
 		def wait
 			raise "Cannot wait on own fiber!" if Fiber.current.equal?(@fiber)
 			
-			if running?
+			# `finish!` will set both of these to nil before signaling the condition:
+			if @block || @fiber
 				@finished ||= Condition.new
 				@finished.wait
 			end
@@ -153,17 +205,22 @@ module Async
 				return
 			end
 			
-			if self.running?
+			# If the fiber is alive, we need to stop it:
+			if @fiber&.alive?
 				if self.current?
 					if later
+						# If the fiber is the current fiber and we want to stop it later, schedule it:
 						Fiber.scheduler.push(Stop::Later.new(self))
 					else
+						# Otherwise, raise the exception directly:
 						raise Stop, "Stopping current task!"
 					end
-				elsif @fiber&.alive?
+				else
+					# If the fiber is not curent, we can raise the exception directly:
 					begin
 						Fiber.scheduler.raise(@fiber, Stop)
 					rescue FiberError
+						# In some cases, this can cause a FiberError (it might be resumed already), so we schedule it to be stopped later:
 						Fiber.scheduler.push(Stop::Later.new(self))
 					end
 				end
@@ -190,36 +247,34 @@ module Async
 			self.equal?(Thread.current[:async_task])
 		end
 		
-		# Check if the task is running.
-		# @returns [Boolean]
-		def running?
-			@status == :running
-		end
-		
-		# Whether we can remove this node from the reactor graph.
-		# @returns [Boolean]
-		def finished?
-			super && @fiber.nil?
-		end
-		
-		def failed?
-			@status == :failed
-		end
+		private
 		
-		def stopped?
-			@status == :stopped
+		# Finish the current task, moving any children to the parent.
+		def finish!
+			# Don't hold references to the fiber or block after the task has finished:
+			@fiber = nil
+			@block = nil # If some how we went directly from initialized to finished.
+			
+			# Attempt to remove this node from the task tree.
+			consume
+			
+			# If this task was being used as a future, signal completion here:
+			if @finished
+				@finished.signal(self)
+				@finished = nil
+			end
 		end
 		
-		def complete?
-			@status == :complete
+		# State transition into the completed state.
+		def completed!(result)
+			@result = result
+			@status = :completed
 		end
 		
-		private
-		
 		# This is a very tricky aspect of tasks to get right. I've modelled it after `Thread` but it's slightly different in that the exception can propagate back up through the reactor. If the user writes code which raises an exception, that exception should always be visible, i.e. cause a failure. If it's not visible, such code fails silently and can be very difficult to debug.
-		def fail!(exception = false, propagate = true)
-			@status = :failed
+		def failed!(exception = false, propagate = true)
 			@result = exception
+			@status = :failed
 			
 			if exception
 				if propagate
@@ -233,27 +288,33 @@ module Async
 			end
 		end
 		
-		def stop!
+		def stopped!
 			# Console.logger.info(self, self.annotation) {"Task was stopped with #{@children&.size.inspect} children!"}
 			@status = :stopped
 			
+			# We are not running, but children might be so we should stop them:
 			stop_children(true)
 		end
 		
+		def stop!
+			stopped!
+			
+			finish!
+		end
+		
 		def schedule(&block)
 			@fiber = Fiber.new do
 				set!
 				
 				begin
-					@result = yield
-					@status = :complete
+					completed!(yield)
 					# Console.logger.debug(self) {"Task was completed with #{@children.size} children!"}
 				rescue Stop
-					stop!
+					stopped!
 				rescue StandardError => error
-					fail!(error, false)
+					failed!(error, false)
 				rescue Exception => exception
-					fail!(exception, true)
+					failed!(exception, true)
 				ensure
 					# Console.logger.info(self) {"Task ensure $! = #{$!} with #{@children&.size.inspect} children!"}
 					finish!
@@ -263,20 +324,6 @@ module Async
 			self.root.resume(@fiber)
 		end
 		
-		# Finish the current task, moving any children to the parent.
-		def finish!
-			# Allow the fiber to be recycled.
-			@fiber = nil
-			
-			# Attempt to remove this node from the task tree.
-			consume
-			
-			# If this task was being used as a future, signal completion here:
-			if @finished
-				@finished.signal(self)
-			end
-		end
-		
 		# Set the current fiber's `:async_task` to this task.
 		def set!
 			# This is actually fiber-local:

data/lib/async/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2017-2022, by Samuel Williams.
 
 module Async
-	VERSION = "2.4.2"
+	VERSION = "2.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.4.2
+  version: 2.5.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -56,7 +56,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2023-03-11 00:00:00.000000000 Z
+date: 2023-03-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: console
@@ -100,20 +100,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.1'
-- !ruby/object:Gem::Dependency
-  name: async-rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.1'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: bake-test
   requirement: !ruby/object:Gem::Requirement
@@ -261,7 +247,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.7
+rubygems_version: 3.4.6
 signing_key:
 specification_version: 4
 summary: A concurrency framework for Ruby.