This module provides a concurrent worker thread implementation for the token bucket rate limiting algorithm. The worker processes incoming requests from a queue and atomically updates the bucket state using Software Transactional Memory (STM).

Algorithm Overview

The token bucket algorithm works as follows:

1. Initialization: A bucket starts with a certain number of tokens (up to capacity)
2. Token Refill: Tokens are added to the bucket at a constant rate over time
3. Request Processing: Each request attempts to consume one token
4. Rate Limiting: If no tokens are available, the request is denied

Concurrency Model

The worker uses STM for atomic state updates and communicates via:

• TQueue for receiving incoming requests
• MVar for sending responses back to clients
• TVar for maintaining bucket state
• TMVar for signaling worker readiness

Example Usage

import Control.Concurrent.STM
import Control.Concurrent.MVar
import Data.Text

-- Create initial bucket state (100 tokens, last updated now)
now <- floor <$> getPOSIXTime  
initialState <- newTVarIO $ TokenBucketState 100 now

-- Create communication channels
requestQueue <- newTBroadcastTQueueIO
readySignal <- newEmptyTMVarIO

-- Start worker: 100 token capacity, 10 tokens/second refill rate
startTokenBucketWorker initialState requestQueue 100 10.0 readySignal

-- Wait for worker to be ready
atomically $ takeTMVar readySignal

-- Send a request and wait for response
replyVar <- newEmptyMVar
atomically $ writeTQueue requestQueue replyVar  
allowed <- takeMVar replyVar  -- True if request allowed, False if denied

Performance Characteristics

• Time Complexity: O(1) per request (constant time token calculation)
• Space Complexity: O(1) (fixed bucket state size)
• Concurrency: Lock-free using STM, supports high throughput
• Precision: Uses POSIX timestamps for accurate time-based calculations

Thread Safety

All operations are thread-safe through STM. Multiple clients can safely send requests to the same worker concurrently.