socketry
diff --git a/‎guides/asynchronous-tasks/readme.md
Lines changed: 55 additions & 31 deletions b/‎guides/asynchronous-tasks/readme.md
Lines changed: 55 additions & 31 deletions
@@ -4,11 +4,11 @@ This guide explains how asynchronous tasks work and how to use them.
 
 ## Overview
 
-Tasks are the smallest unit of sequential code execution in {ruby Async}. Tasks can create other tasks, and Async tracks the parent-child relationship between tasks. When a parent task is stopped, it will also stop all its children tasks. The outer event loop generally has one root task.
+Tasks are the smallest unit of sequential code execution in {ruby Async}. Tasks can create other tasks, and Async tracks the parent-child relationship between tasks. When a parent task is stopped, it will also stop all its children tasks. The outer reactor (event loop) always starts with one root task.
 
 ```mermaid
 graph LR
-    EL[Event Loop] --> WS
+    REL[Reactor Event Loop] --> WS
     WS[Web Server Task] --> R1[Request 1 Task]
     WS --> R2[Request 2 Task]
 
@@ -28,7 +28,7 @@ stateDiagram-v2
     [*] --> initialized : Task.new
     initialized --> running : run
     
-    running --> failed : unhandled exception
+    running --> failed : unhandled StandardError-derived exception
     running --> complete : user code finished
     running --> stopped : stop
 
@@ -39,10 +39,10 @@ stateDiagram-v2
     stopped --> [*]
 ```
 
-Tasks are created in the `initialized` state, and are run by the event loop. During the execution, a task can either `complete` successfully, become `failed` with an unhandled exception, or be explicitly `stopped`. In all of these cases, you can wait for a task to complete by using {ruby Async::Task#wait}.
+Tasks are created in the `initialized` state, and are run by the reactor. During the execution, a task can either `complete` successfully, become `failed` with an unhandled `StandardError`-derived exception, or be explicitly `stopped`. In all of these cases, you can wait for a task to complete by using {ruby Async::Task#wait}.
 
 1. In the case the task successfully completed, the result will be whatever value was generated by the last expression in the task.
-2. In the case the task failed with an unhandled exception, waiting on the task will re-raise the exception.
+2. In the case the task failed with an unhandled `StandardError`-derived exception, waiting on the task will re-raise the exception.
 3. In the case the task was stopped, the result will be `nil`.
 
 ## Starting A Task
@@ -52,32 +52,32 @@ At any point in your program, you can start the reactor and a root task using th
 ```ruby
 Async do
 	3.times do |i|
-		sleep 1
+		sleep(i)
 		puts "Hello World #{i}"
 	end
 end
 ```
 
-This program prints "Hello World" 3 times. Before printing, it sleeps for 1 second. The total execution time is 3 seconds because the program executes sequentially.
+This program prints "Hello World" 3 times. Before printing, it sleeps for 1, then 2, then 3 seconds. The total execution time is 6 seconds because the program executes sequentially.
 
 By using a nested task, we can ensure that each iteration of the loop creates a new task which runs concurrently.
 
 ```ruby
 Async do
 	3.times do |i|
 		Async do
-			sleep 1
+			sleep(i)
 			puts "Hello World #{i}"
 		end
 	end
 end
 ```
 
-Instead of taking 3 seconds, this program takes 1 second in total. The main loop executes rapidly creating 3 child tasks, and then each child task sleeps for 1 second before printing "Hello World".
+Instead of taking 6 seconds, this program takes 3 seconds in total. The main loop executes rapidly creating 3 child tasks, and then each child task sleeps for 1, 2 and 3 seconds respectively before printing "Hello World".
 
 ```mermaid
 graph LR
-	EL[Event Loop] --> TT[Initial Task]
+	REL[Reactor Event Loop] --> TT[Initial Task]
 	
 	TT --> H0[Hello World 0 Task]
 	TT --> H1[Hello World 1 Task]
@@ -185,19 +185,19 @@ barrier.wait
 
 When a task completes execution, it will enter the `complete` state (or the `failed` state if it raises an unhandled exception).
 
-There are various situations where you may want to stop a task ({ruby Async::Task#stop}) before it completes. The most common case is shutting down a server, but other important situations exist, e.g. you may fan out multiple (10s, 100s) of requests, wait for a subset to complete (e.g. the first 5 or all those that complete within a given deadline), and then stop (terminate/cancel) the remaining operations.
+There are various situations where you may want to stop a task ({ruby Async::Task#stop}) before it completes. The most common case is shutting down a server. A more complex example is this: you may fan out multiple (10s, 100s) of requests, wait for a subset to complete (e.g. the first 5 or all those that complete within a given deadline), and then stop (terminate/cancel) the remaining operations.
 
-Using the above program as an example, we can 
+Using the above program as an example, let's stop all the tasks just after the first one completes.
 
 ```ruby
 Async do
 	tasks = 3.times.map do |i|
 		Async do
-			sleep 1
+			sleep(i)
 			puts "Hello World #{i}"
 		end
 	end
-	
+
 	# Stop all the above tasks:
 	tasks.each(&:stop)
 end
@@ -213,7 +213,7 @@ barrier = Async::Barrier.new
 Async do
 	tasks = 3.times.map do |i|
 		barrier.async do
-			sleep 1
+			sleep(i)
 			puts "Hello World #{i}"
 		end
 	end
@@ -222,15 +222,15 @@ Async do
 end
 ```
 
-If you're letting individual tasks held by a barrier raise unhandled exceptions, be sure to call ({ruby Async::Barrier#stop}) to stop the remaining tasks:
+Unless your tasks all rescue and suppresses `StandardError`-derived exceptions, be sure to call ({ruby Async::Barrier#stop}) to stop the remaining tasks:
 
 ```ruby
 barrier = Async::Barrier.new
 
 Async do
 	tasks = 3.times.map do |i|
 		barrier.async do
-			sleep 1
+			sleep(i)
 			puts "Hello World #{i}"
 		end
 	end
@@ -264,7 +264,7 @@ As tasks run synchronously until they yield back to the reactor, you can guarant
 
 ## Exception Handling
 
-{ruby Async::Task} captures and logs exceptions. All unhandled exceptions will cause the enclosing task to enter the `:failed` state. Non-`StandardError` exceptions are re-raised immediately and will generally cause the reactor to fail. This ensures that exceptions will always be visible and cause the program to fail appropriately.
+{ruby Async::Task} captures and logs exceptions. All unhandled exceptions will cause the enclosing task to enter the `:failed` state. Non-`StandardError` exceptions are re-raised immediately and will cause the reactor to exit. This ensures that exceptions will always be visible and cause the program to fail appropriately.
 
 ~~~ ruby
 require 'async'
@@ -307,7 +307,7 @@ require 'async'
 
 Async do |task|
 	task.with_timeout(1) do
-		sleep 100
+		sleep(100)
 	rescue Async::TimeoutError
 		puts "I timed out 99 seconds early!"
 	end
@@ -321,11 +321,33 @@ Sometimes you need to do some recurring work in a loop. Often it's best to measu
 ~~~ ruby
 require 'async'
 
+period = 30
+
 Async do |task|
 	loop do
 		puts Time.now
 		# ... process job ...
-		sleep 1
+		sleep(period)
+	end
+end
+~~~
+
+If you need a periodic timer that runs start-to-start, you can keep track of the `run_next` time using the monotonic clock:
+
+~~~ ruby
+require 'async'
+
+period = 30
+
+Async do |task|
+  run_next = Async::Clock.now
+	loop do
+		run_next += period
+		puts Time.now
+		# ... process job ...
+		if (remaining = run_next - Async::Clock.now) > 0
+		  sleep(remaining)
+		end
 	end
 end
 ~~~
@@ -340,9 +362,8 @@ Tasks which are flagged as `transient` do not behave like normal tasks.
 
 ```ruby
 @pruner = Async(transient: true) do
-	loop do
-	
-		sleep 1
+	loop do	
+		sleep(1)
 		prune_connection_pool
 	end
 end
@@ -359,43 +380,46 @@ The purpose of transient tasks is when a task is an implementation detail of an
 - A background worker or batch processing job which is independent of any specific operation, and is lazily created.
 - A cache system which needs periodic expiration / revalidation of data/values.
 
-Bearing in mind, in all of the above cases, you may need to validate that the background task hasn't been stopped, e.g.
+Here is an example that keeps a cache of the current time string since that has only 1-second granularity
+and you could be handling 1000s of requests per second.
+The task doing the updating in the background is an implementation detail, so it is marked as `transient`.
 
 ```ruby
 require 'async'
 require 'thread/local' # thread-local gem.
 
-class TimeCache
+class TimeStringCache
 	extend Thread::Local # defines `instance` class method that lazy-creates a separate instance per thread
 
 	def initialize
-		@current_time = nil
+		@current_time_string = nil
 	end
 
 	def current_time_string
 		refresh!
 
-		return @current_time
+		return @current_time_string
 	end
 
 	private
 
 	def refresh!
 		@refresh ||= Async(transient: true) do
 			loop do
-				@current_time = Time.now.to_s
+				@current_time_string = Time.now.to_s
 				sleep(1)
 			end
 		ensure
-			# When the reactor terminates all tasks, this will be invoked:
+			# When the reactor terminates all tasks, `Async::Stop` will be raised from `sleep` and 
+			# this code will be invoked.
+			# By clearing `@refresh`, we ensure that the task will be recreated if needed again:
 			@refresh = nil
 		end
 	end
 end
 
 Async do
-	# If you are handling 1000s of requests per second, it can be an advantage to cache the current time string.
-	p TimeCache.instance.current_time_string
+	p TimeStringCache.instance.current_time_string
 end
 ```