async-utilization 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4114f3169e309e3062d153202d83d3eb7b38031dc47a5fbb0df0e3cf63296e9d
-  data.tar.gz: 68eca39b660a7d6414e12bb79ee464d3267d62ec4a1a5ab39c23742a6bb645a4
+  metadata.gz: 522f4b5822343c23f14422555147e2159e2bac50afbd230a06e985e2cfe1cee4
+  data.tar.gz: caa61db8daf6f65a77e319a210ee0079f9a647deed614e7cc5333507967964fa
 SHA512:
-  metadata.gz: 45cd92a3a8ae94aa2c2d6847cff090c7e5a1fadd96cd43dad062c2cf1384d9c1743926311151386a32517d41757e267fb35c5e7e276a4f7cead08468a83c9b68
-  data.tar.gz: 901a1771f0116652411a7cdbb5122669e814b4dc3594646d764179851ba0cf1ef7e8800838191bf2a67e2db3c877513ced9f3df4f58adedc8b4a84f4a0800890
+  metadata.gz: ebaabb2e0959e3664e4e2a18812d71efa75d967a2fb01a89f8d63af02eb9e36bc564edfc50c7315b4efbbe8ee5f60e865250cb660daa274fa185e6a538994f6c
+  data.tar.gz: 7760f55b1383998120a3f7bf0b65b578c8da04bf648c0407f6b3e57040edec2b1487b82356f6d11eaf3bdb02cab9ddc8797eb3c8ee67c930a03d35fec08a5e60

data/lib/async/utilization/metric.rb

@@ -11,16 +11,26 @@ module Async
 		# including the buffer, offset, and type. When the observer changes, the cache
 		# is invalidated and rebuilt on the next access.
 		class Metric
+			# Create a new metric for the given field and observer.
+			#
+			# @parameter field [Symbol] The field name for this metric.
+			# @parameter observer [Observer | Nil] The observer to associate with this metric.
+			# @returns [Metric] A new metric instance.
+			def self.for(field, observer)
+				self.new(field).tap do |metric|
+					metric.observer = observer
+				end
+			end
+			
 			# Initialize a new metric.
 			#
 			# @parameter name [Symbol] The field name for this metric.
-			# @parameter registry [Registry] The registry instance to use.
-			def initialize(name, registry)
+			def initialize(name)
 				@name = name.to_sym
-				@registry = registry
 				@value = 0
-				@cache_valid = false
-				@cached_field_info = nil
+				
+				@observer = nil
+				@cached_field = nil
 				@cached_buffer = nil
 				@guard = Mutex.new
 			end
@@ -28,25 +38,44 @@ 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
 			
-			# Invalidate the cached field information.
+			# Set the observer and rebuild cache.
 			#
-			# Called when the observer changes to force cache rebuild.
-			def invalidate
-				@cache_valid = false
-				@cached_field_info = nil
-				@cached_buffer = nil
+			# This is called when the registry assigns a new observer (or removes it).
+			# The cache is invalidated and then immediately recomputed so that the
+			# fast write path doesn't need to re-check the observer on the first write.
+			#
+			# @parameter observer [Observer | Nil] The new observer (or nil).
+			def observer=(observer)
+				@guard.synchronize do
+					@observer = observer
+					
+					if @observer
+						if field = @observer.schema[@name]
+							if buffer = @observer.buffer
+								@cached_field = field
+								@cached_buffer = buffer
+								
+								return write_direct(@value)
+							end
+						end
+					end
+					
+					@cached_field = nil
+					@cached_buffer = nil
+				end
 			end
 			
 			# Increment the metric value.
 			#
-			# Uses the fast path (direct buffer write) when cache is valid and observer is available.
-			#
 			# @returns [Integer] The new value of the field.
 			def increment
 				@guard.synchronize do
@@ -103,28 +132,6 @@ module Async
 			
 			protected
 			
-			# Check if the cache is valid and rebuild if necessary.
-			#
-			# Always attempts to build the cache if it's invalid. Returns true if cache
-			# is now valid (observer exists, field is in schema, and buffer is available), false otherwise.
-			#
-			# @returns [bool] True if cache is valid, false otherwise.
-			def ensure_cache_valid!
-				unless @cache_valid
-					if observer = @registry.observer
-						if field = observer.schema[@name]
-							if buffer = observer.buffer
-								@cached_field_info = field
-								@cached_buffer = buffer
-							end
-						end
-					end
-					
-					# Once we've validated the cache, even if there was no observer or buffer, we mark it as valid, so that we don't try to revalidate it again:
-					@cache_valid = true
-				end
-			end
-			
 			# Write directly to the cached buffer if available.
 			#
 			# This is the fast path that avoids hash lookups. Always ensures cache is valid
@@ -133,16 +140,12 @@ module Async
 			# @parameter value [Numeric] The value to write.
 			# @returns [Boolean] Whether the write succeeded.
 			def write_direct(value)
-				self.ensure_cache_valid!
-				
 				if @cached_buffer
-					@cached_buffer.set_value(@cached_field_info.type, @cached_field_info.offset, value)
+					@cached_buffer.set_value(@cached_field.type, @cached_field.offset, value)
 				end
 				
 				return true
 			rescue => error
-				# If write fails, log warning but don't invalidate cache
-				# The error might be transient, and invalidating would force hash lookups
 				Console.warn(self, "Failed to write metric value!", metric: {name: @name, value: value}, exception: error)
 				
 				return false

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/observer.rb

@@ -3,7 +3,6 @@
 # Released under the MIT License.
 # Copyright, 2026, by Samuel Williams.
 
-require "console"
 require_relative "schema"
 
 module Async
@@ -71,21 +70,6 @@ module Async
 			
 			# @attribute [IO::Buffer] The mapped buffer for shared memory.
 			attr :buffer
-			
-			# Set a field value.
-			#
-			# Writes the value to shared memory at the offset defined by the schema.
-			# Only fields defined in the schema will be written.
-			#
-			# @parameter field [Symbol] The field name to set.
-			# @parameter value [Numeric] The value to set.
-			def set(field, value)
-				if field = @schema[field]
-					@buffer.set_value(field.type, field.offset, value)
-				end
-			rescue => error
-				Console.warn(self, "Failed to set field in shared memory!", field: field, exception: error)
-			end
 		end
 	end
 end

data/lib/async/utilization/registry.rb

@@ -3,6 +3,9 @@
 # Released under the MIT License.
 # Copyright, 2026, by Samuel Williams.
 
+require "console"
+require_relative "namespace"
+
 module Async
 	module Utilization
 		# Registry for emitting utilization metrics.
@@ -20,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
 		# 	
@@ -35,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
@@ -47,81 +51,33 @@ 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
 			
 			# Set the observer for the registry.
 			#
-			# When an observer is set, it is notified of all current metric values
-			# so it can sync its state. The observer must implement `set(field, value)`.
-			# All cached metrics are invalidated when the observer changes.
+			# When an observer is set, all cached metrics are updated so they write
+			# directly to the observer's buffer. The observer must expose `schema`
+			# and `buffer` attributes.
 			#
-			# @parameter observer [#set] The observer to set.
+			# @parameter observer [Observer | Nil] The observer to set.
 			def observer=(observer)
 				@guard.synchronize do
-					# Invalidate all cached metrics
+					@observer = observer
+					
+					# Invalidate all cached metrics with new observer (or nil)
 					@metrics.each_value do |metric|
-						metric.invalidate
+						metric.observer = observer
 					end
 					
-					@observer = observer
+					# Console.info(self, "Observer assigned", observer: observer, metric_count: @metrics.size)
 				end
-				
-				# Notify observer of all current metric values (outside guard to avoid deadlock)
-				@metrics.each do |name, metric|
-					value = metric.guard.synchronize{metric.value}
-					observer.set(name, value)
-				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.
@@ -135,9 +91,17 @@ module Async
 				field = field.to_sym
 				
 				@guard.synchronize do
-					@metrics[field] ||= Metric.new(field, self)
+					@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/version.rb

@@ -7,6 +7,6 @@
 module Async
 	# @namespace
 	module Utilization
-		VERSION = "0.3.1"
+		VERSION = "0.4.0"
 	end
 end

data/lib/async/utilization.rb

@@ -5,6 +5,7 @@
 
 require_relative "utilization/version"
 require_relative "utilization/schema"
+require_relative "utilization/namespace"
 require_relative "utilization/registry"
 require_relative "utilization/observer"
 require_relative "utilization/metric"

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.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.
+
 ### v0.3.1
 
   - Remove unused `thread-local` dependency.
@@ -36,6 +45,22 @@ We welcome contributions to this project.
 4.  Push to the branch (`git push origin my-new-feature`).
 5.  Create new Pull Request.
 
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
+
 ### Developer Certificate of Origin
 
 In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.

data/releases.md

@@ -1,5 +1,14 @@
 # Releases
 
+## 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.
+
 ## v0.3.1
 
   - Remove unused `thread-local` dependency.

data/test/async/utilization/metric.rb

@@ -154,8 +154,8 @@ describe Async::Utilization::Metric do
 	end
 	
 	it "writes directly to shared memory when observer is set" do
-		registry.observer = observer
 		metric = registry.metric(:total_requests)
+		registry.observer = observer
 		
 		metric.set(42)
 		
@@ -216,22 +216,6 @@ describe Async::Utilization::Metric do
 		expect(metric1).to be == metric2
 	end
 	
-	it "falls back to observer.set when write_direct fails" do
-		registry.observer = observer
-		metric = registry.metric(:total_requests)
-		
-		# Force cache to be invalid by invalidating it
-		metric.invalidate
-		
-		# Set a value - should fall back to observer.set
-		metric.set(42)
-		expect(metric.value).to be == 42
-		
-		# Verify it was written to shared memory
-		buffer = IO::Buffer.map(File.open(shm_path, "r+b"), file_size, 0)
-		expect(buffer.get_value(:u64, 0)).to be == 42
-	end
-	
 	it "handles write errors gracefully" do
 		registry.observer = observer
 		metric = registry.metric(:total_requests)
@@ -239,10 +223,6 @@ describe Async::Utilization::Metric do
 		# Set a value first to build the cache
 		metric.set(10)
 		
-		# Verify cache is built
-		expect(metric.instance_variable_get(:@cache_valid)).to be == true
-		cached_buffer = metric.instance_variable_get(:@cached_buffer)
-		
 		# Create an invalid buffer that will raise an error
 		invalid_buffer = Object.new
 		def invalid_buffer.set_value(type, offset, value)
@@ -251,13 +231,10 @@ describe Async::Utilization::Metric do
 		
 		metric.instance_variable_set(:@cached_buffer, invalid_buffer)
 		
-		# Should not raise, but log warning and keep cache valid
+		# Should not raise, but log warning
 		metric.set(42)
 		expect(metric.value).to be == 42
 		
-		# Cache should remain valid (not invalidated on error)
-		expect(metric.instance_variable_get(:@cache_valid)).to be == true
-		
 		# Assert that a warning was logged
 		expect_console.to have_logged(
 			severity: be == :warn,
@@ -265,4 +242,27 @@ describe Async::Utilization::Metric do
 			message: be == "Failed to write metric value!"
 		)
 	end
+	
+	it "clears cache when observer is removed" do
+		registry.observer = observer
+		metric = registry.metric(:total_requests)
+		metric.set(10)
+		
+		# Remove observer — cache should be cleared
+		registry.observer = nil
+		
+		# Write should not go to the old buffer
+		metric.set(99)
+		
+		buffer = IO::Buffer.map(File.open(shm_path, "r+b"), file_size, 0)
+		expect(buffer.get_value(:u64, 0)).to be == 10
+		
+		# In-memory value is still updated
+		expect(metric.value).to be == 99
+		
+		# Re-attaching observer should sync the current value
+		registry.observer = observer
+		buffer = IO::Buffer.map(File.open(shm_path, "r+b"), file_size, 0)
+		expect(buffer.get_value(:u64, 0)).to be == 99
+	end
 end

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/observer.rb

@@ -4,13 +4,11 @@
 # Copyright, 2026, by Samuel Williams.
 
 require "sus"
-require "sus/fixtures/console/captured_logger"
 require "sus/fixtures/temporary_directory_context"
 require "async/utilization"
 require "fileutils"
 
 describe Async::Utilization::Observer do
-	include Sus::Fixtures::Console::CapturedLogger
 	include Sus::Fixtures::TemporaryDirectoryContext
 	
 	let(:shm_path) {File.join(root, "test.shm")}
@@ -41,68 +39,30 @@ describe Async::Utilization::Observer do
 		expect(observer.schema).to be == schema
 	end
 	
-	it "can write values to shared memory" do
-		observer.set(:total_requests, 42)
-		observer.set(:active_requests, 5)
-		
-		# Read back from file to verify
-		buffer = IO::Buffer.map(File.open(shm_path, "r+b"), file_size, 0)
-		expect(buffer.get_value(:u64, 0)).to be == 42
-		expect(buffer.get_value(:u32, 8)).to be == 5
-	end
-	
 	with "non-page-aligned offsets" do
 		let(:file_size) {IO::Buffer::PAGE_SIZE * 2}
 		let(:offset) {100}  # Not page-aligned
 		
-		it "handles non-page-aligned offsets" do
-			observer.set(:total_requests, 100)
-			observer.set(:active_requests, 20)
+		it "maps values at the correct offset" do
+			observer.buffer.set_value(:u64, schema[:total_requests].offset, 100)
+			observer.buffer.set_value(:u32, schema[:active_requests].offset, 20)
 			
-			# Read back from file at the correct offset
+			# Read back from file at the correct byte position
 			buffer = IO::Buffer.map(File.open(shm_path, "r+b"), file_size, 0)
-			expect(buffer.get_value(:u64, offset)).to be == 100
-			expect(buffer.get_value(:u32, offset + 8)).to be == 20
+			expect(buffer.get_value(:u64, offset + schema[:total_requests].offset)).to be == 100
+			expect(buffer.get_value(:u32, offset + schema[:active_requests].offset)).to be == 20
 		end
 	end
 	
-	it "ignores fields not in schema" do
-		# Should not raise an error
-		observer.set(:unknown_field, 999)
-		
-		# Verify nothing was written
-		buffer = IO::Buffer.map(File.open(shm_path, "r+b"), file_size, 0)
-		expect(buffer.get_value(:u64, 0)).to be == 0
-	end
-	
 	with "page-aligned offsets" do
 		let(:file_size) {page_size * 2}
 		let(:segment_size) {page_size}
 		
-		it "handles page-aligned offsets without slicing" do
-			expect(observer).to be_a(Async::Utilization::Observer)
-			observer.set(:total_requests, 123)
+		it "maps values at the correct offset" do
+			observer.buffer.set_value(:u64, schema[:total_requests].offset, 123)
 			
-			# Verify value was written
 			buffer = IO::Buffer.map(File.open(shm_path, "r+b"), file_size, 0)
-			expect(buffer.get_value(:u64, 0)).to be == 123
+			expect(buffer.get_value(:u64, schema[:total_requests].offset)).to be == 123
 		end
 	end
-	
-	it "handles errors gracefully when setting values" do
-		# Create an invalid buffer that will cause an error
-		# We'll mock the buffer to raise an error
-		buffer = observer.instance_variable_get(:@buffer)
-		expect(buffer).to receive(:set_value).and_raise(IOError, "Buffer error")
-		
-		# Should not raise, but log a warning
-		observer.set(:total_requests, 42)
-		
-		# Assert that a warning was logged
-		expect_console.to have_logged(
-			severity: be == :warn,
-			subject: be_a(Async::Utilization::Observer),
-			message: be == "Failed to set field in shared memory!"
-		)
-	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
@@ -56,44 +57,24 @@ describe Async::Utilization::Registry do
 		expect(registry.values[:test_field]).to be == 0
 	end
 	
-	it "can set an observer" do
-		observer = Object.new
-		def observer.set(field, value); end
-		
-		registry.set(:test_field, 10)
-		registry.observer = observer
-		
-		expect(registry.observer).to be == observer
-	end
-	
 	it "notifies observer when values change" do
-		values_set = []
-		
-		# Create a proper observer with schema
 		schema = Async::Utilization::Schema.build(test_field: :u64)
-		observer = Object.new
+		buffer = IO::Buffer.new(8)
 		
-		# Define methods on observer
-		observer.define_singleton_method(:set) do |field, value|
-			values_set << [field, value]
-		end
+		observer = Object.new
 		observer.define_singleton_method(:schema){schema}
-		observer.define_singleton_method(:buffer){nil}  # No buffer, so write_direct will return false
+		observer.define_singleton_method(:buffer){buffer}
 		
-		registry.set(:test_field, 5)
+		test_field_metric.set(5)
 		registry.observer = observer
 		
-		# Observer should be notified of existing values
-		expect(values_set).to be(:include?, [:test_field, 5])
+		# Buffer should be synced with the existing value on observer assignment
+		expect(buffer.get_value(:u64, 0)).to be == 5
 		
-		# Clear and test new changes
-		# Note: Since observer has no buffer, write_direct will return false
-		# and no notification will occur (as per new design)
-		values_set.clear
-		registry.increment(:test_field)
+		test_field_metric.increment
 		
-		# With no buffer, write_direct fails silently, so no notification
-		expect(values_set).to be == []
+		# Buffer should reflect the incremented value
+		expect(buffer.get_value(:u64, 0)).to be == 6
 	end
 	
 	it "uses metric method for fast path" do
@@ -103,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
@@ -117,12 +106,35 @@ describe Async::Utilization::Registry do
 		expect(registry.values).to have_keys(module_set_test: be == 99)
 	end
 	
-	it "can set observer" do
+	it "wires up existing metrics when observer is assigned" do
+		schema = Async::Utilization::Schema.build(test_field: :u64)
+		buffer = IO::Buffer.new(8)
+		observer = Object.new
+		observer.define_singleton_method(:schema){schema}
+		observer.define_singleton_method(:buffer){buffer}
+		
+		test_field_metric.set(7)
+		registry.observer = observer
+		
+		expect(buffer.get_value(:u64, 0)).to be == 7
+	end
+	
+	it "stops writing to buffer when observer is removed" do
+		schema = Async::Utilization::Schema.build(test_field: :u64)
+		buffer = IO::Buffer.new(8)
 		observer = Object.new
-		def observer.set(field, value); end
+		observer.define_singleton_method(:schema){schema}
+		observer.define_singleton_method(:buffer){buffer}
 		
 		registry.observer = observer
+		test_field_metric.set(5)
+		expect(buffer.get_value(:u64, 0)).to be == 5
+		
+		registry.observer = nil
+		test_field_metric.set(99)
 		
-		expect(registry.observer).to be == observer
+		# Buffer unchanged, in-memory value updated
+		expect(buffer.get_value(:u64, 0)).to be == 5
+		expect(registry.values[:test_field]).to be == 99
 	end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-utilization
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -58,6 +58,7 @@ 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
@@ -67,6 +68,7 @@ files:
 - 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
@@ -90,7 +92,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: High-performance utilization metrics for Async services using shared memory.
 test_files: []