100% documentation coverage.

Author: ioquatix

lib/async/container.rb

@@ -5,7 +5,9 @@
 
 require_relative "container/controller"
 
+# @namespace
 module Async
+	# @namespace
 	module Container
 	end
 end

lib/async/container/error.rb

@@ -5,6 +5,7 @@
 
 module Async
 	module Container
+		# Represents an error that occured during container execution.
 		class Error < StandardError
 		end
 
@@ -13,29 +14,35 @@ class Error < StandardError
 		# Similar to {Interrupt}, but represents `SIGTERM`.
 		class Terminate < SignalException
 			SIGTERM = Signal.list["TERM"]
-
+			
+			# Create a new terminate error.
 			def initialize
 				super(SIGTERM)
 			end
 		end
 
+		# Similar to {Interrupt}, but represents `SIGHUP`.
 		class Restart < SignalException
 			SIGHUP = Signal.list["HUP"]
 
+			# Create a new restart error.
 			def initialize
 				super(SIGHUP)
 			end
 		end
 
 		# Represents the error which occured when a container failed to start up correctly.
 		class SetupError < Error
+			# Create a new setup error.
+			#
+			# @parameter container [Generic] The container that failed.
 			def initialize(container)
 				super("Could not create container!")
 
 				@container = container
 			end
 
-			# The container that failed.
+			# @attribute [Generic] The container that failed.
 			attr :container
 		end
 	end

lib/async/container/forked.rb

@@ -35,24 +35,34 @@ def self.for(process)
 						return instance
 					end
 
+					# Initialize the child process instance.
+					#
+					# @parameter io [IO] The IO object to use for communication.
 					def initialize(io)
 						super
 
 						@name = nil
 					end
 
+					# Generate a hash representation of the process.
+					#
+					# @returns [Hash] The process as a hash, including `process_id` and `name`.
 					def as_json(...)
 						{
 							process_id: ::Process.pid,
 							name: @name,
 						}
 					end
 
+					# Generate a JSON representation of the process.
+					#
+					# @returns [String] The process as JSON.
 					def to_json(...)
 						as_json.to_json(...)
 					end
 
 					# Set the process title to the specified value.
+					#
 					# @parameter value [String] The name of the process.
 					def name= value
 						@name = value
@@ -61,14 +71,17 @@ def name= value
 						::Process.setproctitle(@name.to_s)
 					end
 
-					# The name of the process.
-					# @returns [String]
+					# @returns [String] The name of the process.
 					def name
 						@name
 					end
 
 					# Replace the current child process with a different one. Forwards arguments and options to {::Process.exec}.
 					# This method replaces the child process with the new executable, thus this method never returns.
+					#
+					# @parameter arguments [Array] The arguments to pass to the new process.
+					# @parameter ready [Boolean] If true, informs the parent process that the child is ready. Otherwise, the child process will need to use a notification protocol to inform the parent process that it is ready.
+					# @parameter options [Hash] Additional options to pass to {::Process.exec}.
 					def exec(*arguments, ready: true, **options)
 						if ready
 							self.ready!(status: "(exec)")
@@ -81,6 +94,7 @@ def exec(*arguments, ready: true, **options)
 				end
 
 				# Fork a child process appropriate for a container.
+				#
 				# @returns [Process]
 				def self.fork(**options)
 					# $stderr.puts fork: caller
@@ -105,6 +119,13 @@ def self.fork(**options)
 					end
 				end
 
+				# Spawn a child process using {::Process.spawn}.
+				#
+				# The child process will need to inform the parent process that it is ready using a notification protocol.
+				#
+				# @parameter arguments [Array] The arguments to pass to the new process.
+				# @parameter name [String] The name of the process.
+				# @parameter options [Hash] Additional options to pass to {::Process.spawn}.
 				def self.spawn(*arguments, name: nil, **options)
 					self.new(name: name) do |process|
 						Notify::Pipe.new(process.out).before_spawn(arguments, options)

lib/async/container/generic.rb

@@ -32,12 +32,16 @@ def self.processor_count(env = ENV)
 
 		# A base class for implementing containers.
 		class Generic
-			def self.run(*arguments, **options, &block)
-				self.new.run(*arguments, **options, &block)
+			# Run a new container.
+			def self.run(...)
+				self.new.run(...)
 			end
 
 			UNNAMED = "Unnamed"
 
+			# Initialize the container.
+			#
+			# @parameter options [Hash] Options passed to the {Group} instance.
 			def initialize(**options)
 				@group = Group.new(**options)
 				@running = true

lib/async/container/group.rb

@@ -25,6 +25,7 @@ def initialize(health_check_interval: 1.0)
 				@queue = nil
 			end
 
+			# @returns [String] A human-readable representation of the group.
 			def inspect
 				"#<#{self.class} running=#{@running.size}>"
 			end

lib/async/container/keyed.rb

@@ -8,22 +8,23 @@ module Container
 		# Tracks a key/value pair such that unmarked keys can be identified and cleaned up.
 		# This helps implement persistent processes that start up child processes per directory or configuration file. If those directories and/or configuration files are removed, the child process can then be cleaned up automatically, because those key/value pairs will not be marked when reloading the container.
 		class Keyed
+			# Initialize the keyed instance
+			#
+			# @parameter key [Object] The key.
+			# @parameter value [Object] The value.
 			def initialize(key, value)
 				@key = key
 				@value = value
 				@marked = true
 			end
 
-			# The key. Normally a symbol or a file-system path.
-			# @attribute [Object]
+			# @attribute [Object] The key value, normally a symbol or a file-system path.
 			attr :key
 
-			# The value. Normally a child instance of some sort.
-			# @attribute [Object]
+			# @attribute [Object] The value, normally a child instance.
 			attr :value
 
-			# Has the instance been marked?
-			# @returns [Boolean]
+			# @returns [Boolean] True if the instance has been marked, during reloading the container.
 			def marked?
 				@marked
 			end
@@ -39,6 +40,8 @@ def clear!
 			end
 
 			# Stop the instance if it was not marked.
+			#
+			# @returns [Boolean] True if the instance was stopped.
 			def stop?
 				unless @marked
 					@value.stop

lib/async/container/notify/client.rb

@@ -7,6 +7,9 @@ module Async
 	module Container
 		# Handles the details of several process readiness protocols.
 		module Notify
+			# Represents a client that can send messages to the parent controller in order to notify it of readiness, status changes, etc.
+			#
+			# A process readiness protocol (e.g. `sd_notify`) is a simple protocol for a child process to notify the parent process that it is ready (e.g. to accept connections, to process requests, etc). This can help dependency-based startup systems to start services in the correct order, and to handle failures gracefully.
 			class Client
 				# Notify the parent controller that the child has become ready, with a brief status message.
 				# @parameters message [Hash] Additional details to send with the message.

lib/async/container/notify/log.rb

@@ -9,6 +9,7 @@
 module Async
 	module Container
 		module Notify
+			# Represents a client that uses a local log file to communicate readiness, status changes, etc.
 			class Log < Client
 				# The name of the environment variable which contains the path to the notification socket.
 				NOTIFY_LOG = "NOTIFY_LOG"

lib/async/container/notify/server.rb

@@ -11,9 +11,14 @@
 module Async
 	module Container
 		module Notify
+			# A simple UDP server that can be used to receive messages from a child process, tracking readiness, status changes, etc.
 			class Server
 				MAXIMUM_MESSAGE_SIZE = 4096
 
+				# Parse a message, according to the `sd_notify` protocol.
+				#
+				# @parameter message [String] The message to parse.
+				# @returns [Hash] The parsed message.
 				def self.load(message)
 					lines = message.split("\n")
 
@@ -38,41 +43,60 @@ def self.load(message)
 					return Hash[pairs]
 				end
 
+				# Generate a new unique path for the UNIX socket.
+				#
+				# @returns [String] The path for the UNIX socket.
 				def self.generate_path
 					File.expand_path(
 						"async-container-#{::Process.pid}-#{SecureRandom.hex(8)}.ipc",
 						Dir.tmpdir
 					)
 				end
 
+				# Open a new server instance with a temporary and unique path.
 				def self.open(path = self.generate_path)
 					self.new(path)
 				end
 
+				# Initialize the server with the given path.
+				#
+				# @parameter path [String] The path to the UNIX socket.
 				def initialize(path)
 					@path = path
 				end
 
+				# @attribute [String] The path to the UNIX socket.
 				attr :path
 
+				# Generate a bound context for receiving messages.
+				#
+				# @returns [Context] The bound context.
 				def bind
 					Context.new(@path)
 				end
 
+				# A bound context for receiving messages.
 				class Context
+					# Initialize the context with the given path.
+					#
+					# @parameter path [String] The path to the UNIX socket.
 					def initialize(path)
 						@path = path
 						@bound = Addrinfo.unix(@path, ::Socket::SOCK_DGRAM).bind
 
 						@state = {}
 					end
 
+					# Close the bound context.
 					def close
 						@bound.close
 
 						File.unlink(@path)
 					end
 
+					# Receive a message from the bound context.
+					#
+					# @returns [Hash] The parsed message.
 					def receive
 						while true
 							data, _address, _flags, *_controls = @bound.recvmsg(MAXIMUM_MESSAGE_SIZE)

lib/async/container/statistics.rb

@@ -9,6 +9,7 @@ module Async
 	module Container
 		# Tracks various statistics relating to child instances in a container.
 		class Statistics
+			# Initialize the statistics all to 0.
 			def initialize
 				@spawns = 0
 				@restarts = 0

lib/async/container/threaded.rb

@@ -11,9 +11,6 @@ module Async
 	module Container
 		# A multi-thread container which uses {Thread.fork}.
 		class Threaded < Generic
-			class Kill < Exception
-			end
-			
 			# Indicates that this is not a multi-process container.
 			def self.multiprocess?
 				false
@@ -52,12 +49,18 @@ def self.for(thread)
 						return instance
 					end
 
+					# Initialize the child thread instance.
+					#
+					# @parameter io [IO] The IO object to use for communication with the parent.
 					def initialize(io)
 						@thread = ::Thread.current
 
 						super
 					end
 
+					# Generate a hash representation of the thread.
+					#
+					# @returns [Hash] The thread as a hash, including `process_id`, `thread_id`, and `name`.
 					def as_json(...)
 						{
 							process_id: ::Process.pid,
@@ -66,6 +69,9 @@ def as_json(...)
 						}
 					end
 
+					# Generate a JSON representation of the thread.
+					#
+					# @returns [String] The thread as JSON.
 					def to_json(...)
 						as_json.to_json(...)
 					end
@@ -101,6 +107,9 @@ def exec(*arguments, ready: true, **options)
 					end
 				end
 
+				# Start a new child thread and execute the provided block in it.
+				#
+				# @parameter options [Hash] Additional options to to the new child instance.
 				def self.fork(**options)
 					self.new(**options) do |thread|
 						::Thread.new do
@@ -113,6 +122,7 @@ def self.fork(**options)
 				end
 
 				# Initialize the thread.
+				#
 				# @parameter name [String] The name to use for the child thread.
 				def initialize(name: nil)
 					super()
@@ -230,6 +240,9 @@ def success?
 						@error.nil?
 					end
 
+					# Convert the status to a hash, suitable for serialization.
+					#
+					# @returns [Boolean | String] If the status is an error, the error message is returned, otherwise `true`.
 					def as_json(...)
 						if @error
 							@error.inspect