falcon-limiter 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c04c3679d1562422a91fc38c90006c891199ae292a2452656bcef8d5f7d2b56b
-  data.tar.gz: 9b966859811d80f276405e1d2d7a2550ba978e23a433cf7bbef04b44520c1929
+  metadata.gz: 398a422d9e426d44f0e535293f8c86d5793943b36465c445a88eeb5023b41966
+  data.tar.gz: 9edf8daa24d823759dbf6c4ff972fc857b1e90c597e6f6de326d23440a0b3e7e
 SHA512:
-  metadata.gz: 3db14933d35669507a9fa818a56909f4e52dd6256cf169e1c1f0ce8f7c442314bb323265f8e0c9dcc74ee4b3d367d358abedcc1b36e0924d71c91100ba62b539
-  data.tar.gz: 5f495f30d22525a0068cb9b591769f469a61073829a23e1b9b9adf3ffb2e2ea498b854c05cca35cf51a3a1883f04186b86a5b3aca3d9ed698e4af79ecd80f08b
+  metadata.gz: e8b0e7f6a8eb03df0d5bc5a64411187fb54d3029e9fa8ec67ec3dfbef7296625429869605ebc20053ef7d687baa9a4346101a01a7f8f581949d81598796ce352
+  data.tar.gz: 7d68eb887d4388c9bbd6b6b961c7d94562e18d9e1bf85f853177b22baa1007bb6f16d54fcc13b69a53c893bb78a47f0ff6ea9c380587ab68833f9fb4788ca4c9

data/context/long-tasks.md

@@ -128,6 +128,16 @@ end
 
 The block form ensures the long task is properly stopped even if an exception occurs. They can also be nested.
 
+### Tags
+
+You can attach application-specific metadata when starting a long task:
+
+```ruby
+Falcon::Limiter::LongTask.current.start(tags: {name: :external_api_call})
+```
+
+Tags are stored on the long task while it is started or pending, and cleared when it stops. The limiter does not interpret tags directly; they are intended for instrumentation layers.
+
 ## Long Task Lifecycle
 
 ### 1. Creation

data/lib/falcon/limiter/long_task.rb

@@ -19,6 +19,8 @@ module Falcon
 			# The priority to use when stopping a long task to re-acquire the connection token.
 			STOP_PRIORITY = 1000
 			
+			attr_reader :tags
+			
 			# @returns [LongTask] The current long task.
 			def self.current
 				Fiber.current.falcon_limiter_long_task
@@ -63,6 +65,7 @@ module Falcon
 				
 				@token = Async::Limiter::Token.new(@limiter)
 				@delayed_start_task = nil
+				@tags = nil
 			end
 			
 			# Check if the long task has been started, but not necessarily acquired (e.g. if there was a delay).
@@ -84,7 +87,7 @@ module Falcon
 			end
 			
 			# Start the long task, optionally with a delay to avoid overhead for short operations
-			def start(delay: @start_delay)
+			def start(delay: @start_delay, tags: nil)
 				# If already started, nothing to do:
 				if started?
 					if block_given?
@@ -100,6 +103,8 @@ module Falcon
 					delay = nil
 				end
 				
+				@tags = tags
+				
 				# Otherwise, start the long task:
 				if delay&.positive?
 					# Wait specified delay before starting the long task:
@@ -137,6 +142,8 @@ module Falcon
 				
 				# Release the long task token:
 				release(force, **options)
+			ensure
+				@tags = nil
 			end
 			
 			private

data/lib/falcon/limiter/version.rb

@@ -5,6 +5,6 @@
 
 module Falcon
 	module Limiter
-		VERSION = "0.4.0"
+		VERSION = "0.5.0"
 	end
 end

data/readme.md

@@ -26,6 +26,10 @@ Please see the [project documentation](https://socketry.github.io/falcon-limiter
 
 Please see the [project releases](https://socketry.github.io/falcon-limiter/releases/index) for all releases.
 
+### v0.5.0
+
+  - Add optional `Falcon::Limiter::LongTask#start(tags:)` metadata for instrumentation.
+
 ### v0.4.0
 
   - Add `Falcon::Limiter::LongTask#pending?` for detecting delayed long tasks which have not acquired yet.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.5.0
+
+  - Add optional `Falcon::Limiter::LongTask#start(tags:)` metadata for instrumentation.
+
 ## v0.4.0
 
   - Add `Falcon::Limiter::LongTask#pending?` for detecting delayed long tasks which have not acquired yet.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: falcon-limiter
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Samuel Williams