async-utilization 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5ddd4fc21308eeba6b47fbd44df20d4694ee4bd5b78488a44395d0ab5e2da500
+  data.tar.gz: 8699da59ebaa0497ca112cf4f1ca65805935d11061b9ed6e1475a56f05a58795
+SHA512:
+  metadata.gz: '079cbc3d3a93cda55ebcce48f93c23e5460db7ae8019336b442d0a24ffd783ec6e614cd2d36fc7c937f388cf729ce7d4d6944c5aefae754c4165560a4f353a98'
+  data.tar.gz: '049b0ea1ae9d8bc15c12aa69c3d595e32424d1d200003425067f70111f804079fda1f23ef21cc3ed0a0a0d698b36e3b00cbe0cb9ce3803dde197c8e03c8599b1'

data/lib/async/utilization/metric.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Async
+	module Utilization
+		# A cached metric reference that avoids hash lookups on the fast path.
+		#
+		# This class caches all the details needed to write directly to shared memory,
+		# including the buffer, offset, and type. When the observer changes, the cache
+		# is invalidated and rebuilt on the next access.
+		class Metric
+			# 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)
+				@name = name.to_sym
+				@registry = registry
+				@value = 0
+				@cache_valid = false
+				@cached_field_info = nil
+				@cached_buffer = nil
+				@guard = Mutex.new
+			end
+			
+			# @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
+			
+			# Invalidate the cached field information.
+			#
+			# Called when the observer changes to force cache rebuild.
+			def invalidate
+				@cache_valid = false
+				@cached_field_info = nil
+				@cached_buffer = nil
+			end
+			
+			# Increment the metric value, optionally with a block that auto-decrements.
+			#
+			# Uses the fast path (direct buffer write) when cache is valid and observer is available.
+			#
+			# @yield Optional block - if provided, decrements the field after the block completes.
+			# @returns [Integer] The new value of the field.
+			def increment(&block)
+				@guard.synchronize do
+					@value += 1
+					write_direct(@value)
+				end
+				
+				if block_given?
+					begin
+						yield
+					ensure
+						# Decrement after block completes
+						decrement
+					end
+				end
+				
+				@value
+			end
+			
+			# Decrement 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 decrement
+				@guard.synchronize do
+					@value -= 1
+					write_direct(@value)
+				end
+				
+				@value
+			end
+			
+			# Set the metric value.
+			#
+			# Uses the fast path (direct buffer write) when cache is valid and observer is available.
+			#
+			# @parameter value [Numeric] The value to set.
+			def set(value)
+				@guard.synchronize do
+					@value = value
+					write_direct(@value)
+				end
+			end
+			
+			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
+			# first. If there's no observer or buffer, silently does nothing.
+			#
+			# @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)
+				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
+			end
+		end
+	end
+end

data/lib/async/utilization/observer.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "console"
+require_relative "schema"
+
+module Async
+	module Utilization
+		# Shared memory observer for utilization metrics.
+		#
+		# Writes metrics to shared memory using a schema to define the
+		# serialization layout. The schema is required to know how to
+		# serialize values efficiently.
+		class Observer
+			# Open a shared memory observer from a file.
+			#
+			# Maps the shared memory file and creates an Observer instance.
+			# The file descriptor is closed after mapping - the memory mapping
+			# persists independently on Unix/Linux systems.
+			#
+			# Note: mmap requires page-aligned offsets and sizes. This method handles
+			# non-page-aligned offsets by mapping from the nearest page boundary
+			# and adjusting field offsets accordingly.
+			#
+			# @parameter schema [Schema] The schema defining field types and layout.
+			# @parameter path [String] Path to the shared memory file.
+			# @parameter size [Integer] Size of the shared memory region to map.
+			# @parameter offset [Integer] Offset into the shared memory buffer.
+			# @returns [Observer] A new Observer instance.
+			def self.open(schema, path, size, offset)
+				page_size = IO::Buffer::PAGE_SIZE
+				
+				# Round offset down to nearest page boundary:
+				page_aligned_offset = (offset / page_size) * page_size
+				offset_adjustment = offset - page_aligned_offset
+				
+				# Calculate how many pages we need to cover the segment:
+				segment_end = offset + size
+				page_aligned_end = ((segment_end + page_size - 1) / page_size) * page_size
+				
+				# Ensure we map at least one full page:
+				map_size = [page_aligned_end - page_aligned_offset, page_size].max
+				
+				buffer = File.open(path, "r+b") do |file|
+					mapped_buffer = IO::Buffer.map(file, map_size, page_aligned_offset)
+					
+					# If we had to adjust the offset, create a view into the buffer:
+					if offset_adjustment > 0 || map_size > size
+						mapped_buffer.slice(offset_adjustment, size)
+					else
+						mapped_buffer
+					end
+				end
+				
+				new(schema, buffer)
+			end
+			
+			# Initialize a new shared memory observer.
+			#
+			# @parameter schema [Schema] The schema defining field types and layout.
+			# @parameter buffer [IO::Buffer] The mapped buffer for shared memory.
+			def initialize(schema, buffer)
+				@schema = schema
+				@buffer = buffer
+			end
+			
+			# @attribute [Schema] The schema used for serialization.
+			attr :schema
+			
+			# @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

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "thread/local"
+
+module Async
+	module Utilization
+		# Registry for emitting utilization metrics.
+		#
+		# The registry tracks values directly and notifies a registered observer
+		# when values change. The observer (like Observer) can write to its backend.
+		#
+		# Each thread gets its own instance of the registry, providing
+		# thread-local behavior through the thread-local gem.
+		#
+		# When an observer is added, it is immediately notified of all current values
+		# so it can sync its state. When values change, the observer is notified.
+		#
+		# @example Create a registry and emit metrics:
+		# 	registry = Async::Utilization::Registry.new
+		# 	
+		# 	# Emit metrics - values tracked in registry
+		# 	registry.increment(:total_requests)
+		# 	registry.increment(:active_requests) do
+		# 		# Handle request - auto-decrements when block completes
+		# 	end
+		# 	
+		# 	# Add shared memory observer when supervisor connects
+		# 	# Observer will be notified of all current values automatically
+		# 	schema = Async::Utilization::Schema.build(
+		# 		total_requests: :u64,
+		# 		active_requests: :u32
+		# 	)
+		# 	observer = Async::Utilization::Observer.open(schema, "/path/to/shm", 4096, 0)
+		# 	registry.observer = observer
+		class Registry
+			extend Thread::Local
+			
+			# Initialize a new registry.
+			def initialize
+				@observer = nil
+				@metrics = {}
+				
+				@guard = Mutex.new
+			end
+			
+			# @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}
+				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.
+			#
+			# @parameter observer [#set] The observer to set.
+			def observer=(observer)
+				@guard.synchronize do
+					# Invalidate all cached metrics
+					@metrics.each_value do |metric|
+						metric.invalidate
+					end
+					
+					@observer = observer
+				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, optionally with a block that auto-decrements.
+			#
+			# Delegates to the metric instance for the given field.
+			#
+			# @parameter field [Symbol] The field name to increment.
+			# @yield Optional block - if provided, decrements the field after the block completes.
+			# @returns [Integer] The new value of the field.
+			def increment(field, &block)
+				metric(field).increment(&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.
+			#
+			# Returns a {Metric} instance that caches all details needed for fast writes.
+			# Metrics are cached per field and invalidated when the observer changes.
+			#
+			# @parameter field [Symbol] The field name to get a metric for.
+			# @returns [Metric] A metric instance for the given field.
+			def metric(field)
+				field = field.to_sym
+				
+				@guard.synchronize do
+					@metrics[field] ||= Metric.new(field, self)
+				end
+			end
+		end
+	end
+end

data/lib/async/utilization/schema.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Async
+	module Utilization
+		# Defines a schema for shared memory serialization.
+		#
+		# The schema defines the layout and types for serializing utilization
+		# metrics to shared memory. It's only needed when using Observer for
+		# shared memory storage - the Registry itself doesn't require a schema.
+		#
+		# @example Assign a schema to an observer:
+		# 	schema = Async::Utilization::Schema.build(
+		# 		total_requests: :u64,
+		# 		active_requests: :u32,
+		# 	)
+		# 	
+		# 	registry = Async::Utilization::Registry.new
+		# 	observer = Async::Utilization::Observer.open(schema, "/path/to/shm", 4096, 0)
+		# 	registry.observer = observer
+		class Schema
+			# Represents a field in the schema with its name, type, and offset.
+			Field = Data.define(:name, :type, :offset)
+			
+			# Build a schema from raw fields.
+			#
+			# Factory method that takes a hash of field names to types and creates
+			# Field instances with calculated offsets.
+			#
+			# @parameter fields [Hash] Hash mapping field names to IO::Buffer type symbols (:u32, :u64, :i32, :i64, :f32, :f64).
+			# @returns [Schema] A new schema instance.
+			def self.build(fields)
+				field_instances = []
+				offset = 0
+				
+				fields.each do |key, type|
+					field_instances << Field.new(name: key.to_sym, type: type, offset: offset)
+					offset += IO::Buffer.size_of(type)
+				end
+				
+				new(field_instances)
+			end
+			
+			# Initialize a new schema.
+			#
+			# @parameter fields [Array<Field>] Array of Field instances.
+			def initialize(fields)
+				@fields = fields.freeze
+				
+				# Build an offsets cache mapping field names to Field objects for fast lookup
+				@offsets = {}
+				@fields.each do |field|
+					@offsets[field.name] = field
+				end
+				@offsets.freeze
+			end
+			
+			# @attribute [Array<Field>] The fields in this schema.
+			attr :fields
+			
+			# Get field information for a given field.
+			#
+			# @parameter field [Symbol] The field name to look up.
+			# @returns [Field] Field object containing name, type and offset, or nil if field not found.
+			def [](field)
+				@offsets[field.to_sym]
+			end
+			
+			# Convert schema to array format for shared memory.
+			#
+			# @returns [Array] Array of [key, type, offset] tuples.
+			def to_a
+				@fields.map do |field|
+					[field.name, field.type, field.offset]
+				end
+			end
+		end
+	end
+end

data/lib/async/utilization/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+# @namespace
+module Async
+	# @namespace
+	module Utilization
+		VERSION = "0.1.0"
+	end
+end

data/lib/async/utilization.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "utilization/version"
+require_relative "utilization/schema"
+require_relative "utilization/registry"
+require_relative "utilization/observer"
+require_relative "utilization/metric"
+
+# @namespace
+module Async
+	# Provides high-performance utilization metrics for Async services using shared memory.
+	#
+	# This module provides a convenient interface for tracking utilization metrics
+	# that can be synchronized to shared memory for inter-process communication.
+	# Each thread gets its own instance of the underlying {Registry}, providing
+	# thread-local behavior.
+	#
+	# See the {file:guides/getting-started/readme.md Getting Started} guide for usage examples.
+	module Utilization
+		# Set the observer for utilization metrics.
+		#
+		# 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)`.
+		#
+		# Delegates to the thread-local {Registry} instance.
+		#
+		# @parameter observer [#set] The observer to set.
+		def self.observer=(observer)
+			Registry.instance.observer = observer
+		end
+		
+		# Get a cached metric reference for a field.
+		#
+		# Returns a {Metric} instance that caches all details needed for fast writes
+		# to shared memory, avoiding hash lookups on the fast path.
+		#
+		# This is the recommended way to access metrics for optimal performance.
+		#
+		# Delegates to the thread-local {Registry} instance.
+		#
+		# @parameter field [Symbol] The field name to get a metric for.
+		# @returns [Metric] A metric instance for the given field.
+		# @example Get a metric and increment it:
+		# 	current_requests = Async::Utilization.metric(:current_requests)
+		# 	current_requests.increment
+		# 	current_requests.increment do
+		# 		# Handle request - auto-decrements when block completes
+		# 	end
+		def self.metric(field)
+			Registry.instance.metric(field)
+		end
+	end
+end

data/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 2026, by Samuel Williams.  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/readme.md

@@ -0,0 +1,37 @@
+# Async::Utilization
+
+High-performance utilization metrics for Async services using shared memory.
+
+[![Development Status](https://github.com/socketry/async-utilization/workflows/Test/badge.svg)](https://github.com/socketry/async-utilization/actions?workflow=Test)
+
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/async-utilization/) for more details.
+
+  - [Getting Started](https://socketry.github.io/async-utilization/guides/getting-started/index) - This guide explains how to get started with `async-utilization` to track high-performance utilization metrics for Async services using shared memory.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/async-utilization/releases/index) for all releases.
+
+### v0.1.0
+
+  - Initial implementation.
+
+## Contributing
+
+We welcome contributions to this project.
+
+1.  Fork it.
+2.  Create your feature branch (`git checkout -b my-new-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.
+
+### 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.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

data/releases.md

@@ -0,0 +1,5 @@
+# Releases
+
+## v0.1.0
+
+  - Initial implementation.

data/test/async/utilization/metric.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "sus"
+require "sus/fixtures/console/captured_logger"
+require "sus/fixtures/temporary_directory_context"
+require "async/utilization"
+
+describe Async::Utilization::Metric do
+	include Sus::Fixtures::Console::CapturedLogger
+	include Sus::Fixtures::TemporaryDirectoryContext
+	
+	let(:shm_path) {File.join(root, "test.shm")}
+	let(:schema) do
+		Async::Utilization::Schema.build(
+			total_requests: :u64,
+			active_requests: :u32
+		)
+	end
+	
+	let(:page_size) {IO::Buffer::PAGE_SIZE}
+	let(:segment_size) {512}
+	let(:file_size) {[segment_size, page_size].max}
+	let(:offset) {0}
+	
+	let(:observer) do
+		Async::Utilization::Observer.open(schema, shm_path, segment_size, offset)
+	end
+	
+	before do
+		File.open(shm_path, "w+b") do |file|
+			file.truncate(file_size)
+		end
+		
+		# Reset the registry to ensure clean state between tests
+		registry = Async::Utilization::Registry.instance
+		registry.instance_variable_set(:@values, Hash.new(0))
+		registry.instance_variable_set(:@metrics, {})
+		registry.instance_variable_set(:@observer, nil)
+	end
+	
+	it "can create a metric from a field name" do
+		metric = Async::Utilization.metric(:total_requests)
+		
+		expect(metric).to be_a(Async::Utilization::Metric)
+		expect(metric.name).to be == :total_requests
+	end
+	
+	it "can increment a metric" do
+		Async::Utilization.observer = observer
+		metric = Async::Utilization.metric(:total_requests)
+		
+		value = metric.increment
+		expect(value).to be == 1
+		expect(metric.value).to be == 1
+		
+		value = metric.increment
+		expect(value).to be == 2
+		expect(metric.value).to be == 2
+	end
+	
+	it "can decrement a metric" do
+		Async::Utilization.observer = observer
+		metric = Async::Utilization.metric(:total_requests)
+		
+		metric.increment
+		metric.increment
+		
+		value = metric.decrement
+		expect(value).to be == 1
+		expect(metric.value).to be == 1
+	end
+	
+	it "can set a metric value" do
+		Async::Utilization.observer = observer
+		metric = Async::Utilization.metric(:total_requests)
+		
+		metric.set(42)
+		expect(metric.value).to be == 42
+		
+		metric.set(100)
+		expect(metric.value).to be == 100
+	end
+	
+	it "can increment with auto-decrement block" do
+		Async::Utilization.observer = observer
+		metric = Async::Utilization.metric(:active_requests)
+		
+		metric.increment do
+			expect(metric.value).to be == 1
+		end
+		
+		expect(metric.value).to be == 0
+	end
+	
+	it "decrements even if block raises an error" do
+		Async::Utilization.observer = observer
+		metric = Async::Utilization.metric(:active_requests)
+		
+		begin
+			metric.increment do
+				raise "Test error"
+			end
+		rescue => error
+			expect(error.message).to be == "Test error"
+		end
+		
+		expect(metric.value).to be == 0
+	end
+	
+	it "writes directly to shared memory when observer is set" do
+		Async::Utilization.observer = observer
+		metric = Async::Utilization.metric(:total_requests)
+		
+		metric.set(42)
+		
+		# 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
+	end
+	
+	it "invalidates cache when observer changes" do
+		Async::Utilization.observer = observer
+		metric = Async::Utilization.metric(:total_requests)
+		
+		# Set a value - cache should be built
+		metric.set(10)
+		expect(metric.value).to be == 10
+		
+		# Create a new observer with different schema
+		new_schema = Async::Utilization::Schema.build(
+			total_requests: :u64,
+			active_requests: :u32
+		)
+		new_shm_path = File.join(root, "test2.shm")
+		File.open(new_shm_path, "w+b"){|f| f.truncate(file_size)}
+		new_observer = Async::Utilization::Observer.open(new_schema, new_shm_path, segment_size, 0)
+		
+		# Change observer - cache should be invalidated
+		Async::Utilization.observer = new_observer
+		
+		# Set a new value - cache should be rebuilt
+		metric.set(20)
+		expect(metric.value).to be == 20
+		
+		# Verify it was written to the new shared memory file
+		buffer = IO::Buffer.map(File.open(new_shm_path, "r+b"), file_size, 0)
+		expect(buffer.get_value(:u64, 0)).to be == 20
+	end
+	
+	it "works without an observer" do
+		metric = Async::Utilization.metric(:total_requests)
+		
+		# Should work fine without observer (uses fallback path)
+		metric.increment
+		expect(metric.value).to be == 1
+		
+		metric.set(5)
+		expect(metric.value).to be == 5
+		
+		# Set observer and verify it works with fast path
+		Async::Utilization.observer = observer
+		metric.set(10)
+		expect(metric.value).to be == 10
+	end
+	
+	it "returns the same metric instance for the same field" do
+		metric1 = Async::Utilization.metric(:total_requests)
+		metric2 = Async::Utilization.metric(:total_requests)
+		
+		expect(metric1).to be == metric2
+	end
+	
+	it "falls back to observer.set when write_direct fails" do
+		Async::Utilization.observer = observer
+		metric = Async::Utilization.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
+		Async::Utilization.observer = observer
+		metric = Async::Utilization.metric(:total_requests)
+		
+		# 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)
+			raise IOError, "Buffer error"
+		end
+		
+		metric.instance_variable_set(:@cached_buffer, invalid_buffer)
+		
+		# Should not raise, but log warning and keep cache valid
+		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,
+			subject: be_a(Async::Utilization::Metric),
+			message: be == "Failed to write metric value!"
+		)
+	end
+end

data/test/async/utilization/observer.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# 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")}
+	let(:schema) do
+		Async::Utilization::Schema.build(
+			total_requests: :u64,
+			active_requests: :u32
+		)
+	end
+	
+	let(:page_size) {IO::Buffer::PAGE_SIZE}
+	let(:segment_size) {512}
+	let(:file_size) {[segment_size, page_size].max}
+	let(:offset) {0}
+	
+	let(:observer) do
+		Async::Utilization::Observer.open(schema, shm_path, segment_size, offset)
+	end
+	
+	before do
+		File.open(shm_path, "w+b") do |file|
+			file.truncate(file_size)
+		end
+	end
+	
+	it "can create an observer from a file" do
+		expect(observer).to be_a(Async::Utilization::Observer)
+		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)
+			
+			# Read back from file at the correct offset
+			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
+		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)
+			
+			# 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
+		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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "sus"
+require "async/utilization"
+
+describe Async::Utilization::Registry do
+	let(:registry) {Async::Utilization::Registry.new}
+	
+	it "can increment a value" do
+		value = registry.increment(:test_field)
+		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)
+		
+		expect(registry.values[:test_field]).to be == 3
+	end
+	
+	it "can decrement a value" do
+		registry.increment(:test_field)
+		registry.increment(:test_field)
+		
+		value = registry.decrement(:test_field)
+		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)
+		expect(registry.values[:test_field]).to be == 42
+	end
+	
+	it "can auto-decrement with a block" do
+		registry.increment(:test_field) do
+			expect(registry.values[:test_field]).to be == 1
+		end
+		
+		expect(registry.values[:test_field]).to be == 0
+	end
+	
+	it "decrements even if block raises an error" do
+		begin
+			registry.increment(:test_field) do
+				raise "Error!"
+			end
+		rescue
+		end
+		
+		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
+		
+		# Define methods on observer
+		observer.define_singleton_method(:set) do |field, value|
+			values_set << [field, value]
+		end
+		observer.define_singleton_method(:schema){schema}
+		observer.define_singleton_method(:buffer){nil}  # No buffer, so write_direct will return false
+		
+		registry.set(:test_field, 5)
+		registry.observer = observer
+		
+		# Observer should be notified of existing values
+		expect(values_set).to be(:include?, [:test_field, 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)
+		
+		# With no buffer, write_direct fails silently, so no notification
+		expect(values_set).to be == []
+	end
+	
+	it "uses metric method for fast path" do
+		registry.metric(:module_test).increment
+		registry.metric(:module_test).increment
+		
+		expect(registry.values).to have_keys(module_test: be == 2)
+	end
+	
+	it "can use metric for decrement" do
+		registry.metric(:module_decrement_test).increment
+		registry.metric(:module_decrement_test).increment
+		registry.metric(:module_decrement_test).decrement
+		
+		expect(registry.values).to have_keys(module_decrement_test: be == 1)
+	end
+	
+	it "can use metric for set" do
+		registry.metric(:module_set_test).set(99)
+		
+		expect(registry.values).to have_keys(module_set_test: be == 99)
+	end
+	
+	it "can set observer" do
+		observer = Object.new
+		def observer.set(field, value); end
+		
+		registry.observer = observer
+		
+		expect(registry.observer).to be == observer
+	end
+end

data/test/async/utilization/schema.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "sus"
+require "async/utilization"
+
+describe Async::Utilization::Schema do
+	it "can build a schema from fields" do
+		schema = Async::Utilization::Schema.build(
+			total_requests: :u64,
+			active_requests: :u32
+		)
+		
+		expect(schema).to be_a(Async::Utilization::Schema)
+		expect(schema.fields.size).to be == 2
+	end
+	
+	it "calculates offsets correctly" do
+		schema = Async::Utilization::Schema.build(
+			total_requests: :u64,
+			active_requests: :u32
+		)
+		
+		field1 = schema[:total_requests]
+		field2 = schema[:active_requests]
+		
+		expect(field1).to be_a(Async::Utilization::Schema::Field)
+		expect(field1.name).to be == :total_requests
+		expect(field1.type).to be == :u64
+		expect(field1.offset).to be == 0
+		
+		expect(field2).to be_a(Async::Utilization::Schema::Field)
+		expect(field2.name).to be == :active_requests
+		expect(field2.type).to be == :u32
+		expect(field2.offset).to be == 8  # u64 is 8 bytes
+	end
+	
+	it "can convert to array format" do
+		schema = Async::Utilization::Schema.build(
+			total_requests: :u64,
+			active_requests: :u32
+		)
+		
+		array = schema.to_a
+		expect(array).to be == [
+			[:total_requests, :u64, 0],
+			[:active_requests, :u32, 8]
+		]
+	end
+	
+	it "returns nil for unknown fields" do
+		schema = Async::Utilization::Schema.build(
+			total_requests: :u64
+		)
+		
+		expect(schema[:unknown_field]).to be_nil
+	end
+end

data/test/async/utilization.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "sus"
+require "async/utilization"
+
+describe Async::Utilization do
+	it "has a version number" do
+		expect(Async::Utilization::VERSION).to be =~ /\d+\.\d+\.\d+/
+	end
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: async-utilization
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Samuel Williams
+bindir: bin
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIE2DCCA0CgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMRgwFgYDVQQDDA9zYW11
+  ZWwud2lsbGlhbXMxHTAbBgoJkiaJk/IsZAEZFg1vcmlvbnRyYW5zZmVyMRIwEAYK
+  CZImiZPyLGQBGRYCY28xEjAQBgoJkiaJk/IsZAEZFgJuejAeFw0yMjA4MDYwNDUz
+  MjRaFw0zMjA4MDMwNDUzMjRaMGExGDAWBgNVBAMMD3NhbXVlbC53aWxsaWFtczEd
+  MBsGCgmSJomT8ixkARkWDW9yaW9udHJhbnNmZXIxEjAQBgoJkiaJk/IsZAEZFgJj
+  bzESMBAGCgmSJomT8ixkARkWAm56MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIB
+  igKCAYEAomvSopQXQ24+9DBB6I6jxRI2auu3VVb4nOjmmHq7XWM4u3HL+pni63X2
+  9qZdoq9xt7H+RPbwL28LDpDNflYQXoOhoVhQ37Pjn9YDjl8/4/9xa9+NUpl9XDIW
+  sGkaOY0eqsQm1pEWkHJr3zn/fxoKPZPfaJOglovdxf7dgsHz67Xgd/ka+Wo1YqoE
+  e5AUKRwUuvaUaumAKgPH+4E4oiLXI4T1Ff5Q7xxv6yXvHuYtlMHhYfgNn8iiW8WN
+  XibYXPNP7NtieSQqwR/xM6IRSoyXKuS+ZNGDPUUGk8RoiV/xvVN4LrVm9upSc0ss
+  RZ6qwOQmXCo/lLcDUxJAgG95cPw//sI00tZan75VgsGzSWAOdjQpFM0l4dxvKwHn
+  tUeT3ZsAgt0JnGqNm2Bkz81kG4A2hSyFZTFA8vZGhp+hz+8Q573tAR89y9YJBdYM
+  zp0FM4zwMNEUwgfRzv1tEVVUEXmoFCyhzonUUw4nE4CFu/sE3ffhjKcXcY//qiSW
+  xm4erY3XAgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
+  BBYEFO9t7XWuFf2SKLmuijgqR4sGDlRsMC4GA1UdEQQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEBCwUAA4IBgQB5sxkE
+  cBsSYwK6fYpM+hA5B5yZY2+L0Z+27jF1pWGgbhPH8/FjjBLVn+VFok3CDpRqwXCl
+  xCO40JEkKdznNy2avOMra6PFiQyOE74kCtv7P+Fdc+FhgqI5lMon6tt9rNeXmnW/
+  c1NaMRdxy999hmRGzUSFjozcCwxpy/LwabxtdXwXgSay4mQ32EDjqR1TixS1+smp
+  8C/NCWgpIfzpHGJsjvmH2wAfKtTTqB9CVKLCWEnCHyCaRVuKkrKjqhYCdmMBqCws
+  JkxfQWC+jBVeG9ZtPhQgZpfhvh+6hMhraUYRQ6XGyvBqEUe+yo6DKIT3MtGE2+CP
+  eX9i9ZWBydWb8/rvmwmX2kkcBbX0hZS1rcR593hGc61JR6lvkGYQ2MYskBveyaxt
+  Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
+  voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
+  -----END CERTIFICATE-----
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: console
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: thread-local
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/async/utilization.rb
+- lib/async/utilization/metric.rb
+- lib/async/utilization/observer.rb
+- lib/async/utilization/registry.rb
+- lib/async/utilization/schema.rb
+- lib/async/utilization/version.rb
+- license.md
+- readme.md
+- releases.md
+- test/async/utilization.rb
+- test/async/utilization/metric.rb
+- test/async/utilization/observer.rb
+- test/async/utilization/registry.rb
+- test/async/utilization/schema.rb
+homepage: https://github.com/socketry/async-utilization
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://socketry.github.io/async-utilization/
+  source_code_uri: https://github.com/socketry/async-utilization.git
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: High-performance utilization metrics for Async services using shared memory.
+test_files: []