Document child lifecycle APIs

Assisted-By: devx/a01026a8-dd63-4b91-bae4-aec7ee8f7fa3

Author: samuel-williams-shopify

lib/async/container/child.rb

@@ -10,11 +10,16 @@
 
 module Async
 	module Container
+		# Represents a child execution unit managed by a container.
 		class Child
 			# The default amount of time to wait for a child to be reaped after its
 			# notification channel closes.
 			REAP_TIMEOUT = 1.0
 
+			# Initialize the child with the given notification channel.
+			# @parameter channel [Channel] The channel used to receive child notifications.
+			# @parameter name [String | Nil] The optional child name.
+			# @parameter options [Hash] Additional child options.
 			def initialize(channel, name: nil, **options)
 				@channel = channel
 				@name = name
@@ -73,6 +78,11 @@ def stop(graceful = true, &block)
 				return status
 			end
 
+			# Receive notification messages from the child until a message is available, the channel closes, or the timeout expires.
+			# @parameter timeout [Numeric | Nil] The maximum time to wait for a message.
+			# @yields {|message| ...} Each received notification message.
+			# 	@parameter message [Hash] The notification message from the child.
+			# @returns [Hash | Boolean | Nil] The message, `false` on timeout, or `nil` when the channel closes.
 			def receive(timeout = nil, &block)
 				deadline = Deadline.new(timeout) if timeout
 

lib/async/container/forked.rb

@@ -10,10 +10,16 @@ module Async
 	module Container
 		# Public factory for multi-process containers.
 		module Forked
+			# Create a generic container which spawns forked children.
+			# @parameter arguments [Array] Positional arguments for {Generic#initialize}.
+			# @parameter options [Hash] Keyword options for {Generic#initialize}.
+			# @returns [Generic] A generic container configured with {Forked::Child}.
 			def self.new(*arguments, **options)
 				Generic.new(Child, *arguments, **options)
 			end
 
+			# Whether this container uses multiple processes.
+			# @returns [Boolean]
 			def self.multiprocess?
 				true
 			end

lib/async/container/forked/child.rb

@@ -9,7 +9,15 @@
 module Async
 	module Container
 		module Forked
+			# Represents a child process managed by a forked container.
 			class Child < Container::Child
+				# Start a child process using `fork`.
+				# @parameter channel [Channel] The notification channel for the child.
+				# @parameter name [String | Nil] The optional child name.
+				# @parameter options [Hash] Additional child options.
+				# @yields {|instance| ...} The child process body.
+				# 	@parameter instance [Instance] The child-side instance interface.
+				# @returns [Child] The forked child process.
 				def self.call(channel: Channel.new, name: nil, **options, &block)
 					process_id = ::Thread.new do
 						::Process.fork do
@@ -39,6 +47,10 @@ def self.call(channel: Channel.new, name: nil, **options, &block)
 					return self.new(process_id, channel, name: name, **options)
 				end
 
+				# Initialize the child process wrapper.
+				# @parameter process_id [Integer] The process identifier.
+				# @parameter channel [Channel] The notification channel for the child.
+				# @parameter options [Hash] Additional child options.
 				def initialize(process_id, channel, **options)
 					@process_id = process_id
 					@status = nil
@@ -78,6 +90,9 @@ def restart!
 					end
 				end
 
+				# Reap the child process.
+				# @parameter timeout [Numeric | Nil] The maximum time to wait for the process to exit.
+				# @returns [::Process::Status | Nil] The process status, or `nil` if the timeout expired.
 				def reap(timeout = nil)
 					unless @status
 						if timeout

lib/async/container/generic.rb

@@ -35,10 +35,18 @@ def self.processor_count(env = ENV)
 		class Generic
 			UNNAMED = "Unnamed"
 
+			# Create and run a generic container.
+			# @parameter arguments [Array] Positional arguments for {#run}.
+			# @parameter options [Hash] Keyword options for {#run}.
+			# @returns [Generic] The running container.
 			def self.run(...)
 				self.new.run(...)
 			end
 
+			# Initialize the generic container.
+			# @parameter child_type [Class] The child type used to spawn children.
+			# @parameter policy [Policy] The policy for managing child lifecycle events.
+			# @parameter options [Hash] Additional group options.
 			def initialize(child_type, policy: Policy::DEFAULT, **options)
 				@child_type = child_type
 				@group = Group.new(**options)

lib/async/container/group.rb

@@ -19,6 +19,7 @@ class Group
 			# Emitted when a child exits the group.
 			Exit = Data.define(:child, :status)
 
+			# Initialize the group.
 			def initialize
 				@children = Set.new
 				@events = Thread::Queue.new

lib/async/container/hybrid.rb

@@ -8,11 +8,24 @@
 
 module Async
 	module Container
+		# Represents a container which spawns forked processes that manage threaded children.
 		class Hybrid < Generic
+			# Initialize the hybrid container.
+			# @parameter arguments [Array] Positional arguments for {Generic#initialize}.
+			# @parameter options [Hash] Keyword options for {Generic#initialize}.
 			def initialize(*arguments, **options)
 				super(Forked::Child, *arguments, **options)
 			end
 
+			# Spawn forked containers, each managing a set of threaded children.
+			# @parameter count [Integer | Nil] The total number of threaded children.
+			# @parameter forks [Integer | Nil] The number of forked child containers.
+			# @parameter threads [Integer | Nil] The number of threads per fork.
+			# @parameter health_check_timeout [Numeric | Nil] The timeout for child health checks.
+			# @parameter options [Hash] Additional child options.
+			# @yields {|instance| ...} The threaded child body.
+			# 	@parameter instance [Threaded::Instance] The child-side instance interface.
+			# @returns [Hybrid] The hybrid container.
 			def run(count: nil, forks: nil, threads: nil, health_check_timeout: nil, **options, &block)
 				processor_count = Async::Container.processor_count
 				count ||= processor_count ** 2
@@ -42,6 +55,8 @@ def run(count: nil, forks: nil, threads: nil, health_check_timeout: nil, **optio
 				return self
 			end
 
+			# Whether this container uses multiple processes.
+			# @returns [Boolean]
 			def self.multiprocess?
 				true
 			end

lib/async/container/threaded.rb

@@ -10,10 +10,16 @@ module Async
 	module Container
 		# Public factory for multi-thread containers.
 		module Threaded
+			# Create a generic container which spawns threaded children.
+			# @parameter arguments [Array] Positional arguments for {Generic#initialize}.
+			# @parameter options [Hash] Keyword options for {Generic#initialize}.
+			# @returns [Generic] A generic container configured with {Threaded::Child}.
 			def self.new(*arguments, **options)
 				Generic.new(Child, *arguments, **options)
 			end
 
+			# Whether this container uses multiple processes.
+			# @returns [Boolean]
 			def self.multiprocess?
 				false
 			end

lib/async/container/threaded/child.rb

@@ -9,7 +9,15 @@
 module Async
 	module Container
 		module Threaded
+			# Represents a child thread managed by a threaded container.
 			class Child < Container::Child
+				# Start a child thread.
+				# @parameter channel [Channel] The notification channel for the child.
+				# @parameter name [String | Nil] The optional child name.
+				# @parameter options [Hash] Additional child options.
+				# @yields {|instance| ...} The child thread body.
+				# 	@parameter instance [Instance] The child-side instance interface.
+				# @returns [Child] The threaded child.
 				def self.call(channel: Channel.new, name: nil, **options, &block)
 					thread = ::Thread.new do
 						begin
@@ -32,6 +40,10 @@ def self.call(channel: Channel.new, name: nil, **options, &block)
 					return self.new(thread, channel, name: name, **options)
 				end
 
+				# Initialize the child thread wrapper.
+				# @parameter thread [Thread] The child thread.
+				# @parameter channel [Channel] The notification channel for the child.
+				# @parameter options [Hash] Additional child options.
 				def initialize(thread, channel, **options)
 					@thread = thread
 					@status = nil
@@ -61,6 +73,9 @@ def restart!
 					@thread.raise(Restart)
 				end
 
+				# Reap the child thread.
+				# @parameter timeout [Numeric | Nil] The maximum time to wait for the thread to exit.
+				# @returns [Status | Nil] The thread status, or `nil` if the timeout expired.
 				def reap(timeout = nil)
 					if timeout
 						return nil unless @thread.join(timeout)