From 395a7d1c10e0508d10ef61b0428f683b2c4022ef Mon Sep 17 00:00:00 2001
From: Samuel Williams <samuel.williams@oriontransfer.co.nz>
Date: Fri, 22 Nov 2024 20:32:03 +1300
Subject: [PATCH] Documentation.

---
 lib/async/work_pool.rb | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/lib/async/work_pool.rb b/lib/async/work_pool.rb
index b2b77ed..fae8af4 100644
--- a/lib/async/work_pool.rb
+++ b/lib/async/work_pool.rb
@@ -6,8 +6,15 @@
 require "etc"
 
 module Async
+	# A simple work pool that offloads work to a background thread.
 	class WorkPool
+		# A handle to the work being done.
 		class Handle
+			# Create a new handle.
+			#
+			# @parameter scheduler [Async::Scheduler] The scheduler that is managing the fiber.
+			# @parameter fiber [Async::Fiber] The fiber that is waiting for the work to complete.
+			# @parameter work [Proc] The work to be done.
 			def initialize(scheduler, fiber, work)
 				@scheduler = scheduler
 				@fiber = fiber
@@ -20,6 +27,7 @@ def initialize(scheduler, fiber, work)
 				@error = nil
 			end
 			
+			# Call the work and notify the scheduler when it is done.
 			def call
 				@thread = ::Thread.current
 				
@@ -35,6 +43,7 @@ def call
 				end
 			end
 			
+			# Wait for the work to complete.
 			def wait
 				@scheduler.block(self, nil)
 				
@@ -45,6 +54,7 @@ def wait
 				end
 			end
 			
+			# Cancel the work.
 			def cancel!
 				@work = nil
 				@fiber = nil # Don't call unblock.
@@ -52,6 +62,9 @@ def cancel!
 			end
 		end
 		
+		# Create a new work pool.
+		#
+		# @parameter size [Integer] The number of threads to use.
 		def initialize(size: Etc.nprocessors)
 			@queue = ::Thread::Queue.new
 			
@@ -60,6 +73,7 @@ def initialize(size: Etc.nprocessors)
 			end
 		end
 		
+		# Close the work pool. Kills all outstanding work.
 		def close
 			@queue.close
 			
@@ -68,6 +82,9 @@ def close
 			end
 		end
 		
+		# Offload work to a thread.
+		#
+		# @parameter work [Proc] The work to be done.
 		def call(work)
 			handle = Handle.new(::Fiber.scheduler, ::Fiber.current, work)