Prefer cached fast path for buffer writes.

Author: samuel-williams-shopify

guides/getting-started/readme.md

@@ -16,22 +16,27 @@ $ bundle add async-utilization
 
 The key components are:
 
-- {ruby Async::Utilization::Interface}: Thread-local singleton for emitting metrics
-- {ruby Async::Utilization::Schema}: Defines the binary layout for serialization
-- {ruby Async::Utilization::Observer}: Writes metrics to shared memory using the schema
+- {ruby Async::Utilization::Interface}: Thread-local singleton for emitting metrics.
+- {ruby Async::Utilization::Schema}: Defines the binary layout for serialization.
+- {ruby Async::Utilization::Observer}: Writes metrics to shared memory using the schema.
+- {ruby Async::Utilization::Metric}: Caches metric value and fast path for direct buffer updates.
 
 ## Basic Usage
 
-The simplest way to use `async-utilization` is to emit metrics directly:
+The recommended way to use `async-utilization` is to get a cached metric reference and use it:
 
 ```ruby
 require "async/utilization"
 
-# Increment a metric
-Async::Utilization.increment(:total_requests)
+# Get metrics:
+total_requests = Async::Utilization.metric(:total_requests)
+active_requests = Async::Utilization.metric(:active_requests)
 
-# Increment with auto-decrement
-Async::Utilization.increment(:active_requests) do
+# Increment a metric:
+total_requests.increment
+
+# Increment with auto-decrement:
+active_requests.increment do
 	# Handle request - automatically decrements when block completes
 end
 ```
@@ -63,8 +68,9 @@ observer = Async::Utilization::Observer.open(
 # Set observer - metrics will now be written to shared memory
 Async::Utilization.observer = observer
 
-# Now all metrics are written to shared memory
-Async::Utilization.increment(:total_requests)
+# All metrics are written directly to shared memory:
+total_requests = Async::Utilization.metric(:total_requests)
+total_requests.increment
 ```
 
 The observer automatically handles page alignment requirements for memory mapping, so you can use any segment size and offset. The supervisor process can then read these metrics from shared memory to aggregate utilization across all workers.

lib/async/utilization.rb

@@ -7,50 +7,50 @@
 require_relative "utilization/schema"
 require_relative "utilization/interface"
 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 {Interface}, providing
+	# thread-local behavior.
+	#
+	# See the {file:guides/getting-started/readme.md Getting Started} guide for usage examples.
 	module Utilization
-		# Increment a field value, optionally with a block that auto-decrements.
-		#
-		# Delegates to the thread-local {Interface} instance.
+		# Set the observer for utilization metrics.
 		#
-		# @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 self.increment(...)
-			Interface.instance.increment(...)
-		end
-		
-		# Decrement a field value.
+		# 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 {Interface} instance.
 		#
-		# @parameter field [Symbol] The field name to decrement.
-		# @returns [Integer] The new value of the field.
-		def self.decrement(...)
-			Interface.instance.decrement(...)
+		# @parameter observer [#set] The observer to set.
+		def self.observer=(observer)
+			Interface.instance.observer = observer
 		end
 
-		# Set a field value.
+		# Get a cached metric reference for a field.
 		#
-		# Delegates to the thread-local {Interface} instance.
+		# Returns a {Metric} instance that caches all details needed for fast writes
+		# to shared memory, avoiding hash lookups on the fast path.
 		#
-		# @parameter field [Symbol] The field name to set.
-		# @parameter value [Numeric] The value to set.
-		def self.set(...)
-			Interface.instance.set(...)
-		end
-		
-		# Set the observer for utilization metrics.
-		#
-		# When an observer is set, it is notified of all current values
-		# so it can sync its state. The observer must implement `set(field, value)`.
+		# This is the recommended way to access metrics for optimal performance.
 		#
 		# Delegates to the thread-local {Interface} instance.
 		#
-		# @parameter observer [#set] The observer to set.
-		def self.observer=(observer)
-			Interface.instance.observer = observer
+		# @parameter field [Symbol] The field name to get a metric for.
+		# @returns [Metric] A metric instance for the given field.
+		# @example
+		#   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)
+			Interface.instance.metric(field)
 		end
 	end
 end

lib/async/utilization/interface.rb

@@ -41,94 +41,94 @@ class Interface
 			# Initialize a new interface.
 			def initialize
 				@observer = nil
-				@values = Hash.new(0)
+				@metrics = {}
 
 				@guard = Mutex.new
 			end
 
 			# @attribute [Object | Nil] The registered observer.
 			attr :observer
 
-			# @attribute [Hash] The current values for all fields.
-			attr :values
+			# @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 interface.
 			#
-			# When an observer is set, it is notified of all current values
+			# 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
-					@observer = observer
-					
-					@values.each do |field, value|
-						observer.set(field, value)
+					# 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.
 			#
-			# Updates the interface's value and notifies the registered observer.
+			# 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)
-				field = field.to_sym
-				
-				@guard.synchronize do
-					@values[field] = value
-					@observer&.set(field, value)
-				end
+				metric(field).set(value)
 			end
 
 			# Increment a field value, optionally with a block that auto-decrements.
 			#
-			# Updates the interface's value and notifies the registered observer.
+			# 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)
-				field = field.to_sym
-				
-				new_value = nil
-				@guard.synchronize do
-					new_value = @values[field] + 1
-					@values[field] = new_value
-					@observer&.set(field, new_value)
-				end
-				
-				if block_given?
-					begin
-						yield
-					ensure
-						# Decrement after block completes
-						decrement(field)
-					end
-				end
-				
-				new_value
+			def increment(field, &block)
+				metric(field).increment(&block)
 			end
 
 			# Decrement a field value.
 			#
-			# Updates the interface's value and notifies the registered observer.
+			# 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
 
-				new_value = nil
 				@guard.synchronize do
-					new_value = @values[field] - 1
-					@values[field] = new_value
-					@observer&.set(field, new_value)
+					@metrics[field] ||= Metric.new(field, self)
 				end
-				
-				new_value
 			end
 		end
 	end