async-utilization 0.3.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2494a3f35fcbfd987fe6520ceda64225ccc6592ebe4072f0260f38a430d0d3fc
-  data.tar.gz: '0668665f31e13ac0d00c5eded51ad94f7f394927318e05ef83f7a5cd818e22e3'
+  metadata.gz: 64e873daf011f6226b574b609cecde9b402edb2a2ff5144f68526195575492ea
+  data.tar.gz: b5e25e805f9e8b359af97653bc1496706c9ac81d8c8c2ea42c1bbd1680be271b
 SHA512:
-  metadata.gz: 863148a136e0a8696c337c5c24e18f8751bea2b586f1a703235992103c5454d1621d9296c401ded2d75aa532255beab3ae7ee2ad84211a8eb3b9971aac7b5fc8
-  data.tar.gz: 4a6e0ee78558c67dd2f8c5e8bb284c0aaed26cb23a3df700b451841a8081dafd9973ff2ef033f7f137cae4e657b60eae29cfeca89a8edd7ca3233f46a7318ce5
+  metadata.gz: e486c1307fead9186ae112f2c258ec4e5ed25b7c6cb8d49d56974634ed2e250400ccb8a57caccb736871df8cd592e5be5379bfd9ac738cf9ace363812e651a90
+  data.tar.gz: 4c0380449a03ea7b1ba5c42cc0b70e86cbe76fb360e0bdccaf7f3b5477dccd26d0171921e91f2e535433a236c60c8abb8a97f3dcaf1c6e34b17d7e8c87a72a17

data/lib/async/utilization/metric.rb

@@ -38,11 +38,14 @@ module Async
 			# @attribute [Symbol] The field name for this metric.
 			attr :name
 			
-			# @attribute [Numeric] The current value of this metric.
-			attr :value
-			
-			# @attribute [Mutex] The mutex for thread safety.
-			attr :guard
+			# Get the current in-memory metric value.
+			#
+			# @returns [Numeric] The last value written to this metric.
+			def value
+				@guard.synchronize do
+					@value
+				end
+			end
 			
 			# Set the observer and rebuild cache.
 			#

data/lib/async/utilization/namespace.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Async
+	module Utilization
+		# A registry-like view that prefixes metric names.
+		#
+		# Namespaces let components use generic metric names while applications decide
+		# how those names are composed in the shared registry.
+		class Namespace
+			# Initialize a new namespace.
+			#
+			# @parameter registry [Registry] The underlying registry.
+			# @parameter name [Symbol] The namespace name.
+			def initialize(registry, name)
+				@registry = registry
+				@name = name.to_sym
+			end
+			
+			# @attribute [Registry] The underlying registry.
+			attr :registry
+			
+			# @attribute [Symbol] The namespace name.
+			attr :name
+			
+			# Get a metric in this namespace.
+			#
+			# @parameter name [Symbol] The metric name.
+			# @returns [Metric] A metric instance for the namespaced field.
+			def metric(name)
+				@registry.metric(metric_name(name))
+			end
+			
+			# Get a nested namespace.
+			#
+			# @parameter name [Symbol] The nested namespace name.
+			# @returns [Namespace] A namespace view with the composed name.
+			def namespace(name)
+				self.class.new(@registry, metric_name(name))
+			end
+			
+			private
+			
+			def metric_name(name)
+				:"#{@name}_#{name}"
+			end
+		end
+	end
+end

data/lib/async/utilization/registry.rb

@@ -4,6 +4,7 @@
 # Copyright, 2026, by Samuel Williams.
 
 require "console"
+require_relative "namespace"
 
 module Async
 	module Utilization
@@ -22,9 +23,11 @@ module Async
 		# @example Create a registry and emit metrics:
 		# 	registry = Async::Utilization::Registry.new
 		# 	
-		# 	# Emit metrics - values tracked in registry
-		# 	registry.increment(:total_requests)
-		# 	registry.track(:active_requests) do
+		# 	total_requests = registry.metric(:total_requests)
+		# 	total_requests.increment
+		# 	
+		# 	active_requests = registry.metric(:active_requests)
+		# 	active_requests.track do
 		# 		# Handle request - auto-decrements when block completes
 		# 	end
 		# 	
@@ -37,7 +40,6 @@ module Async
 		# 	observer = Async::Utilization::Observer.open(schema, "/path/to/shm", 4096, 0)
 		# 	registry.observer = observer
 		class Registry
-			
 			# Initialize a new registry.
 			def initialize
 				@observer = nil
@@ -49,15 +51,12 @@ module Async
 			# @attribute [Object | Nil] The registered observer.
 			attr :observer
 			
-			# @attribute [Mutex] The mutex for thread safety.
-			attr :guard
-			
 			# Get the current values for all metrics.
 			#
 			# @returns [Hash] Hash mapping field names to their current values.
 			def values
 				@metrics.transform_values do |metric|
-					metric.guard.synchronize{metric.value}
+					metric.value
 				end
 			end
 			
@@ -79,48 +78,6 @@ module Async
 					
 					# Console.info(self, "Observer assigned", observer: observer, metric_count: @metrics.size)
 				end
-				
-			end
-			
-			# Set a field value.
-			#
-			# Delegates to the metric instance for the given field.
-			#
-			# @parameter field [Symbol] The field name to set.
-			# @parameter value [Numeric] The value to set.
-			def set(field, value)
-				metric(field).set(value)
-			end
-			
-			# Increment a field value.
-			#
-			# Delegates to the metric instance for the given field.
-			#
-			# @parameter field [Symbol] The field name to increment.
-			# @returns [Integer] The new value of the field.
-			def increment(field)
-				metric(field).increment
-			end
-			
-			# Track an operation: increment before the block, decrement after it completes.
-			#
-			# Delegates to the metric instance for the given field.
-			#
-			# @parameter field [Symbol] The field name to track.
-			# @yield The operation to track.
-			# @returns [Object] The block's return value.
-			def track(field, &block)
-				metric(field).track(&block)
-			end
-			
-			# Decrement a field value.
-			#
-			# Delegates to the metric instance for the given field.
-			#
-			# @parameter field [Symbol] The field name to decrement.
-			# @returns [Integer] The new value of the field.
-			def decrement(field)
-				metric(field).decrement
 			end
 			
 			# Get a cached metric reference for a field.
@@ -137,6 +94,14 @@ module Async
 					@metrics[field] ||= Metric.for(field, @observer)
 				end
 			end
+			
+			# Get a namespace view of this registry.
+			#
+			# @parameter name [Symbol] The namespace name.
+			# @returns [Namespace] A registry-like namespace view.
+			def namespace(name)
+				Namespace.new(self, name)
+			end
 		end
 	end
 end

data/lib/async/utilization/segment_store.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "console"
+
+module Async
+	module Utilization
+		# Represents a shared memory segment store for utilization data.
+		#
+		# Stores fixed-size segments in a shared memory file, associates each
+		# segment with a utilization schema, and reads the resulting values.
+		class SegmentStore
+			# Open a shared memory segment store.
+			#
+			# @parameter path [String] The path to the shared memory file.
+			# @parameter size [Integer] The initial size of the shared memory file.
+			# @parameter segment_size [Integer] The size of each allocation segment.
+			# @parameter growth_factor [Integer | Float] The factor used to grow the file when all segments are allocated.
+			# @parameter replace [Boolean] Whether to replace an existing file at the given path.
+			# @yields {|store| ...} The store, which is closed after the block completes.
+			# 	@parameter store [SegmentStore] The opened store.
+			# @returns [SegmentStore | Object] The store, or the value returned by the block.
+			# @raises [ArgumentError] If the store configuration is invalid.
+			# @raises [Errno::EEXIST] If the path already exists and `replace` is `false`.
+			def self.open(path, size: IO::Buffer::PAGE_SIZE * 8, segment_size: 512, growth_factor: 2, replace: false)
+				raise ArgumentError, "Size must be a positive integer!" unless size.is_a?(Integer) && size > 0
+				raise ArgumentError, "Segment size must be a positive integer!" unless segment_size.is_a?(Integer) && segment_size > 0
+				raise ArgumentError, "Segment size must not exceed size!" if segment_size > size
+				raise ArgumentError, "Growth factor must be greater than 1!" unless growth_factor.is_a?(Numeric) && growth_factor.real? && growth_factor > 1
+				
+				if replace
+					begin
+						File.unlink(path)
+					rescue Errno::ENOENT
+						# The file does not need to be replaced:
+					end
+				end
+				
+				file = File.open(path, "w+bx")
+				buffer = nil
+				
+				begin
+					file.truncate(size)
+					buffer = IO::Buffer.map(file, size)
+					store = new(file, buffer, size: size, segment_size: segment_size, growth_factor: growth_factor)
+				rescue
+					buffer&.free
+					file.close
+					raise
+				end
+				
+				return store unless block_given?
+				
+				begin
+					yield store
+				ensure
+					store.close
+				end
+			end
+			
+			# Initialize the shared memory segment store.
+			#
+			# @parameter file [File] The open shared memory file.
+			# @parameter buffer [IO::Buffer] The mapped shared memory buffer.
+			# @parameter size [Integer] The initial size of the shared memory file.
+			# @parameter segment_size [Integer] The size of each allocation segment.
+			# @parameter growth_factor [Integer | Float] The factor used to grow the file when all segments are allocated.
+			def initialize(file, buffer, size:, segment_size:, growth_factor:)
+				@file = file
+				@buffer = buffer
+				@size = size
+				@segment_size = segment_size
+				@growth_factor = growth_factor
+				
+				@allocations = {}
+				@free_list = []
+				
+				(0...(@size / @segment_size)).each do |segment_index|
+					@free_list << (segment_index * @segment_size)
+				end
+			end
+			
+			# Allocate a segment for the given key.
+			#
+			# The shared memory file is automatically resized if no segments are available.
+			#
+			# @parameter key [Object] The key used to identify the allocation.
+			# @parameter schema [Array] The `[key, type, offset]` tuples describing the data layout.
+			# @returns [Integer | Nil] The offset into the shared memory file, or `nil` if allocation fails.
+			def allocate(key, schema)
+				if @free_list.empty?
+					unless resize(@size * @growth_factor)
+						return nil
+					end
+				end
+				
+				offset = @free_list.shift
+				@allocations[key] = {offset: offset, schema: schema}
+				
+				return offset
+			end
+			
+			# Free the segment allocated to the given key.
+			#
+			# @parameter key [Object] The key used to identify the allocation.
+			def free(key)
+				if allocation = @allocations.delete(key)
+					@free_list << allocation[:offset]
+				end
+			end
+			
+			# Get the allocation information for the given key.
+			#
+			# @parameter key [Object] The key used to identify the allocation.
+			# @returns [Hash | Nil] The allocation offset and schema, or `nil` if the key is not allocated.
+			def allocation(key)
+				@allocations[key]
+			end
+			
+			# @attribute [Integer] The current size of the shared memory file.
+			attr :size
+			
+			# Update the schema for an existing allocation.
+			#
+			# @parameter key [Object] The key used to identify the allocation.
+			# @parameter schema [Array] The `[key, type, offset]` tuples describing the data layout.
+			def update_schema(key, schema)
+				if allocation = @allocations[key]
+					allocation[:schema] = schema
+				end
+			end
+			
+			# Read utilization data from an allocated segment.
+			#
+			# @parameter key [Object] The key used to identify the allocation.
+			# @returns [Hash | Nil] The utilization values, or `nil` if the key is not allocated.
+			def read(key)
+				allocation = @allocations[key]
+				return nil unless allocation
+				
+				offset = allocation[:offset]
+				schema = allocation[:schema]
+				
+				result = {}
+				schema.each do |field_key, type, field_offset|
+					absolute_offset = offset + field_offset
+					
+					begin
+						result[field_key] = @buffer.get_value(type, absolute_offset)
+					rescue => error
+						Console.warn(self, "Failed to read value", type: type, key: field_key, offset: absolute_offset, exception: error)
+					end
+				end
+				
+				return result
+			end
+			
+			# Resize the shared memory file.
+			#
+			# The new size is rounded up to the nearest page boundary.
+			#
+			# @parameter new_size [Integer] The requested new size of the shared memory file.
+			# @returns [Boolean] Whether the file was resized successfully.
+			def resize(new_size)
+				old_size = @size
+				return false if new_size <= old_size
+				
+				page_size = IO::Buffer::PAGE_SIZE
+				new_size = (((new_size + page_size - 1) / page_size) * page_size).to_i
+				
+				begin
+					@file.truncate(new_size)
+					buffer = IO::Buffer.map(@file, new_size)
+					
+					@buffer&.free
+					@buffer = buffer
+					
+					old_segment_count = old_size / @segment_size
+					new_segment_count = new_size / @segment_size
+					
+					(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
+				@buffer&.free
+				@buffer = nil
+				
+				@file&.close
+				@file = nil
+			end
+		end
+	end
+end

data/lib/async/utilization/version.rb

@@ -7,6 +7,6 @@
 module Async
 	# @namespace
 	module Utilization
-		VERSION = "0.3.2"
+		VERSION = "0.5.0"
 	end
 end

data/lib/async/utilization.rb

@@ -5,9 +5,11 @@
 
 require_relative "utilization/version"
 require_relative "utilization/schema"
+require_relative "utilization/namespace"
 require_relative "utilization/registry"
 require_relative "utilization/observer"
 require_relative "utilization/metric"
+require_relative "utilization/segment_store"
 
 # @namespace
 module Async

data/readme.md

@@ -14,6 +14,15 @@ Please see the [project documentation](https://socketry.github.io/async-utilizat
 
 Please see the [project releases](https://socketry.github.io/async-utilization/releases/index) for all releases.
 
+### v0.5.0
+
+  - Add `Async::Utilization::SegmentStore` for allocating and reading utilization data in shared memory.
+
+### v0.4.0
+
+  - Add `Async::Utilization::Namespace` for composing registry metric names.
+  - `Async::Utilization::Metric` is the primary interface, remove `#set`, `#increment`, `#decrement` and `#track` from `Registry`.
+
 ### v0.3.2
 
   - Better observer state handling.
@@ -34,11 +43,27 @@ Please see the [project releases](https://socketry.github.io/async-utilization/r
 
 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,14 @@
 # Releases
 
+## v0.5.0
+
+  - Add `Async::Utilization::SegmentStore` for allocating and reading utilization data in shared memory.
+
+## v0.4.0
+
+  - Add `Async::Utilization::Namespace` for composing registry metric names.
+  - `Async::Utilization::Metric` is the primary interface, remove `#set`, `#increment`, `#decrement` and `#track` from `Registry`.
+
 ## v0.3.2
 
   - Better observer state handling.

data/test/async/utilization/namespace.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "sus"
+require "async/utilization"
+
+describe Async::Utilization::Namespace do
+	let(:registry) {Async::Utilization::Registry.new}
+	let(:namespace) {registry.namespace(:socket_accept)}
+	
+	it "uses namespaced metric names" do
+		metric = namespace.metric(:acquired_count)
+		
+		expect(metric).to be_a(Async::Utilization::Metric)
+		expect(metric.name).to be == :socket_accept_acquired_count
+		
+		metric.set(2)
+		expect(registry.values).to have_keys(socket_accept_acquired_count: be == 2)
+	end
+	
+	it "returns the same metric instance for the same namespaced field" do
+		metric1 = namespace.metric(:waiting_count)
+		metric2 = namespace.metric(:waiting_count)
+		
+		expect(metric1).to be == metric2
+	end
+	
+	it "supports nested namespaces" do
+		metric = namespace.namespace(:long_task).metric(:waiting_count)
+		
+		expect(metric.name).to be == :socket_accept_long_task_waiting_count
+		
+		metric.increment
+		expect(registry.values).to have_keys(socket_accept_long_task_waiting_count: be == 1)
+	end
+	
+	it "writes namespaced metrics to an observer" do
+		schema = Async::Utilization::Schema.build(socket_accept_acquired_count: :u64)
+		buffer = IO::Buffer.new(8)
+		
+		observer = Object.new
+		observer.define_singleton_method(:schema){schema}
+		observer.define_singleton_method(:buffer){buffer}
+		
+		registry.observer = observer
+		
+		namespace.metric(:acquired_count).set(5)
+		
+		expect(buffer.get_value(:u64, 0)).to be == 5
+	end
+end

data/test/async/utilization/registry.rb

@@ -8,37 +8,38 @@ require "async/utilization"
 
 describe Async::Utilization::Registry do
 	let(:registry) {Async::Utilization::Registry.new}
+	let(:test_field_metric) {registry.metric(:test_field)}
 	
 	it "can increment a value" do
-		value = registry.increment(:test_field)
+		value = test_field_metric.increment
 		expect(value).to be == 1
 		expect(registry.values[:test_field]).to be == 1
 	end
 	
 	it "can increment multiple times" do
-		registry.increment(:test_field)
-		registry.increment(:test_field)
-		registry.increment(:test_field)
+		test_field_metric.increment
+		test_field_metric.increment
+		test_field_metric.increment
 		
 		expect(registry.values[:test_field]).to be == 3
 	end
 	
 	it "can decrement a value" do
-		registry.increment(:test_field)
-		registry.increment(:test_field)
+		test_field_metric.increment
+		test_field_metric.increment
 		
-		value = registry.decrement(:test_field)
+		value = test_field_metric.decrement
 		expect(value).to be == 1
 		expect(registry.values[:test_field]).to be == 1
 	end
 	
 	it "can set a value directly" do
-		registry.set(:test_field, 42)
+		test_field_metric.set(42)
 		expect(registry.values[:test_field]).to be == 42
 	end
 	
 	it "can track an operation with auto-decrement" do
-		registry.track(:test_field) do
+		test_field_metric.track do
 			expect(registry.values[:test_field]).to be == 1
 		end
 		
@@ -47,7 +48,7 @@ describe Async::Utilization::Registry do
 	
 	it "decrements even if track block raises an error" do
 		begin
-			registry.track(:test_field) do
+			test_field_metric.track do
 				raise "Error!"
 			end
 		rescue
@@ -64,13 +65,13 @@ describe Async::Utilization::Registry do
 		observer.define_singleton_method(:schema){schema}
 		observer.define_singleton_method(:buffer){buffer}
 		
-		registry.set(:test_field, 5)
+		test_field_metric.set(5)
 		registry.observer = observer
 		
 		# Buffer should be synced with the existing value on observer assignment
 		expect(buffer.get_value(:u64, 0)).to be == 5
 		
-		registry.increment(:test_field)
+		test_field_metric.increment
 		
 		# Buffer should reflect the incremented value
 		expect(buffer.get_value(:u64, 0)).to be == 6
@@ -83,6 +84,14 @@ describe Async::Utilization::Registry do
 		expect(registry.values).to have_keys(module_test: be == 2)
 	end
 	
+	it "can create a namespace" do
+		namespace = registry.namespace(:socket_accept)
+		
+		expect(namespace).to be_a(Async::Utilization::Namespace)
+		expect(namespace.registry).to be == registry
+		expect(namespace.name).to be == :socket_accept
+	end
+	
 	it "can use metric for decrement" do
 		registry.metric(:module_decrement_test).increment
 		registry.metric(:module_decrement_test).increment
@@ -104,7 +113,7 @@ describe Async::Utilization::Registry do
 		observer.define_singleton_method(:schema){schema}
 		observer.define_singleton_method(:buffer){buffer}
 		
-		registry.set(:test_field, 7)
+		test_field_metric.set(7)
 		registry.observer = observer
 		
 		expect(buffer.get_value(:u64, 0)).to be == 7
@@ -118,11 +127,11 @@ describe Async::Utilization::Registry do
 		observer.define_singleton_method(:buffer){buffer}
 		
 		registry.observer = observer
-		registry.set(:test_field, 5)
+		test_field_metric.set(5)
 		expect(buffer.get_value(:u64, 0)).to be == 5
 		
 		registry.observer = nil
-		registry.set(:test_field, 99)
+		test_field_metric.set(99)
 		
 		# Buffer unchanged, in-memory value updated
 		expect(buffer.get_value(:u64, 0)).to be == 5

data/test/async/utilization/segment_store.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "sus"
+require "sus/fixtures/console/null_logger"
+require "sus/fixtures/temporary_directory_context"
+require "async/utilization"
+
+describe Async::Utilization::SegmentStore do
+	include Sus::Fixtures::Console::NullLogger
+	include Sus::Fixtures::TemporaryDirectoryContext
+	
+	let(:path) {File.join(root, "utilization.shm")}
+	let(:page_size) {IO::Buffer::PAGE_SIZE}
+	let(:schema) do
+		Async::Utilization::Schema.build(
+			requests_total: :u64,
+			requests_active: :u32,
+		)
+	end
+	
+	it "allocates, reads, and reuses segments" do
+		store = subject.open(path, size: page_size, segment_size: page_size)
+		
+		first_offset = store.allocate(:first, [])
+		expect(first_offset).to be == 0
+		expect(store.allocation(:first)).to have_keys(offset: be == 0, schema: be == [])
+		
+		store.update_schema(:first, schema.to_a)
+		observer = Async::Utilization::Observer.open(schema, path, page_size, first_offset)
+		observer.buffer.set_value(:u64, 0, 12)
+		observer.buffer.set_value(:u32, 8, 3)
+		
+		expect(store.read(:first)).to be == {requests_total: 12, requests_active: 3}
+		
+		store.free(:first)
+		expect(store.read(:first)).to be_nil
+		expect(store.allocate(:second, schema.to_a)).to be == first_offset
+	ensure
+		observer&.buffer&.free
+		store&.close
+	end
+	
+	it "preserves existing observer mappings when resizing" do
+		store = subject.open(path, size: page_size, segment_size: page_size)
+		first_offset = store.allocate(:first, schema.to_a)
+		observer = Async::Utilization::Observer.open(schema, path, page_size, first_offset)
+		
+		observer.buffer.set_value(:u64, 0, 42)
+		expect(store.read(:first)[:requests_total]).to be == 42
+		
+		second_offset = store.allocate(:second, schema.to_a)
+		expect(second_offset).to be == page_size
+		expect(store.size).to be == page_size * 2
+		
+		observer.buffer.set_value(:u64, 0, 99)
+		expect(store.read(:first)[:requests_total]).to be == 99
+	ensure
+		observer&.buffer&.free
+		store&.close
+	end
+	
+	it "returns nil when automatic resizing fails" do
+		store = subject.open(path, size: page_size, segment_size: page_size)
+		store.allocate(:first, schema.to_a)
+		
+		expect(store).to receive(:resize).and_return(false)
+		expect(store.allocate(:second, schema.to_a)).to be_nil
+	ensure
+		store&.close
+	end
+	
+	it "skips fields that cannot be read" do
+		store = subject.open(path, size: page_size, segment_size: page_size)
+		store.allocate(:worker, [[:invalid, :invalid, 0]])
+		
+		expect(store.read(:worker)).to be == {}
+	ensure
+		store&.close
+	end
+	
+	it "reports resize failures" do
+		store = subject.open(path, size: page_size, segment_size: page_size)
+		file = store.instance_variable_get(:@file)
+		
+		expect(file).to receive(:truncate).and_raise(IOError, "Failed to resize")
+		expect(store.resize(page_size * 2)).to be_falsey
+	ensure
+		store&.close
+	end
+	
+	it "only replaces an existing file when requested" do
+		original = subject.open(path, size: page_size, segment_size: page_size)
+		original.resize(page_size * 2)
+		
+		existing_file = File.open(path, "rb")
+		original_size = existing_file.size
+		original.close
+		
+		expect do
+			subject.open(path, size: page_size, segment_size: page_size)
+		end.to raise_exception(Errno::EEXIST)
+		
+		replacement = subject.open(path, size: page_size, segment_size: page_size, replace: true)
+		expect(replacement.size).to be == page_size
+		expect(existing_file.size).to be == original_size
+	ensure
+		original&.close
+		replacement&.close
+		existing_file&.close
+	end
+	
+	it "validates configuration before replacing an existing file" do
+		File.write(path, "existing")
+		
+		[
+			[{size: 0}, "Size must be a positive integer!"],
+			[{segment_size: 0}, "Segment size must be a positive integer!"],
+			[{size: page_size, segment_size: page_size * 2}, "Segment size must not exceed size!"],
+			[{growth_factor: 1}, "Growth factor must be greater than 1!"],
+		].each do |options, message|
+			expect do
+				subject.open(path, replace: true, **options)
+			end.to raise_exception(ArgumentError, message: be == message)
+			
+			expect(File.read(path)).to be == "existing"
+		end
+	end
+	
+	it "closes the store after yielding it" do
+		file = nil
+		
+		result = subject.open(path, size: page_size, segment_size: page_size) do |store|
+			file = store.instance_variable_get(:@file)
+			expect(file.closed?).to be_falsey
+			:result
+		end
+		
+		expect(result).to be == :result
+		expect(file.closed?).to be_truthy
+	end
+	
+	it "closes the file when mapping fails" do
+		file = File.open(path, "w+bx")
+		File.unlink(path)
+		
+		expect(File).to receive(:open).with(path, "w+bx").and_return(file)
+		expect(IO::Buffer).to receive(:map).with(file, page_size).and_raise(IOError, "Failed to map")
+		
+		expect do
+			subject.open(path, size: page_size, segment_size: page_size)
+		end.to raise_exception(IOError, message: be == "Failed to map")
+		
+		expect(file.closed?).to be_truthy
+	end
+	
+	it "releases acquired resources when initialization fails" do
+		file = File.open(path, "w+bx")
+		File.unlink(path)
+		buffer = IO::Buffer.new(page_size)
+		
+		expect(File).to receive(:open).with(path, "w+bx").and_return(file)
+		expect(IO::Buffer).to receive(:map).with(file, page_size).and_return(buffer)
+		expect(subject).to receive(:new).and_raise(IOError, "Failed to initialize")
+		
+		expect do
+			subject.open(path, size: page_size, segment_size: page_size)
+		end.to raise_exception(IOError, message: be == "Failed to initialize")
+		
+		expect(file.closed?).to be_truthy
+		expect(buffer.null?).to be_truthy
+	end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-utilization
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -58,22 +58,28 @@ extra_rdoc_files: []
 files:
 - lib/async/utilization.rb
 - lib/async/utilization/metric.rb
+- lib/async/utilization/namespace.rb
 - lib/async/utilization/observer.rb
 - lib/async/utilization/registry.rb
 - lib/async/utilization/schema.rb
+- lib/async/utilization/segment_store.rb
 - lib/async/utilization/version.rb
 - license.md
 - readme.md
 - releases.md
 - test/async/utilization.rb
 - test/async/utilization/metric.rb
+- test/async/utilization/namespace.rb
 - test/async/utilization/observer.rb
 - test/async/utilization/registry.rb
 - test/async/utilization/schema.rb
+- test/async/utilization/segment_store.rb
 homepage: https://github.com/socketry/async-utilization
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/socketry/async-utilization/issues
+  changelog_uri: https://github.com/socketry/async-utilization/blob/main/releases.md
   documentation_uri: https://socketry.github.io/async-utilization/
   source_code_uri: https://github.com/socketry/async-utilization.git
 rdoc_options: []
@@ -90,7 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.10
 specification_version: 4
 summary: High-performance utilization metrics for Async services using shared memory.
 test_files: []