async-utilization 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ddd4fc21308eeba6b47fbd44df20d4694ee4bd5b78488a44395d0ab5e2da500
-  data.tar.gz: 8699da59ebaa0497ca112cf4f1ca65805935d11061b9ed6e1475a56f05a58795
+  metadata.gz: 10d5277f8a02e1f72a8466b86dae5245d8beacf60f7310b5f4b2fbbe829ad2b2
+  data.tar.gz: 8e1519b41206468ffcd4c5197aecd0843882e5c637db9db24fce67f87fd34386
 SHA512:
-  metadata.gz: '079cbc3d3a93cda55ebcce48f93c23e5460db7ae8019336b442d0a24ffd783ec6e614cd2d36fc7c937f388cf729ce7d4d6944c5aefae754c4165560a4f353a98'
-  data.tar.gz: '049b0ea1ae9d8bc15c12aa69c3d595e32424d1d200003425067f70111f804079fda1f23ef21cc3ed0a0a0d698b36e3b00cbe0cb9ce3803dde197c8e03c8599b1'
+  metadata.gz: aff8c89a734ee90bb716186f4a9133373bc222c26a0b4bb089152a9bce6bd2d76105a91a6c99f3a5333be4afef83ba3c88637e64b69a2629ab185e94b6035a4a
+  data.tar.gz: 853481053488156d6baa7be3cff2f7c19e9bad60028e44649f96bfc978c07c173065bb0d8bd17105ae1248204d569bc115fcc0e146ce3ee25886b8efcc2580e9

data/lib/async/utilization/metric.rb

@@ -43,30 +43,38 @@ module Async
 				@cached_buffer = nil
 			end
 			
-			# Increment the metric value, optionally with a block that auto-decrements.
+			# Increment the metric value.
 			#
 			# 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)
+			def increment
 				@guard.synchronize do
 					@value += 1
 					write_direct(@value)
 				end
 				
-				if block_given?
-					begin
-						yield
-					ensure
-						# Decrement after block completes
-						decrement
-					end
-				end
-				
 				@value
 			end
 			
+			# Track an operation: increment before the block, decrement after it completes.
+			#
+			# Returns the block's return value. Use for active/count metrics that should
+			# reflect the number of operations currently in progress.
+			#
+			# @yield The operation to track.
+			# @returns [Object] The block's return value.
+			def track(&block)
+				raise ArgumentError, "block required" unless block_given?
+				
+				increment
+				begin
+					yield
+				ensure
+					decrement
+				end
+			end
+			
 			# Decrement the metric value.
 			#
 			# Uses the fast path (direct buffer write) when cache is valid and observer is available.

data/lib/async/utilization/registry.rb

@@ -3,8 +3,6 @@
 # Released under the MIT License.
 # Copyright, 2026, by Samuel Williams.
 
-require "thread/local"
-
 module Async
 	module Utilization
 		# Registry for emitting utilization metrics.
@@ -12,8 +10,9 @@ module Async
 		# 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.
+		# Registries should be explicitly created and passed to components that need them.
+		# In service contexts, registries are typically created via the evaluator and
+		# shared across components within the same service instance.
 		#
 		# 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.
@@ -23,7 +22,7 @@ module Async
 		# 	
 		# 	# Emit metrics - values tracked in registry
 		# 	registry.increment(:total_requests)
-		# 	registry.increment(:active_requests) do
+		# 	registry.track(:active_requests) do
 		# 		# Handle request - auto-decrements when block completes
 		# 	end
 		# 	
@@ -36,7 +35,6 @@ module Async
 		# 	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
@@ -95,15 +93,25 @@ module Async
 				metric(field).set(value)
 			end
 			
-			# Increment a field value, optionally with a block that auto-decrements.
+			# Increment a field value.
 			#
 			# 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)
+			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.

data/lib/async/utilization/version.rb

@@ -7,6 +7,6 @@
 module Async
 	# @namespace
 	module Utilization
-		VERSION = "0.1.0"
+		VERSION = "0.3.0"
 	end
 end

data/lib/async/utilization.rb

@@ -15,42 +15,9 @@ module Async
 	#
 	# 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.
+	# Registries should be explicitly created and passed to components that need them.
 	#
 	# 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/readme.md

@@ -14,6 +14,10 @@ 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.3.0
+
+  - Introduce `Metric#track{...}` for increment -\> decrement.
+
 ### v0.1.0
 
   - Initial implementation.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.3.0
+
+  - Introduce `Metric#track{...}` for increment -\> decrement.
+
 ## v0.1.0
 
   - Initial implementation.

data/test/async/utilization/metric.rb

@@ -29,28 +29,24 @@ describe Async::Utilization::Metric do
 		Async::Utilization::Observer.open(schema, shm_path, segment_size, offset)
 	end
 	
+	let(:registry) {Async::Utilization::Registry.new}
+	
 	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)
+		metric = registry.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)
+		registry.observer = observer
+		metric = registry.metric(:total_requests)
 		
 		value = metric.increment
 		expect(value).to be == 1
@@ -62,8 +58,8 @@ describe Async::Utilization::Metric do
 	end
 	
 	it "can decrement a metric" do
-		Async::Utilization.observer = observer
-		metric = Async::Utilization.metric(:total_requests)
+		registry.observer = observer
+		metric = registry.metric(:total_requests)
 		
 		metric.increment
 		metric.increment
@@ -74,8 +70,8 @@ describe Async::Utilization::Metric do
 	end
 	
 	it "can set a metric value" do
-		Async::Utilization.observer = observer
-		metric = Async::Utilization.metric(:total_requests)
+		registry.observer = observer
+		metric = registry.metric(:total_requests)
 		
 		metric.set(42)
 		expect(metric.value).to be == 42
@@ -84,23 +80,62 @@ describe Async::Utilization::Metric do
 		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)
+	it "can track an operation with auto-decrement" do
+		registry.observer = observer
+		metric = registry.metric(:active_requests)
 		
-		metric.increment do
+		metric.track 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)
+	it "returns the metric value when increment is called" do
+		registry.observer = observer
+		metric = registry.metric(:total_requests)
+		
+		result = metric.increment
+		expect(result).to be == 1
+		expect(result).to be == metric.value
+		
+		result = metric.increment
+		expect(result).to be == 2
+		expect(result).to be == metric.value
+	end
+	
+	it "returns the block's return value when track is called" do
+		registry.observer = observer
+		metric = registry.metric(:active_requests)
+		
+		# Block returns a string
+		result = metric.track do
+			"connection_object"
+		end
+		expect(result).to be == "connection_object"
+		expect(metric.value).to be == 0 # Should be decremented after block
+		
+		# Block returns an integer
+		result = metric.track do
+			42
+		end
+		expect(result).to be == 42
+		expect(metric.value).to be == 0 # Should be decremented after block
+		
+		# Block returns nil
+		result = metric.track do
+			nil
+		end
+		expect(result).to be == nil
+		expect(metric.value).to be == 0 # Should be decremented after block
+	end
+	
+	it "decrements even if track block raises an error" do
+		registry.observer = observer
+		metric = registry.metric(:active_requests)
 		
 		begin
-			metric.increment do
+			metric.track do
 				raise "Test error"
 			end
 		rescue => error
@@ -110,9 +145,17 @@ describe Async::Utilization::Metric do
 		expect(metric.value).to be == 0
 	end
 	
+	it "raises ArgumentError when track is called without a block" do
+		metric = registry.metric(:active_requests)
+		
+		expect do
+			metric.track
+		end.to raise_exception(ArgumentError, message: be == "block required")
+	end
+	
 	it "writes directly to shared memory when observer is set" do
-		Async::Utilization.observer = observer
-		metric = Async::Utilization.metric(:total_requests)
+		registry.observer = observer
+		metric = registry.metric(:total_requests)
 		
 		metric.set(42)
 		
@@ -122,8 +165,8 @@ describe Async::Utilization::Metric do
 	end
 	
 	it "invalidates cache when observer changes" do
-		Async::Utilization.observer = observer
-		metric = Async::Utilization.metric(:total_requests)
+		registry.observer = observer
+		metric = registry.metric(:total_requests)
 		
 		# Set a value - cache should be built
 		metric.set(10)
@@ -139,7 +182,7 @@ describe Async::Utilization::Metric do
 		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
+		registry.observer = new_observer
 		
 		# Set a new value - cache should be rebuilt
 		metric.set(20)
@@ -151,7 +194,7 @@ describe Async::Utilization::Metric do
 	end
 	
 	it "works without an observer" do
-		metric = Async::Utilization.metric(:total_requests)
+		metric = registry.metric(:total_requests)
 		
 		# Should work fine without observer (uses fallback path)
 		metric.increment
@@ -161,21 +204,21 @@ describe Async::Utilization::Metric do
 		expect(metric.value).to be == 5
 		
 		# Set observer and verify it works with fast path
-		Async::Utilization.observer = observer
+		registry.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)
+		metric1 = registry.metric(:total_requests)
+		metric2 = registry.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)
+		registry.observer = observer
+		metric = registry.metric(:total_requests)
 		
 		# Force cache to be invalid by invalidating it
 		metric.invalidate
@@ -190,8 +233,8 @@ describe Async::Utilization::Metric do
 	end
 	
 	it "handles write errors gracefully" do
-		Async::Utilization.observer = observer
-		metric = Async::Utilization.metric(:total_requests)
+		registry.observer = observer
+		metric = registry.metric(:total_requests)
 		
 		# Set a value first to build the cache
 		metric.set(10)

data/test/async/utilization/registry.rb

@@ -37,17 +37,17 @@ describe Async::Utilization::Registry do
 		expect(registry.values[:test_field]).to be == 42
 	end
 	
-	it "can auto-decrement with a block" do
-		registry.increment(:test_field) do
+	it "can track an operation with auto-decrement" do
+		registry.track(: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
+	it "decrements even if track block raises an error" do
 		begin
-			registry.increment(:test_field) do
+			registry.track(:test_field) do
 				raise "Error!"
 			end
 		rescue

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-utilization
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -97,7 +97,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="