socketry
diff --git a/‎guides/asynchronous-tasks/readme.md
Lines changed: 34 additions & 30 deletions b/‎guides/asynchronous-tasks/readme.md
Lines changed: 34 additions & 30 deletions
@@ -4,7 +4,7 @@ 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 stopping a parent task, it will also stop all it's children tasks. The 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 event loop generally has one root task.
 
 ```mermaid
 graph LR
@@ -39,15 +39,15 @@ 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, fail 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 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}.
 
 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.
 3. In the case the task was stopped, the result will be `nil`.
 
 ## Starting A Task
 
-At any point in your program, you can start a task using the {ruby Kernel::Async} method:
+At any point in your program, you can start the reactor and a root task using the {ruby Kernel::Async} method:
 
 ```ruby
 Async do
@@ -100,7 +100,7 @@ end
 
 ### Performance Considerations
 
-Task creation and execution has been heavily optimised. Do not trade program complexity to avoid creating tasks, the cost will almost never be useful.
+Task creation and execution has been heavily optimised. Do not trade program complexity to avoid creating tasks; the cost will almost always exceed the gain.
 
 Do consider using correct concurrency primatives like {ruby Async::Semaphore}, {ruby Async::Barrier}, etc, to ensure your program is well-behaved in the presence of large inputs (i.e. don't create an unbounded number of tasks).
 
@@ -124,7 +124,7 @@ end
 
 ## Waiting for Tasks
 
-Waiting for a single task is trivial, simply invoke {ruby Async::Task#wait}. To wait for multiple tasks, you may want to use a {ruby Async::Barrier}. You can use {ruby Async::Barrier#async} to create multiple child tasks, and wait for them all to complete using {ruby Async::Barrier#wait}.
+Waiting for a single task is trivial: simply invoke {ruby Async::Task#wait}. To wait for multiple tasks, you may either {ruby Async::Task#wait} on each in turn, or you may want to use a {ruby Async::Barrier}. You can use {ruby Async::Barrier#async} to create multiple child tasks, and wait for them all to complete using {ruby Async::Barrier#wait}.
 
 ```ruby
 barrier = Async::Barrier.new
@@ -183,9 +183,9 @@ barrier.wait
 
 ## Stopping a Task
 
-When a task completes execution, it will enter
+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}). 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, 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.
 
 Using the above program as an example, we can 
 
@@ -205,7 +205,7 @@ end
 
 ### Stopping all Tasks held in a Barrier
 
-To stop (terminate/cancel) the all tasks held in a barrier:
+To stop (terminate/cancel) all the tasks held in a barrier:
 
 ```ruby
 barrier = Async::Barrier.new
@@ -222,7 +222,7 @@ Async do
 end
 ```
 
-If you're letting individual tasks held by a barrier
8000
 throw unhandled exceptions, be sure to call ({ruby Async::Barrier#stop}):
+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:
 
 ```ruby
 barrier = Async::Barrier.new
@@ -300,57 +300,59 @@ end
 
 ## Timeouts
 
-You can wrap asynchronous operations in a timeout. This ensures that malicious services don't cause your code to block indefinitely.
+You can wrap asynchronous operations in a timeout. This allows you to put an upper bound on how long the enclosed code will run vs. potentially blocking indefinitely. If the enclosed code hasn't completed by the timeout, it will be interrupted with an {ruby Async::TimeoutError} exception.
 
 ~~~ ruby
 require 'async'
 
 Async do |task|
 	task.with_timeout(1) do
-		task.sleep 100
+		sleep 100
 	rescue Async::TimeoutError
-		puts "I timed out!"
+		puts "I timed out 99 seconds early!"
 	end
 end
 ~~~
 
-### Reoccurring Timers
+### Periodic Timers
 
-Sometimes you need to do some periodic work in a loop.
+Sometimes you need to do some recurring work in a loop. Often it's best to measure the periodic delay end-to-start, so that your process always takes a break between iterations and doesn't risk spending 100% of its time on the periodic work. In this case, simply call {ruby sleep} between iterations:
 
 ~~~ ruby
 require 'async'
 
 Async do |task|
-	while true
+	loop do
 		puts Time.now
-		task.sleep 1
+		# ... process job ...
+		sleep 1
 	end
 end
 ~~~
 
 ## Reactor Lifecycle
 
-Generally, the event loop will not exit until all tasks complete. This is informed by {ruby Async::Task#finished?} which checks if the current node has completed execution, which also includes all children. However, there is one exception to this rule: tasks flagged as being transient ({ruby Async::Node#transient?}).
+Generally, the outer reactor will not exit until all tasks complete. This is informed by {ruby Async::Task#finished?} which checks if the current node has completed execution, which also includes all children. However, there is one exception to this rule: tasks flagged as being `transient` ({ruby Async::Node#transient?}).
 
 ### Transient Tasks
 
-Tasks which are flagged as transient, do not behave like normal tasks.
+Tasks which are flagged as `transient` do not behave like normal tasks.
 
 ```ruby
 @pruner = Async(transient: true) do
-	while true
+	loop do
+	
 		sleep 1
 		prune_connection_pool
 	end
 end
 ```
 
-1. They will not keep the reactor alive, and instead are stopped (with a {ruby Async::Stop} exception) when all other (non-transient) tasks are finished.
-2. If the parent task is finished, any transient tasks will become children of the parent's parent, i.e. they don't keep sub-trees alive.
-3. If you stop a task which has transient children, those transient children will not be stopped and will instead move up the tree.
+1. They are not considered by {ruby Async::Task#finished?}, so they will not keep the reactor alive. Instead, they are stopped (with a {ruby Async::Stop} exception) when all other (non-transient) tasks are finished.
+2. As soon as a parent task is finished, any transient child tasks will be moved up to be children of the parent's parent. This ensures that they never keep a sub-tree alive.
+3. Similarly, if you `stop` a task, any transient child tasks will be moved up the tree as above rather than being stopped.
 
-The purpose of transient tasks is when a task is an implementation detail of an object or instance, rather than a concurrency process. Some examples of trasient tasks 
+The purpose of transient tasks is when a task is an implementation detail of an object or instance, rather than a concurrency process. Some examples of transient tasks:
 
 - A task which is reading or writing data on behalf of a stateful connection object, e.g. HTTP/2 frame reader, Redis cache invalidation, etc.
 - A task which is monitoring and maintaining a connection pool, pruning unused connections or possibly ensuring those connections are periodically checked for activity (ping/pong, etc).
@@ -364,21 +366,23 @@ require 'async'
 require 'thread/local' # thread-local gem.
 
 class TimeCache
-	extend Thread::Local
+	extend Thread::Local # defines `instance` class method that lazy-creates a separate instance per thread
 
 	def initialize
 		@current_time = nil
 	end
 
-	def current_time
+	def current_time_string
 		refresh!
 
 		return @current_time
 	end
 
-	private def refresh!
+	private
+	
+	def refresh!
 		@refresh ||= Async(transient: true) do
-			while true
+			loop do
 				@current_time = Time.now.to_s
 				sleep(1)
 			end
@@ -390,9 +394,9 @@ class TimeCache
 end
 
 Async do
-	# If you are handling 1000s of requests per second, it can be an advantage to cache the current time as a string.
-	p TimeCache.instance.current_time
+	# 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
 end
 ```
 
-Upon existing the top level async block, the {ruby @refresh} task will be set to `nil`. Bear in mind, you should not share these resources across threads, doing so would need further locking/coordination.
+Upon existing the top level async block, the {ruby @refresh} task will be set to `nil`. Bear in mind, you should not share these resources across threads; doing so would need some form of mutual exclusion.