async-service-supervisor 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb8f5a6980d5ea448b4e4ec8826590167195c4fc31c3d40d2ba3e79e118bc270
-  data.tar.gz: 47bf75e14cfb55cba7007b50cea7029151bd6c265ebf8d0547340b4e53b58a14
+  metadata.gz: 0bad9d9135d925d16cb121c2f935fa99006724d3eea22f8676fbb4c252ff3289
+  data.tar.gz: ef02370d8a829606dc0fc1f38f5e56aa152b79d777dd1968542bad4496e6f460
 SHA512:
-  metadata.gz: 02b8bb2dada453bc5b96f48ae2608cd655c5eb0cfe22568c9aacd68efe798fcc25a3c652d7cfe94cdcf144676c7aa5d4a12b92f3f91ba6d0d419a2154c296991
-  data.tar.gz: 547604201a8a872e1498773e3ef6e472ed5a4970b5781c9fd6638802095e732d23bf5049332a8bb9d1cfdab0699421d50a52abff2f3ecc701a1d2366c5acadb8
+  metadata.gz: 8278cc7549c4de12409bbe06bc4f99c9e14af56feb6c87fc5202d926c27b7df214a8426514da3cab1a4f048dabd184fb0673e484a2266701c9385cb602780cfb
+  data.tar.gz: fdefd78ec63d3afa48fd19204c1ea60fb6526389db774d0b93085a10076010345962c17b1d74e1c2097733ba10ddf5ad5131dee9e7cb6f065827f236392bf6ec

data/context/index.yaml

@@ -3,6 +3,8 @@
 ---
 description: A supervisor for managing multiple container processes.
 metadata:
+  bug_tracker_uri: https://github.com/socketry/async-service-supervisor/issues
+  changelog_uri: https://github.com/socketry/async-service-supervisor/blob/main/releases.md
   documentation_uri: https://socketry.github.io/async-service-supervisor/
   source_code_uri: https://github.com/socketry/async-service-supervisor.git
 files:

data/lib/async/service/supervisor/monitor.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2026, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "async/loop"
 

data/lib/async/service/supervisor/utilization_monitor.rb

@@ -3,8 +3,6 @@
 # Released under the MIT License.
 # Copyright, 2026, by Samuel Williams.
 
-require "set"
-
 require_relative "monitor"
 require "async/utilization"
 
@@ -16,178 +14,9 @@ module Async
 			# Uses shared memory to efficiently collect utilization metrics from workers
 			# and aggregates them by service name for monitoring and reporting.
 			class UtilizationMonitor < Monitor
-				# Allocates and manages shared memory segments for worker utilization data.
-				#
-				# Manages a shared memory file that workers can write utilization metrics to.
-				# Allocates segments to workers and maintains a free list for reuse.
-				# Each process (supervisor and workers) maps the shared memory file independently.
-				class SegmentAllocator
-					# Initialize a new shared memory manager.
-					#
-					# Creates and maps the shared memory file. Workers will map the same file
-					# independently using the provided path.
-					#
-					# @parameter path [String] Path to the shared memory file.
-					# @parameter size [Integer] Total size of the shared memory buffer.
-					# @parameter segment_size [Integer] Size of each allocation segment (default: 512 bytes).
-					# @parameter growth_factor [Integer, Float] Factor to grow by when resizing (default: 2, doubles the size).
-					#   Can be less than 2 or a floating point value; the result will be page-aligned to an integer.
-					def initialize(path, size: IO::Buffer::PAGE_SIZE * 8, segment_size: 512, growth_factor: 2)
-						@path = path
-						@size = size
-						@segment_size = segment_size
-						@growth_factor = growth_factor
-						
-						File.unlink(path) rescue nil
-						@file = File.open(path, "w+b")
-						@file.truncate(size)
-						# Supervisor maps the file for reading worker data
-						@buffer = IO::Buffer.map(@file, size)
-						
-						# Track allocated segments: worker_id => {offset: Integer, schema: Array}
-						@allocations = {}
-						
-						# Free list of segment offsets
-						@free_list = []
-						
-						# Initialize free list with all segments
-						(0...(@size / @segment_size)).each do |segment_index|
-							@free_list << (segment_index * @segment_size)
-						end
-					end
-					
-					# Allocate a segment for a worker.
-					#
-					# Automatically resizes the shared memory file if no segments are available.
-					#
-					# @parameter worker_id [Integer] The ID of the worker.
-					# @parameter schema [Array] Array of [key, type, offset] tuples describing the data layout.
-					# @returns [Integer] The offset into the shared memory buffer, or nil if allocation fails.
-					def allocate(worker_id, schema)
-						# Try to resize if we're out of segments
-						if @free_list.empty?
-							unless resize(@size * @growth_factor)
-								return nil
-							end
-						end
-						
-						offset = @free_list.shift
-						@allocations[worker_id] = {offset: offset, schema: schema}
-						
-						return offset
-					end
-					
-					# Free a segment allocated to a worker.
-					#
-					# @parameter worker_id [Integer] The ID of the worker.
-					def free(worker_id)
-						if allocation = @allocations.delete(worker_id)
-							@free_list << allocation[:offset]
-						end
-					end
-					
-					# Get the allocation information for a worker.
-					#
-					# @parameter worker_id [Integer] The ID of the worker.
-					# @returns [Hash] Allocation info with :offset and :schema, or nil if not allocated.
-					def allocation(worker_id)
-						@allocations[worker_id]
-					end
-					
-					# Get the current size of the shared memory file.
-					#
-					# @returns [Integer] The current size of the shared memory file.
-					def size
-						@size
-					end
-					
-					# Update the schema for an existing allocation.
-					#
-					# @parameter worker_id [Integer] The ID of the worker.
-					# @parameter schema [Array] Array of [key, type, offset] tuples describing the data layout.
-					def update_schema(worker_id, schema)
-						if allocation = @allocations[worker_id]
-							allocation[:schema] = schema
-						end
-					end
-					
-					# Read utilization data from a worker's allocated segment.
-					#
-					# @parameter worker_id [Integer] The ID of the worker.
-					# @returns [Hash] Hash mapping keys to their values, or nil if not allocated.
-					def read(worker_id)
-						allocation = @allocations[worker_id]
-						return nil unless allocation
-						
-						offset = allocation[:offset]
-						schema = allocation[:schema]
-						
-						result = {}
-						schema.each do |key, type, field_offset|
-							absolute_offset = offset + field_offset
-							
-							# Use IO::Buffer type symbols directly (i32, u32, i64, u64, f32, f64)
-							# IO::Buffer accepts both lowercase and uppercase versions
-							begin
-								result[key] = @buffer.get_value(type, absolute_offset)
-							rescue => error
-								Console.warn(self, "Failed to read value", type: type, key: key, offset: absolute_offset, exception: error)
-							end
-						end
-						
-						return result
-					end
-					
-					# Resize the shared memory file.
-					#
-					# Extends the file to the new size, remaps the buffer, and adds new segments
-					# to the free list. The new size must be larger than the current size and should
-					# be page-aligned for optimal performance.
-					#
-					# @parameter new_size [Integer] The new size for the shared memory file.
-					# @returns [Boolean] True if resize was successful, false otherwise.
-					def resize(new_size)
-						old_size = @size
-						return false if new_size <= old_size
-						
-						# Ensure new size is page-aligned (rounds up to nearest page boundary)
-						page_size = IO::Buffer::PAGE_SIZE
-						new_size = (((new_size + page_size - 1) / page_size) * page_size).to_i
-						
-						begin
-							# Extend the file:
-							@file.truncate(new_size)
-							
-							# Remap the buffer to the new size:
-							@buffer&.free
-							@buffer = IO::Buffer.map(@file, new_size)
-							
-							# Calculate new segments to add to free list:
-							old_segment_count = old_size / @segment_size
-							new_segment_count = new_size / @segment_size
-							
-							# Add new segments to free list:
-							(old_segment_count...new_segment_count).each do |segment_index|
-								@free_list << (segment_index * @segment_size)
-							end
-							
-							@size = new_size
-							
-							Console.info(self, "Resized shared memory", old_size: old_size, new_size: new_size, segments_added: new_segment_count - old_segment_count)
-							
-							return true
-						rescue => error
-							Console.error(self, "Failed to resize shared memory", old_size: old_size, new_size: new_size, exception: error)
-							return false
-						end
-					end
-					
-					# Close the shared memory file.
-					def close
-						@file&.close
-						@buffer = nil
-					end
-				end
+				# @deprecated Use {Async::Utilization::SegmentStore} instead.
+				SegmentAllocator = Async::Utilization::SegmentStore
+				
 				# Initialize a new utilization monitor.
 				#
 				# @parameter path [String] Path to the shared memory file.
@@ -199,7 +28,7 @@ module Async
 					@path = path
 					@segment_size = segment_size
 					
-					@allocator = SegmentAllocator.new(path, size: size, segment_size: segment_size)
+					@store = Async::Utilization::SegmentStore.open(path, size: size, segment_size: segment_size, replace: true)
 					
 					# Track workers: worker_id => supervisor_controller
 					@workers = {}
@@ -207,6 +36,9 @@ module Async
 					@guard = Mutex.new
 				end
 				
+				# @attribute [Async::Utilization::SegmentStore] The shared utilization segment store.
+				attr :store
+				
 				# Register a worker with the utilization monitor.
 				#
 				# Allocates a segment of shared memory and instructs the worker
@@ -220,7 +52,7 @@ module Async
 						return unless worker_id
 						
 						# Allocate a segment first (we'll get schema from worker)
-						offset = @allocator.allocate(worker_id, [])
+						offset = @store.allocate(worker_id, [])
 						
 						unless offset
 							Console.warn(self, "Failed to allocate utilization segment", worker_id: worker_id)
@@ -238,19 +70,19 @@ module Async
 								
 								# Update the allocation with the actual schema
 								if schema && !schema.empty?
-									@allocator.update_schema(worker_id, schema)
+									@store.update_schema(worker_id, schema)
 									@workers[worker_id] = supervisor_controller
 									
 									Console.info(self, "Registered worker utilization", worker_id: worker_id, offset: offset, schema: schema)
 								else
 									# Worker didn't provide schema, free the allocation
-									@allocator.free(worker_id)
+									@store.free(worker_id)
 									Console.info(self, "Worker did not provide utilization schema", worker_id: worker_id)
 								end
 							end
 						rescue => error
 							Console.error(self, "Error setting up worker utilization", worker_id: worker_id, exception: error)
-							@allocator.free(worker_id)
+							@store.free(worker_id)
 						end
 					end
 				end
@@ -266,7 +98,7 @@ module Async
 						return unless worker_id
 						
 						@workers.delete(worker_id)
-						@allocator.free(worker_id)
+						@store.free(worker_id)
 						
 						Console.debug(self, "Freed utilization segment", worker_id: worker_id)
 					end
@@ -316,7 +148,7 @@ module Async
 				def sample_by_worker
 					@guard.synchronize do
 						@workers.each_with_object({}) do |(worker_id, supervisor_controller), workers|
-							if utilization = @allocator.read(worker_id)
+							if utilization = @store.read(worker_id)
 								workers[worker_id] = {
 									state: supervisor_controller.state.dup.freeze,
 									utilization: utilization.freeze,

data/lib/async/service/supervisor/version.rb

@@ -9,7 +9,7 @@ module Async
 	module Service
 		# @namespace
 		module Supervisor
-			VERSION = "0.20.0"
+			VERSION = "0.21.0"
 		end
 	end
 end

data/lib/metrics/provider/async/service/supervisor/utilization_monitor.rb

@@ -11,11 +11,11 @@ require_relative "../../../../../async/service/supervisor/utilization_monitor"
 class Async::Service::Supervisor::UtilizationMonitor
 	Metrics::Provider(self) do
 		UTILIZATION = Metrics.metric("async.utilization", :gauge, description: "Active requests per worker.")
-		UTILIZATION_CONNECTIONS_ACTIVE = Metrics.metric("async.utilization.connections.active", :gauge, description: "The number of active connections.")
-		UTILIZATION_CONNECTIONS_TOTAL = Metrics.metric("async.utilization.connections.total", :gauge, description: "The total number of connections.")
-		UTILIZATION_REQUESTS_ACTIVE = Metrics.metric("async.utilization.requests.active", :gauge, description: "The number of active requests.")
-		UTILIZATION_REQUESTS_TOTAL = Metrics.metric("async.utilization.requests.total", :gauge, description: "The total number of requests.")
-		UTILIZATION_WORKERS = Metrics.metric("async.utilization.workers", :gauge, description: "The number of workers contributing utilization metrics.")
+		UTILIZATION_CONNECTIONS_ACTIVE = Metrics.metric("async.utilization.connections_active", :gauge, description: "The number of active connections.")
+		UTILIZATION_CONNECTIONS_TOTAL = Metrics.metric("async.utilization.connections_total", :gauge, description: "The total number of connections.")
+		UTILIZATION_REQUESTS_ACTIVE = Metrics.metric("async.utilization.requests_active", :gauge, description: "The number of active requests.")
+		UTILIZATION_REQUESTS_TOTAL = Metrics.metric("async.utilization.requests_total", :gauge, description: "The total number of requests.")
+		UTILIZATION_WORKER_COUNT = Metrics.metric("async.utilization.worker_count", :gauge, description: "The number of workers contributing utilization metrics.")
 		
 		def emit(metrics)
 			metrics.each do |service_name, fields|
@@ -38,7 +38,7 @@ class Async::Service::Supervisor::UtilizationMonitor
 				end
 				
 				if worker_count = fields[:worker_count]
-					UTILIZATION_WORKERS.emit(worker_count, tags: tags)
+					UTILIZATION_WORKER_COUNT.emit(worker_count, tags: tags)
 					
 					if worker_count > 0 and requests_active = fields[:requests_active]
 						UTILIZATION.emit(requests_active.to_f / worker_count, tags: tags)

data/readme.md

@@ -30,6 +30,10 @@ Please see the [project documentation](https://socketry.github.io/async-service-
 
 Please see the [project releases](https://socketry.github.io/async-service-supervisor/releases/index) for all releases.
 
+### v0.21.0
+
+  - Use `Async::Utilization::SegmentStore` to manage utilization shared memory.
+
 ### v0.20.0
 
   - Add per-worker snapshots to `Async::Service::Supervisor::UtilizationMonitor`.
@@ -66,21 +70,31 @@ Please see the [project releases](https://socketry.github.io/async-service-super
 
   - Introduce `UtilizationMonitor`, that uses shared memory to track worker utilization metrics, like total and active requests, connections, etc.
 
-### v0.11.0
-
-  - Add `state` attribute to `SupervisorController` to store per-worker metadata (e.g., service name).
-  - Add `state` parameter to `Worker#initialize` to allow workers to provide state during registration.
-  - State is now accessible via `supervisor_controller.state` instead of `connection.state` (as it was in `Async::Container::Supervisor`).
-
 ## Contributing
 
 We welcome contributions to this project.
 
-1.  Fork it.
+1.  Fork the repository.
 2.  Create your feature branch (`git checkout -b my-new-feature`).
-3.  Commit your changes (`git commit -am 'Add some feature'`).
+3.  Commit your changes (`git commit -am 'Add some feature.'`).
 4.  Push to the branch (`git push origin my-new-feature`).
-5.  Create new Pull Request.
+5.  Create a new pull request.
+
+### Running Tests
+
+To run the test suite:
+
+``` bash
+$ bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` bash
+$ bundle exec bake gem:release:patch # or minor or major
+```
 
 ### Developer Certificate of Origin
 

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.21.0
+
+  - Use `Async::Utilization::SegmentStore` to manage utilization shared memory.
+
 ## v0.20.0
 
   - Add per-worker snapshots to `Async::Service::Supervisor::UtilizationMonitor`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-service-supervisor
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.21.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -86,14 +86,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: io-endpoint
   requirement: !ruby/object:Gem::Requirement
@@ -190,6 +190,8 @@ homepage: https://github.com/socketry/async-service-supervisor
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/socketry/async-service-supervisor/issues
+  changelog_uri: https://github.com/socketry/async-service-supervisor/blob/main/releases.md
   documentation_uri: https://socketry.github.io/async-service-supervisor/
   source_code_uri: https://github.com/socketry/async-service-supervisor.git
 rdoc_options: []