Simplify getting started guide.

Author: samuel-williams-shopify

context/getting-started.md

@@ -72,68 +72,40 @@ end
 
 This runs a maximum of 2 tasks concurrently. Total duration is 2 seconds (tasks 0,1 run first, then tasks 2,3).
 
-### Queue-Based Resource Management
+### Timeouts
 
-Use a pre-populated queue of specific resources:
+You can control how long to wait when acquiring resources using the `timeout` parameter. This is particularly useful when working with limited capacity limiters that might block indefinitely.
 
 ```ruby
 require "async"
 require "async/limiter"
-require "async/queue"
 
 Async do
-	# Pre-populate queue with database connections
-	queue = Async::Queue.new
-	queue.push("connection_1")
-	queue.push("connection_2") 
-	queue.push("connection_3")
+	# Zero limit will always block:
+	limiter = Async::Limiter::Limited.new(0)
 
-	limiter = Async::Limiter::Queued.new(queue)
-	
-	5.times do |i|
-		limiter.async do |task|
-			# Automatically gets an available connection
-			limiter.acquire do |connection|
-				puts "Task #{i} using #{connection}"
-				task.sleep 1
-				# Connection automatically returned to queue
-			end
-		end
-	end
+	limiter.acquire(timeout: 3)
+	# => nil
+
+	limiter.acquire(timeout: 3) do
+		puts "Acquired."
+	end or puts "Timed out!"
 end
 ```
 
-## Advanced Timeout Features
-
-### Unified Timeouts
-
-All acquisition methods support flexible timeout handling:
-
-```ruby
-limiter = Async::Limiter::Limited.new(1)
-
-# Blocking (wait forever)
-resource = limiter.acquire
-
-# Non-blocking (immediate)
-resource = limiter.acquire(timeout: 0)
-return "busy" unless resource
-
-# Timed (wait up to 2.5 seconds)
-resource = limiter.acquire(timeout: 2.5)
-return "timeout" unless resource
+**Key timeout behaviors:**
 
-# With blocks (automatic cleanup)
-limiter.acquire(timeout: 1.0) do |resource|
-	# Use resource
-end  # Automatically released
-```
+- `timeout: nil` (default) - Wait indefinitely until a resource becomes available
+- `timeout: 0` - Non-blocking operation; return immediately if no resource is available  
+- `timeout: N` (where N > 0) - Wait up to N seconds for a resource to become available
 
-## Rate Limiting with Timing Strategies
+**Return values:**
+- Returns `true` (or the acquired resource) when successful
+- Returns `nil` when the timeout is exceeded or no resource is available
 
-### Sliding Window Rate Limiting
+## Rate Limiting
 
-Continuous rolling time windows:
+Timing strategies can be used to implement rate limiting, for example a continuous rolling time windows:
 
 ```ruby
 require "async"
@@ -142,9 +114,9 @@ require "async/limiter"
 Async do
 	# Max 3 tasks within any 1-second sliding window
 	timing = Async::Limiter::Timing::SlidingWindow.new(
-		1.0,                                             # 1-second window
-		Async::Limiter::Timing::BurstStrategy::Greedy,   # Allow bursting
-		3                                                # 3 tasks per window
+		1.0, # 1-second window.
+		Async::Limiter::Timing::BurstStrategy::Greedy, # Allow bursting
+		3 # 3 tasks per window
 	)
 
 	limiter = Async::Limiter::Limited.new(10, timing: timing)
@@ -157,139 +129,3 @@ Async do
 	end
 end
 ```
-
-### Fixed Window Rate Limiting
-
-Discrete time boundaries:
-
-```ruby
-# Max 5 tasks per 2-second window with fixed boundaries
-timing = Async::Limiter::Timing::FixedWindow.new(
-	2.0,                                             # 2-second windows
-	Async::Limiter::Timing::BurstStrategy::Greedy,   # Allow bursting
-	5                                                # 5 tasks per window
-)
-
-limiter = Async::Limiter::Limited.new(10, timing: timing)
-```
-
-### Leaky Bucket Rate Limiting
-
-Smooth rate limiting with token consumption:
-
-```ruby
-# 10 tokens per second, bucket capacity of 50 tokens
-timing = Async::Limiter::Timing::LeakyBucket.new(
-	10.0,  # 10 tokens/second leak rate
-	50.0   # 50 token capacity
-)
-
-limiter = Async::Limiter::Limited.new(100, timing: timing)
-
-# Bucket starts empty, fills with usage, leaks over time
-```
-
-## Cost-Based Acquisition
-
-Operations can consume multiple "units" based on their computational weight:
-
-```ruby
-# Create a leaky bucket with 10 tokens capacity
-timing = Async::Limiter::Timing::LeakyBucket.new(5.0, 10.0)  # 5/sec rate, 10 capacity
-limiter = Async::Limiter::Limited.new(100, timing: timing)
-
-# Light operations
-limiter.acquire(cost: 0.5) do
-	perform_light_operation()
-end
-
-# Normal operations  
-limiter.acquire(cost: 1.0) do  # Default cost
-	perform_standard_operation()
-end
-
-# Heavy operations
-limiter.acquire(cost: 3.5) do
-	perform_heavy_operation()
-end
-
-# Impossible operations fail fast
-begin
-	limiter.acquire(cost: 15.0)  # Exceeds capacity!
-rescue ArgumentError => e
-	puts "#{e.message}"  # Cost 15.0 exceeds maximum supported cost 10.0
-end
-```
-
-### Cost + Timeout Combinations
-
-```ruby
-# Heavy operation with timeout
-result = limiter.acquire(timeout: 30.0, cost: 5.0) do |resource|
-	expensive_computation()
-end
-
-if result
-	puts "Completed successfully"
-else
-	puts "Timed out waiting for capacity"
-end
-```
-
-## Manual Resource Management
-
-You can manually acquire and release resources:
-
-```ruby
-limiter = Async::Limiter::Limited.new(1)
-
-# Acquire with automatic release
-limiter.acquire do |resource|
-	puts "I have the resource"
-	# Automatically released when block exits
-end
-
-# Manual acquire/release
-resource = limiter.acquire
-begin
-	puts "I have the resource"
-ensure
-	limiter.release(resource)
-end
-
-# Non-blocking acquisition
-resource = limiter.acquire(timeout: 0)
-if resource
-	begin
-		puts "Got the resource immediately"
-	ensure
-		limiter.release(resource)
-	end
-else
-	puts "Resource not available"
-end
-```
-
-## Choosing the Right Limiter
-
-### Use {Async::Limiter::Generic} when:
-- You want unlimited concurrency
-- You need timing constraints without concurrency limits
-- You're building a base class for custom limiters
-
-### Use {Async::Limiter::Limited} when:
-- You need to limit concurrent execution
-- You want traditional semaphore behavior
-- You need timing + concurrency coordination
-
-### Use {Async::Limiter::Queued} when:
-- You have a pre-existing set of resources to distribute (DB connections, API keys, etc.).
-- You need priority-based resource allocation.
-- You want queue-based resource distribution with timeout support.
-
-### Timing Strategy Selection
-
-- **None**: Pure concurrency control without rate limiting.
-- **SlidingWindow**: Smooth, continuous rate limiting.
-- **FixedWindow**: Discrete time periods with burst tolerance.
-- **LeakyBucket**: Token-based rate limiting with natural decay.