falcon-limiter 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f3dddcc61c0937bb6126b7a27298982a6159438479753b717fff59491ab9048
-  data.tar.gz: 6430a166f1ffb09e7dbdc6b0e4897abdcfc82c4b299af550aebe3a0ace1deba5
+  metadata.gz: 61d3807604e041bf6affc784d16a9dc6003016e0f716081f2fb85efd26f17f12
+  data.tar.gz: 9b1ca7661095b7f609b5cd027975e52bbd9b87951d09d2c6b947c16503fa9396
 SHA512:
-  metadata.gz: 4313993a4aa621ed7be5449759e8e874224c1d7ad88f1708e54f8fc2b070064b8ec43cce7b43775d98295c90eb46bd273592bd592331d20cb0d3f7990cef0a4a
-  data.tar.gz: a4b12e91879182a082573553293615843d07f08c8aa67d4f9a2aa13af1121dda6b13cff654887e7da585d21eb10f1d7a6c06d009818e03fbcb2f6a363b9b6a87
+  metadata.gz: d09553c8da363d761041e05850e6e38a6f562eb00108ea6944f6724e4546fc114332367c73ee1e87ff5445ed4fbc0a8d3519fbf2a42a0bc7806ff8088e73af5d
+  data.tar.gz: c46e60261492d8f0da23738dffe8fbdf20844e999acf766ee3e93cf3f3a2b351e8a9fd804249dc12284b987b35f843644d977db8536156be15e082c3277bbcff

data/examples/load/config.ru

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "console"
 require "falcon/limiter/long_task"
 
 run do |env|
@@ -8,12 +9,17 @@ run do |env|
 	case path
 	when "/io"
 		Console.info(self, "Starting \"I/O intensive\" task...")
-		Falcon::Limiter::LongTask.current.start
+		Falcon::Limiter::LongTask.current.start(delay: 0.1)
 		sleep(10)
 	when "/cpu"
 		Console.info(self, "Starting \"CPU intensive\" task...")
 		sleep(10)
+	else
+		Console.info(self, "Unknown path: #{path}")
+		return [404, {"content-type" => "text/plain"}, ["Not Found"]]
 	end
 	
+	Console.info(self, "Request completed");
+	
 	[200, {"content-type" => "text/plain"}, ["Hello from Falcon Limiter!"]]
 end

data/examples/load/readme.md

@@ -0,0 +1,87 @@
+# Load Example
+
+This example provides pseudo "io"-bound and "cpu"-bound endpoints for testing Falcon Limiter.
+
+## Usage
+
+First, start the server:
+
+```bash
+$ bundle exec ./falcon.rb
+  0.0s     info: Falcon::Command::Host [oid=0x448] [ec=0x450] [pid=8064] [2025-09-20 16:20:08 +1200]
+               | Falcon Host v0.52.3 taking flight!
+               | - Configuration: ././falcon.rb
+               | - To terminate: Ctrl-C or kill 8064
+               | - To reload: kill -HUP 8064
+ 0.08s     info: Async::Container::Notify::Console [oid=0x510] [ec=0x450] [pid=8064] [2025-09-20 16:20:08 +1200]
+               | {status: "Initializing controller..."}
+ 0.08s     info: Falcon::Service::Server [oid=0x520] [ec=0x450] [pid=8064] [2025-09-20 16:20:08 +1200]
+               | Starting hello.localhost on #<Async::HTTP::Endpoint http://localhost:9292ps/ {wrapper: #<Falcon::Limiter::Wrapper:0x0000000104efe0e8 @limiter=#<Async::Limiter::Queued:0x00000001086ffcd0 @timing=Async::Limiter::Timing::None, @parent=nil, @tags=nil, @mutex=#<Thread::Mutex:0x0000000104efe188>, @queue=#<Async::PriorityQueue:0x00000001086ffd20 @items=[true], @closed=false, @parent=nil, @waiting=#<IO::Event::PriorityHeap:0x0000000104efe4a8 @contents=[]>, @sequence=0, @mutex=#<Thread::Mutex:0x0000000104efe3e0>>>>}>
+ 0.08s     info: Async::Service::Controller [oid=0x528] [ec=0x450] [pid=8064] [2025-09-20 16:20:08 +1200]
+               | Controller starting...
+ 0.08s     info: Async::Container::Notify::Console [oid=0x510] [ec=0x450] [pid=8064] [2025-09-20 16:20:08 +1200]
+               | {ready: true, size: 1}
+ 0.08s     info: Async::Service::Controller [oid=0x528] [ec=0x450] [pid=8064] [2025-09-20 16:20:08 +1200]
+               | Controller started...
+```
+
+Note that the server is starting with a wrapper `Falcon::Limiter::Wrapper` which provides connection limiting, and with only a single worker (for the sake of making testing predictable).
+
+## "CPU"-bound Work
+
+Make several requests to the `/cpu` path:
+
+```bash
+# Start multiple requests in background
+$ curl http://localhost:9292/cpu &
+$ curl http://localhost:9292/cpu &
+$ curl http://localhost:9292/cpu &
+
+$ curl -v http://localhost:9292/cpu
+```
+
+You will note that these will be sequential as the connection limiter is limited to 1 connection at a time.
+
+## "IO"-bound Work
+
+Make several requests to the `/io` path:
+
+```bash
+# These will run concurrently (up to the long task limit)
+$ curl http://localhost:9292/io &
+$ curl http://localhost:9292/io &
+$ curl http://localhost:9292/io &
+$ curl http://localhost:9292/io &
+
+$ curl -v http://localhost:9292/io
+```
+
+You will note that these will be concurrent, as the connection limiter is released once `LongTask.current.start` is invoked.
+
+Also note that in order to prevent persistent connections from overloading the limiter, once a connection handles an "IO"-bound request, it will be marked as non-persistent (`connection: close`). This prevents us from having several "IO"-bound requests and a "CPU"-bound request from exceeding the limit on "CPU"-bound requests, by preventing a connection that was handling an "IO"-bound request from submitting a "CPU"-bound request (or otherwise hanging while waiting on the connection limiter).
+
+## Mixed Workload Testing
+
+In addition, if you perform a "CPU"-bound request after starting several "IO"-bound requests, a single "CPU"-bound request will be allowed, but until it completes, no further connections will be accepted.
+
+To see the limiter behavior with mixed workloads:
+
+```bash
+# Start several I/O requests
+$ curl http://localhost:9292/io &
+$ curl http://localhost:9292/io &
+$ curl http://localhost:9292/io &
+
+# Then try a CPU request (should be queued until I/O requests complete)
+$ curl http://localhost:9292/cpu
+```
+
+## Configuration
+
+The example is configured with:
+- **Connection limit**: 1 (only 1 connection accepted at a time).
+- **Long task limit**: 4 (up to 4 concurrent I/O operations).
+- **Start delay**: 0.1 seconds (delay before releasing connection token).
+- **Workers**: 1 (single process for predictable behavior).
+
+You can modify these values in `falcon.rb` by overriding the environment methods.

data/lib/falcon/limiter/environment.rb

@@ -15,11 +15,11 @@ module Falcon
 		# Provides simple, declarative configuration for concurrency limiting.
 		# Override these methods in your service to customize behavior.
 		module Environment
-			# Maximum number of concurrent long tasks (default: 4).
+			# Maximum number of concurrent long tasks (default: 10).
 			# If this is nil or non-positive, long task support will be disabled.
 			# @returns [Integer] The maximum number of concurrent long tasks.
 			def limiter_maximum_long_tasks
-				4
+				10
 			end
 			
 			# @returns [Integer] The maximum number of concurrent connection accepts.
@@ -66,6 +66,7 @@ module Falcon
 				limiter_middleware(super)
 			end
 			
+			# @returns [Falcon::Limiter::Wrapper] The wrapper for the connection limiter.
 			def limiter_wrapper
 				Wrapper.new(connection_limiter)
 			end

data/lib/falcon/limiter/long_task.rb

@@ -65,12 +65,18 @@ module Falcon
 				@delayed_start_task = nil
 			end
 			
-			# Check if the long task has been started.
-			# @returns [Boolean] True if the long task token has been acquired, false otherwise.
+			# Check if the long task has been started, but not necessarily acquired (e.g. if there was a delay).
+			# @returns [Boolean] If the long task has been started.
 			def started?
 				@token.acquired? || @delayed_start_task
 			end
 			
+			# Check if the long task has been acquired.
+			# @returns [Boolean] If the long task token has been acquired.
+			def acquired?
+				@token.acquired?
+			end
+			
 			# Start the long task, optionally with a delay to avoid overhead for short operations
 			def start(delay: @start_delay)
 				# If already started, nothing to do:
@@ -88,10 +94,6 @@ module Falcon
 					delay = nil
 				end
 				
-				def acquired?
-					@token.acquired?
-				end
-				
 				# Otherwise, start the long task:
 				if delay&.positive?
 					# Wait specified delay before starting the long task:

data/lib/falcon/limiter/middleware.rb

@@ -16,9 +16,9 @@ module Falcon
 			# Initialize the middleware with limiting configuration.
 			# @parameter delegate [Object] The next middleware in the chain to call.
 			# @parameter connection_limiter [Async::Limiter] Connection limiter instance for managing accepts.
-			# @parameter maximum_long_tasks [Integer] Maximum number of concurrent long tasks (default: 4).
+			# @parameter maximum_long_tasks [Integer] Maximum number of concurrent long tasks (default: 10).
 			# @parameter start_delay [Float] Delay in seconds before starting long tasks (default: 0.1).
-			def initialize(delegate, connection_limiter:, maximum_long_tasks: 4, start_delay: 0.1)
+			def initialize(delegate, connection_limiter:, maximum_long_tasks: 10, start_delay: 0.1)
 				super(delegate)
 				
 				@maximum_long_tasks = maximum_long_tasks

data/lib/falcon/limiter/socket.rb

@@ -49,17 +49,9 @@ module Falcon
 				end
 			end
 			
-			# Support for method_missing delegation by checking delegate's methods.
-			# @parameter method [Symbol] The method name to check.
-			# @parameter include_private [Boolean] Whether to include private methods (default: false).
-			# @returns [Boolean] True if the delegate responds to the method.
-			def respond_to_missing?(method, include_private = false)
-				@delegate.respond_to?(method, include_private) || super
-			end
-			
 			# Forward common inspection methods
 			def inspect
-				"#<#{self.class}(#{@delegate.class}) #{@delegate.inspect}>"
+				"#<#{Socket} #{@delegate.inspect}>"
 			end
 			
 			# String representation of the wrapped socket.

data/lib/falcon/limiter/version.rb

@@ -5,6 +5,6 @@
 
 module Falcon
 	module Limiter
-		VERSION = "0.1.0"
+		VERSION = "0.1.1"
 	end
 end

data/lib/falcon/limiter/wrapper.rb

@@ -43,6 +43,10 @@ module Falcon
 				token.release unless socket
 			end
 			
+			# Wrap the socket with a transparent token management.
+			# @parameter socket [Object] The socket to wrap.
+			# @parameter token [Async::Limiter::Token] The limiter token to release when socket closes.
+			# @returns [Falcon::Limiter::Socket] The wrapped socket.
 			def wrap_socket(socket, token)
 				Socket.new(socket, token)
 			end

data/readme.md

@@ -8,126 +8,33 @@ Advanced concurrency control and resource limiting for Falcon web server, built
 
 This gem provides sophisticated concurrency management for Falcon applications by:
 
-  - **Connection Limiting**: Control the number of concurrent connections to prevent server overload
-  - **Long Task Management**: Handle I/O vs CPU bound workloads effectively by releasing resources during long operations
-  - **Priority-based Resource Allocation**: Higher priority tasks get preferential access to limited resources
-  - **Automatic Resource Cleanup**: Ensures proper resource release even when exceptions occur
-  - **Built-in Statistics**: Monitor resource utilization and contention
+  - **Connection Limiting**: Control the number of concurrent connections to prevent server overload.
+  - **Long Task Management**: Handle I/O vs CPU bound workloads effectively by releasing resources during long operations.
+  - **Priority-based Resource Allocation**: Higher priority tasks get preferential access to limited resources.
+  - **Automatic Resource Cleanup**: Ensures proper resource release even when exceptions occur.
+  - **Built-in Statistics**: Monitor resource utilization and contention.
 
-## Installation
+## Usage
 
-Add this line to your application's Gemfile:
+Please see the [project documentation](https://socketry.github.io/falcon-limiter/) for more details.
 
-``` ruby
-gem 'falcon-limiter'
-```
+  - [Getting Started](https://socketry.github.io/falcon-limiter/guides/getting-started/index) - This guide explains how to get started with `falcon-limiter` for advanced concurrency control and resource limiting in Falcon web applications.
 
-## Usage
+  - [Long Tasks](https://socketry.github.io/falcon-limiter/guides/long-tasks/index) - This guide explains how to use <code class="language-ruby">Falcon::Limiter::LongTask</code> to effectively manage I/O vs CPU bound workloads in your Falcon applications.
 
-Please see the [project documentation](https://socketry.github.io/falcon-limiter/) for more details.
+## Releases
+
+Please see the [project releases](https://socketry.github.io/falcon-limiter/releases/index) for all releases.
 
-### Basic Falcon Environment Integration
-
-``` ruby
-#!/usr/bin/env falcon-host
-
-require "falcon-limiter"
-
-service "myapp.localhost" do
-  include Falcon::Environment::Limiter
-  
-  # Configure concurrency limits
-  limiter_configuration.max_long_tasks = 8
-  limiter_configuration.max_accepts = 2
-  
-  scheme "http"
-  url "http://localhost:9292"
-  
-  rack_app do
-    run lambda { |env|
-      # Start long task for I/O bound work
-      Falcon::Limiter::LongTask.current&.start
-      
-      # Long I/O operation (database query, external API call, etc.)
-      external_api_call
-      
-      # Optional manual stop (auto-cleanup on response end)
-      Falcon::Limiter::LongTask.current&.stop
-      
-      [200, {}, ["OK"]]
-    }
-  end
-end
-```
-
-### Manual Middleware Setup
-
-``` ruby
-require "falcon-limiter"
-require "protocol/http/middleware"
-
-# Configure middleware stack
-middleware = Protocol::HTTP::Middleware.build do
-  use Falcon::Limiter::Middleware, 
-      max_long_tasks: 4,
-      max_accepts: 2
-  use Protocol::Rack::Adapter
-  run rack_app
-end
-```
-
-### Direct Semaphore Usage
-
-``` ruby
-require "falcon-limiter"
-
-# Create a semaphore for database connections
-db_semaphore = Falcon::Limiter::Semaphore.new(5)
-
-# Acquire a connection
-token = db_semaphore.acquire
-
-begin
-  # Use database connection
-  database_operation
-ensure
-  # Release the connection
-  token.release
-end
-```
-
-## Configuration
-
-Configure limits using environment variables or programmatically:
-
-``` bash
-export FALCON_LIMITER_MAX_LONG_TASKS=8
-export FALCON_LIMITER_MAX_ACCEPTS=2
-export FALCON_LIMITER_START_DELAY=0.6
-```
-
-Or in code:
-
-``` ruby
-Falcon::Limiter.configure do |config|
-  config.max_long_tasks = 8
-  config.max_accepts = 2
-  config.start_delay = 0.6
-end
-```
-
-## Architecture
-
-Falcon Limiter is built on top of [async-limiter](https://github.com/socketry/async-limiter), providing:
-
-  - **Thread-safe resource management** using priority queues
-  - **Integration with Falcon's HTTP pipeline** through Protocol::HTTP::Middleware
-  - **Automatic connection token management** for optimal resource utilization
-  - **Priority-based task scheduling** to prevent resource starvation
-
-## Development
-
-After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec sus` to run the tests.
+### v0.1.0
+
+  - Initial implementation.
+
+## See Also
+
+  - [falcon](https://github.com/socketry/falcon) - A fast, asynchronous, rack-compatible web server.
+  - [async-limiter](https://github.com/socketry/async-limiter) - Execution rate limiting for Async.
+  - [async](https://github.com/socketry/async) - A concurrency framework for Ruby.
 
 ## Contributing
 
@@ -146,15 +53,3 @@ In order to protect users of this project, we require all contributors to comply
 ### 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.
-
-## Releases
-
-Please see the [project releases](https://socketry.github.io/falcon-limiter/releases/index) for all releases.
-
-### v0.1.0
-
-## See Also
-
-  - [falcon](https://github.com/socketry/falcon) - A fast, asynchronous, rack-compatible web server.
-  - [async-limiter](https://github.com/socketry/async-limiter) - Execution rate limiting for Async.
-  - [async](https://github.com/socketry/async) - A concurrency framework for Ruby.

data/releases.md

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: falcon-limiter
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Josh Teeter
@@ -59,14 +59,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- examples/basic_limiting.rb
-- examples/environment_usage.rb
-- examples/falcon_environment.rb
-- examples/limiter/README.md
-- examples/limiter/config.ru
-- examples/limiter/falcon.rb
 - examples/load/config.ru
 - examples/load/falcon.rb
+- examples/load/readme.md
 - lib/falcon/limiter.rb
 - lib/falcon/limiter/environment.rb
 - lib/falcon/limiter/long_task.rb

data/examples/basic_limiting.rb

@@ -1,40 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
-
-require_relative "../lib/falcon/limiter"
-
-# Create a semaphore with a limit of 3 concurrent resources
-semaphore = Falcon::Limiter::Semaphore.new(3)
-
-puts "Available resources: #{semaphore.available_count}"
-puts "Acquired resources: #{semaphore.acquired_count}"
-
-# Simulate acquiring and releasing resources
-tasks = []
-
-10.times do |i|
-	tasks << Thread.new do
-		puts "Task #{i}: Waiting for resource..."
-		
-		# Acquire a resource token
-		token = semaphore.acquire
-		
-		puts "Task #{i}: Acquired resource (#{semaphore.available_count} remaining)"
-		
-		# Simulate work
-		sleep(rand * 2)
-		
-		# Release the resource
-		token.release
-		
-		puts "Task #{i}: Released resource (#{semaphore.available_count} available)"
-	end
-end
-
-# Wait for all tasks to complete
-tasks.each(&:join)
-
-puts "Final state - Available: #{semaphore.available_count}, Acquired: #{semaphore.acquired_count}"

data/examples/environment_usage.rb

@@ -1,77 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
-
-require_relative "../lib/falcon/limiter"
-
-# Example service module that includes the limiter environment
-module MyService
-	include Falcon::Limiter::Environment
-	
-	# Customize limiter configuration by overriding methods
-	def limiter_maximum_long_tasks
-		8  # Override default of 4
-	end
-	
-	def limiter_maximum_accepts
-		3  # Override default of 1
-	end
-	
-	def limiter_start_delay
-		0.8 # Override default of 0.1
-	end
-	
-	# Mock middleware method
-	def middleware
-		proc {|_env| [200, {}, ["Base middleware"]]}
-	end
-	
-	# Mock endpoint method
-	def endpoint
-		Object.new.tap do |endpoint|
-			endpoint.define_singleton_method(:to_s) {"MockEndpoint"}
-		end
-	end
-end
-
-# Demonstrate the environment with proper async-service pattern
-require "async/service"
-environment = Async::Service::Environment.build(MyService)
-service = environment.evaluator
-
-puts "=== Falcon Limiter Environment Demo ==="
-puts
-puts "Configuration:"
-options = service.limiter_semaphore_options
-puts "  Max Long Tasks: #{options[:maximum_long_tasks]}"
-puts "  Max Accepts: #{options[:maximum_accepts]}"
-puts "  Start Delay: #{options[:start_delay]}s"
-puts
-
-puts "Semaphore:"
-semaphore = service.limiter_semaphore
-puts "  Limiter Semaphore: #{semaphore.available_count}/#{semaphore.limit} available"
-puts "  Limited: #{semaphore.limited?}"
-puts "  Waiting: #{semaphore.waiting_count}"
-puts
-
-puts "Middleware Integration:"
-base_middleware = service.middleware
-wrapped_middleware = service.limiter_middleware(base_middleware)
-puts "  Base middleware: #{base_middleware.class}"
-puts "  Wrapped middleware: #{wrapped_middleware.class}"
-puts
-
-puts "Endpoint Integration:"
-endpoint = service.endpoint
-puts "  Final Endpoint: #{endpoint.class}"
-
-# Check if it's actually wrapped (only if it's a Wrapper)
-if endpoint.respond_to?(:semaphore)
-	puts "  Semaphore: #{endpoint.semaphore.class}"
-	puts "  Same semaphore instance: #{endpoint.semaphore == service.limiter_semaphore}"
-else
-	puts "  Note: Endpoint is not wrapped (likely mock object)"
-end

data/examples/falcon_environment.rb

@@ -1,55 +0,0 @@
-#!/usr/bin/env falcon-host
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
-
-require_relative "../lib/falcon/limiter"
-
-service "limiter-example.localhost" do
-	include Falcon::Limiter::Environment
-	
-	# Configure concurrency limits by overriding methods
-	def limiter_max_long_tasks = 4
-	def limiter_max_accepts = 2
-	def limiter_start_delay = 0.5
-	
-	scheme "http"
-	url "http://localhost:9292"
-	
-	rack_app do
-		run lambda {|env|
-			request = env["protocol.http.request"]
-			
-			case env["PATH_INFO"]
-			when "/fast"
-				# Fast response - no need for long task
-				[200, { "Content-Type" => "text/plain" }, ["Fast response"]]
-				
-			when "/slow"
-				# Slow response - use long task management
-				Falcon::Limiter::LongTask.current&.start
-				
-				# Simulate I/O operation (database query, API call, etc.)
-				sleep(2)
-				
-				Falcon::Limiter::LongTask.current&.stop
-				
-				[200, { "Content-Type" => "text/plain" }, ["Slow response completed"]]
-				
-			when "/stats"
-				# Show limiter statistics
-				stats = if respond_to?(:statistics)
-					statistics
-				else
-					{ message: "Statistics not available" }
-				end
-				
-				[200, { "Content-Type" => "application/json" }, [stats.to_json]]
-				
-			else
-				[404, { "Content-Type" => "text/plain" }, ["Not found"]]
-			end
-		}
-	end
-end

data/examples/limiter/README.md

@@ -1,95 +0,0 @@
-# Falcon Limiter Examples
-
-This directory contains examples demonstrating the Falcon::Limiter functionality for managing concurrent workloads.
-
-## Overview
-
-The Falcon::Limiter system helps distinguish between I/O bound and CPU bound workloads:
-
-- **I/O bound work**: Long tasks that benefit from releasing connection tokens to improve concurrency
-- **CPU bound work**: Tasks that should keep connection tokens to prevent GVL contention
-
-## Examples
-
-### 1. Falcon Environment (`falcon.rb`)
-
-Uses `Falcon::Environment::Limiter` for turn-key setup:
-
-```bash
-falcon-host ./falcon.rb
-```
-
-**Endpoints:**
-- `/fast` - Quick response without long task
-- `/slow` - I/O bound task using long task management  
-- `/cpu` - CPU bound task without long task
-- `/stats` - Show limiter statistics
-
-### 2. Rack Application (`config.ru`)
-
-Basic Rack app with manual limiter middleware:
-
-```bash
-falcon serve -c config.ru
-```
-
-**Endpoints:**
-- `/long-io` - Long I/O operation with long task
-- `/short` - Short operation (long task delay avoids overhead)
-- `/token-info` - Shows connection token information
-- `/` - Simple hello response
-
-## Key Concepts
-
-### Long Task Management
-
-```ruby
-# For I/O bound operations
-request.long_task&.start
-external_api_call()  # Long I/O operation
-request.long_task&.stop  # Optional - auto cleanup on response end
-```
-
-### Connection Token Release
-
-Long tasks automatically:
-1. Extract and release connection tokens during I/O operations
-2. Acquire long task tokens from a separate semaphore
-3. Allow more connections to be accepted while I/O is pending
-4. Clean up automatically when response finishes
-
-### Configuration
-
-```ruby
-# Environment-based
-ENV["FALCON_LIMITER_MAX_LONG_TASKS"] = "8"
-ENV["FALCON_LIMITER_MAX_ACCEPTS"] = "2"
-
-# Or programmatic
-Falcon::Limiter.configure do |config|
-  config.max_long_tasks = 8
-  config.max_accepts = 2
-  config.start_delay = 0.6
-end
-```
-
-## Testing Load Scenarios
-
-Test with multiple concurrent requests:
-
-```bash
-# Test slow endpoint concurrency
-curl -s "http://localhost:9292/slow" &
-curl -s "http://localhost:9292/slow" &
-curl -s "http://localhost:9292/slow" &
-
-# Should still be responsive for fast requests
-curl -s "http://localhost:9292/fast"
-```
-
-## Benefits
-
-1. **Better Concurrency**: I/O operations don't block connection acceptance
-2. **Graceful Degradation**: System remains responsive under high load  
-3. **Resource Management**: Prevents GVL contention for CPU work
-4. **Automatic Cleanup**: Long tasks clean up automatically on response completion

data/examples/limiter/config.ru

@@ -1,50 +0,0 @@
-#!/usr/bin/env falcon --verbose serve -c
-# frozen_string_literal: true
-
-require "falcon/limiter"
-
-# Configure limiter globally
-Falcon::Limiter.configure do |config|
-	config.max_long_tasks = 4
-	config.max_accepts = 2
-	config.start_delay = 0.1
-end
-
-# Basic Rack app demonstrating limiter usage
-run lambda {|env|
-	request = env["protocol.http.request"]
-	path = env["PATH_INFO"]
-	
-	case path
-	when "/long-io"
-		# Start long task for I/O bound work
-		request.long_task&.start
-		
-		# Simulate database query or external API call
-		sleep(1.5)
-		
-		[200, { "content-type" => "text/plain" }, ["Long I/O operation completed at #{Time.now}"]]
-		
-	when "/short"
-		# Short operation - long task overhead avoided by delay
-		sleep(0.05)
-		[200, { "content-type" => "text/plain" }, ["Short operation at #{Time.now}"]]
-		
-	when "/token-info"
-		# Show connection token information
-		token_info = "No connection token"
-		
-		if request.respond_to?(:connection)
-			io = request.connection.stream.io
-			if io.respond_to?(:token)
-				token = io.token
-				token_info = "Token: #{token.inspect}, Released: #{token.released?}"
-			end
-		end
-		
-		[200, { "content-type" => "text/plain" }, [token_info]]
-		
-	else
-		[200, { "content-type" => "text/plain" }, ["Hello from Falcon Limiter!"]]
-	end
-}

data/examples/limiter/falcon.rb

@@ -1,60 +0,0 @@
-#!/usr/bin/env falcon-host
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
-
-require "falcon/limiter"
-
-service "limiter-example.localhost" do
-	include Falcon::Environment::Limiter
-	
-	# Configure limiter settings
-	limiter_configuration.max_long_tasks = 4
-	limiter_configuration.max_accepts = 2
-	limiter_configuration.start_delay = 0.1 # Shorter delay for demo
-	
-	scheme "http"
-	url "http://localhost:9292"
-	
-	rack_app do
-		run lambda {|env|
-			# Access HTTP request directly
-			request = env["protocol.http.request"]
-			path = env["PATH_INFO"]
-			
-			case path
-			when "/fast"
-				# Fast request - no long task needed
-				[200, { "content-type" => "text/plain" }, ["Fast response: #{Time.now}"]]
-				
-			when "/slow"
-				# Slow I/O bound request - use long task
-				request.long_task&.start
-				
-				# Simulate I/O operation
-				sleep(2.0)
-				
-				# Optional manual stop (auto-cleanup on response end)
-				request.long_task&.stop
-				
-				[200, { "content-type" => "text/plain" }, ["Slow response: #{Time.now}"]]
-				
-			when "/cpu"
-				# CPU bound request - don't use long task to prevent GVL contention
-				# Simulate CPU work
-				result = (1..1_000_000).sum
-				
-				[200, { "content-type" => "text/plain" }, ["CPU result: #{result}"]]
-				
-			when "/stats"
-				# Show limiter statistics
-				stats = statistics
-				[200, { "content-type" => "application/json" }, [stats.to_json]]
-				
-			else
-				[404, { "content-type" => "text/plain" }, ["Not found"]]
-			end
-		}
-	end
-end