fractor 0.1.3 → 0.1.6

data/README.adoc

@@ -5,9 +5,9 @@ distributing computational work across multiple Ractors.
 
 == Introduction
 
-Fractor stands for *Function-driven Ractors framework*. It is a lightweight Ruby
-framework designed to simplify the process of distributing computational work
-across multiple Ractors (Ruby's actor-like concurrency model).
+Fractor stands for *Function-driven Ractors framework*. It is a lightweight
+Ruby framework designed to simplify the process of distributing computational
+work across multiple Ractors (Ruby's actor-like concurrency model).
 
 The primary goal of Fractor is to provide a structured way to define work,
 process it in parallel using Ractors, and aggregate the results, while
@@ -108,85 +108,125 @@ component that manages the pool of workers and distributes work items
 
 component that collects and organizes work results from workers
 
+=== pipeline mode
 
+operating mode where Fractor processes a defined set of work items and then
+stops
 
+=== continuous mode
 
-== Core components
+operating mode where Fractor runs indefinitely, processing work items as they
+arrive
 
-=== General
 
-The Fractor framework consists of the following main classes, all residing
-within the `Fractor` module.
 
 
-=== Fractor::Worker
+== Understanding Fractor operating modes
 
-The abstract base class for defining how work should be processed.
+=== General
 
-Client code must subclass this and implement the `process(work)` method.
+Fractor supports two distinct operating modes, each optimized for different use
+cases. Understanding these modes is essential for choosing the right approach
+for your application.
 
-The `process` method receives a `Fractor::Work` object (or a subclass) and
-   should return a `Fractor::WorkResult` object.
+=== Pipeline mode (batch processing)
 
-=== Fractor::Work
+Pipeline mode is designed for processing a defined set of work items with a
+clear beginning and end.
 
-The abstract base class for representing a unit of work.
+Characteristics:
 
-Typically holds the input data needed by the `Worker`.
+* Processes a predetermined batch of work items
+* Stops automatically when all work is completed
+* Results are collected and accessed after processing completes
+* Ideal for one-time computations or periodic batch jobs
 
-Client code should subclass this to define specific types of work items.
+Common use cases:
 
-=== Fractor::WorkResult
+* Processing a file or dataset
+* Batch data transformations
+* One-time parallel computations
+* Scheduled batch jobs
+* Hierarchical or multi-stage processing
 
-A container object returned by the `Worker#process` method.
+=== Continuous mode (long-running servers)
 
-Holds either the successful `:result` of the computation or an `:error`
-message if processing failed.
+Continuous mode is designed for applications that need to run indefinitely,
+processing work items as they arrive.
 
-Includes a reference back to the original `:work` item.
+Characteristics:
 
-Provides a `success?` method.
+* Runs continuously without a predetermined end
+* Processes work items dynamically as they become available
+* Workers idle efficiently when no work is available
+* Results are processed via callbacks, not batch collection
+* Supports graceful shutdown and runtime monitoring
 
-=== Fractor::ResultAggregator
+Common use cases:
 
-Collects and stores all `WorkResult` objects generated by the workers.
+* Chat servers and messaging systems
+* Background job processors
+* Real-time data stream processing
+* Web servers handling concurrent requests
+* Monitoring and alerting systems
+* Event-driven architectures
 
-Separates results into `results` (successful) and `errors` arrays.
+=== Comparison
 
-=== Fractor::WrappedRactor
+[cols="1,2,2",options="header"]
+|===
+|Aspect |Pipeline Mode |Continuous Mode
 
-Manages an individual Ruby `Ractor`.
+|Duration
+|Finite (stops when done)
+|Indefinite (runs until stopped)
 
-Instantiates the client-provided `Worker` subclass within the Ractor.
+|Work arrival
+|All work known upfront
+|Work arrives dynamically
 
-Handles receiving `Work` items, calling the `Worker#process` method, and
-yielding `WorkResult` objects (or errors) back to the `Supervisor`.
+|Result handling
+|Batch collection after completion
+|Callback-based processing
 
-=== Fractor::Supervisor
+|Typical lifetime
+|Seconds to minutes
+|Hours to days/weeks
 
-The main orchestrator of the framework.
+|Shutdown
+|Automatic on completion
+|Manual or signal-based
 
-Initializes and manages a pool of `WrappedRactor` instances.
+|Best for
+|Batch jobs, file processing
+|Servers, streams, job queues
+|===
 
-Manages a `work_queue` of input data.
+=== Decision guide
 
-Distributes work items (wrapped in the client's `Work` subclass) to available
-Ractors.
+Choose *Pipeline mode* when:
 
-Listens for results and errors from Ractors using `Ractor.select`.
+* You have a complete dataset to process
+* Processing has a clear start and end
+* You need all results aggregated after completion
+* The task is one-time or scheduled periodically
 
-Uses `ResultAggregator` to store outcomes.
+Choose *Continuous mode* when:
+
+* Work arrives over time from external sources
+* Your application runs as a long-lived server
+* You need to process items as they arrive
+* Results should be handled immediately via callbacks
 
-Handles graceful shutdown on `SIGINT` (Ctrl+C).
 
 
 
-== Quick start
+== Quick start: Pipeline mode
 
 === General
 
-This quick start guide shows the minimum steps needed to get a simple parallel
-execution working with Fractor.
+This quick start guide shows the minimum steps needed to get parallel batch
+processing working with Fractor.
 
 === Step 1: Create a minimal Work class
 
@@ -259,57 +299,233 @@ returns an error result.
 The Supervisor class orchestrates the entire framework, managing worker Ractors,
 distributing work, and collecting results.
 
-It initializes pools of Ractors, each running an instance of a Worker
-class. The Supervisor handles the communication between the main thread and
-the Ractors, including sending work items and receiving results.
-
-The Supervisor also manages the work queue and the ResultAggregator, which
-collects and organizes all results from the workers.
-
-To set up the Supervisor, you specify worker pools, each containing a Worker class
-and the number of workers to create. You can create multiple worker pools with
-different worker types to handle different kinds of work. Each worker pool can
-process any type of Work object that inherits from Fractor::Work.
-
 [source,ruby]
 ----
-# Create the supervisor
+# Create the supervisor with auto-detected number of workers
 supervisor = Fractor::Supervisor.new(
   worker_pools: [
-    { worker_class: MyWorker, num_workers: 4 }  # One pool with 4 workers
+    { worker_class: MyWorker }  # Number of workers auto-detected
   ]
 )
 
-# Add individual work items (instances of Work subclasses)
-supervisor.add_work_item(MyWork.new(1))
-
-# Add multiple work items
+# Add work items (instances of Work subclasses)
 supervisor.add_work_items([
+  MyWork.new(1),
   MyWork.new(2),
   MyWork.new(3),
   MyWork.new(4),
   MyWork.new(5)
 ])
 
-# You can add different types of Work objects to the same supervisor
-supervisor.add_work_items([
-  MyWork.new(6),
-  OtherWork.new("data")
-])
-
 # Run the processing
 supervisor.run
 
-# Access results
+# Access results after completion
 puts "Results: #{supervisor.results.results.map(&:result)}"
 puts "Errors: #{supervisor.results.errors.size}"
 ----
 
 That's it! With these three simple steps, you have a working parallel processing
-system using Fractor.
+system using Fractor in pipeline mode.
+
+
+
+
+== Quick start: Continuous mode
+
+=== General
+
+This quick start guide shows how to build a long-running server using Fractor's
+high-level primitives for continuous mode. These primitives eliminate boilerplate
+code for thread management, queuing, and results processing.
+
+=== Step 1: Create Work and Worker classes
+
+Just like pipeline mode, you need Work and Worker classes:
+
+[source,ruby]
+----
+require 'fractor'
+
+class MessageWork < Fractor::Work
+  def initialize(client_id, message)
+    super({ client_id: client_id, message: message })
+  end
+
+  def client_id
+    input[:client_id]
+  end
+
+  def message
+    input[:message]
+  end
+end
+
+class MessageWorker < Fractor::Worker
+  def process(work)
+    # Process the message
+    processed = "Echo: #{work.message}"
+
+    Fractor::WorkResult.new(
+      result: { client_id: work.client_id, response: processed },
+      work: work
+    )
+  rescue => e
+    Fractor::WorkResult.new(error: e.message, work: work)
+  end
+end
+----
+
+=== Step 2: Set up WorkQueue
+
+Create a thread-safe work queue that will hold incoming work items:
+
+[source,ruby]
+----
+# Create a thread-safe work queue
+work_queue = Fractor::WorkQueue.new
+----
+
+=== Step 3: Set up ContinuousServer with callbacks
+
+The ContinuousServer handles all the boilerplate: thread management, signal
+handling, and results processing.
+
+[source,ruby]
+----
+# Create the continuous server
+server = Fractor::ContinuousServer.new(
+  worker_pools: [
+    { worker_class: MessageWorker, num_workers: 4 }
+  ],
+  work_queue: work_queue,  # Auto-registers as work source
+  log_file: 'logs/server.log'  # Optional logging
+)
+
+# Define how to handle successful results
+server.on_result do |result|
+  client_id = result.result[:client_id]
+  response = result.result[:response]
+  puts "Sending to client #{client_id}: #{response}"
+  # Send response to client here
+end
+
+# Define how to handle errors
+server.on_error do |error_result|
+  puts "Error processing work: #{error_result.error}"
+end
+----
+
+=== Step 4: Run and add work dynamically
+
+Start the server and add work items as they arrive:
+
+[source,ruby]
+----
+# Start the server in a background thread
+server_thread = Thread.new { server.run }
+
+# Your application can now push work items dynamically
+# For example, when a client sends a message:
+work_queue << MessageWork.new(client_id: 1, message: "Hello")
+work_queue << MessageWork.new(client_id: 2, message: "World")
+
+# The server runs indefinitely, processing work as it arrives
+# Use Ctrl+C or send SIGTERM for graceful shutdown
+
+# Or stop programmatically
+sleep 10
+server.stop
+server_thread.join
+----
+
+That's it! The ContinuousServer handles all thread management, signal handling,
+and graceful shutdown automatically.
+
+
+
+
+== Core components
+
+=== General
+
+The Fractor framework consists of the following main classes, all residing
+within the `Fractor` module. These core components are used by both pipeline
+mode and continuous mode.
+
+
+=== Fractor::Worker
+
+The abstract base class for defining how work should be processed.
+
+Client code must subclass this and implement the `process(work)` method.
+
+The `process` method receives a `Fractor::Work` object (or a subclass) and
+should return a `Fractor::WorkResult` object.
+
+=== Fractor::Work
+
+The abstract base class for representing a unit of work.
+
+Typically holds the input data needed by the `Worker`.
+
+Client code should subclass this to define specific types of work items.
+
+=== Fractor::WorkResult
+
+A container object returned by the `Worker#process` method.
+
+Holds either the successful `:result` of the computation or an `:error`
+message if processing failed.
+
+Includes a reference back to the original `:work` item.
+
+Provides a `success?` method.
+
+=== Fractor::ResultAggregator
+
+Collects and stores all `WorkResult` objects generated by the workers.
+
+Separates results into `results` (successful) and `errors` arrays.
+
+=== Fractor::WrappedRactor
+
+Manages an individual Ruby `Ractor`.
+
+Instantiates the client-provided `Worker` subclass within the Ractor.
+
+Handles receiving `Work` items, calling the `Worker#process` method, and
+yielding `WorkResult` objects (or errors) back to the `Supervisor`.
+
+=== Fractor::Supervisor
+
+The main orchestrator of the framework.
+
+Initializes and manages a pool of `WrappedRactor` instances.
+
+Manages a `work_queue` of input data.
+
+Distributes work items (wrapped in the client's `Work` subclass) to available
+Ractors.
+
+Listens for results and errors from Ractors using `Ractor.select`.
+
+Uses `ResultAggregator` to store outcomes.
+
+Handles graceful shutdown on `SIGINT` (Ctrl+C).
+
+
+
+
+== Pipeline mode components
 
+=== General
+
+This section describes the components and their detailed usage specifically for
+pipeline mode (batch processing). For continuous mode, see the Continuous mode
+components section.
 
-== Usage
+Pipeline mode uses only the core components without any additional primitives.
 
 === Work class
 
@@ -362,11 +578,9 @@ end
 
 [TIP]
 ====
-====
 * Keep Work objects lightweight and serializable since they will be passed
   between Ractors
 * Implement a meaningful `to_s` method for better debugging
-====
 * Consider adding validation in the initializer to catch issues early
 ====
 
@@ -448,7 +662,10 @@ def process(work)
   Fractor::WorkResult.new(result: result, work: work)
 rescue StandardError => e
   # Catch and convert any unexpected exceptions to error results
-  Fractor::WorkResult.new(error: "An unexpected error occurred: #{e.message}", work: work)
+  Fractor::WorkResult.new(
+    error: "An unexpected error occurred: #{e.message}",
+    work: work
+  )
 end
 ----
 
@@ -460,277 +677,1118 @@ end
 * Ensure all paths return a valid `WorkResult` object
 ====
 
-=== WorkResult class
+=== Supervisor class for pipeline mode
 
 ==== Purpose and responsibilities
 
-The `Fractor::WorkResult` class is a container that holds either the successful
-result of processing or an error message, along with a reference to the original
-work item.
+The `Fractor::Supervisor` class orchestrates the entire framework, managing
+worker Ractors, distributing work, and collecting results.
 
-==== Creating results
+==== Configuration options
 
-To create a successful result:
+When creating a Supervisor for pipeline mode, configure worker pools:
 
 [source,ruby]
 ----
-# For successful processing
-Fractor::WorkResult.new(result: calculated_value, work: work_object)
+supervisor = Fractor::Supervisor.new(
+  worker_pools: [
+    # Pool 1 - for general data processing
+    { worker_class: MyWorker, num_workers: 4 },
+
+    # Pool 2 - for specialized image processing
+    { worker_class: ImageWorker, num_workers: 2 }
+  ]
+  # Note: continuous_mode defaults to false for pipeline mode
+)
 ----
 
-To create an error result:
+==== Worker auto-detection
+
+Fractor automatically detects the number of available processors on your system
+and uses that value when `num_workers` is not specified. This provides optimal
+resource utilization across different deployment environments without requiring
+manual configuration.
 
 [source,ruby]
 ----
-# For error conditions
-Fractor::WorkResult.new(error: "Error message", work: work_object)
+# Auto-detect number of workers (recommended for most cases)
+supervisor = Fractor::Supervisor.new(
+  worker_pools: [
+    { worker_class: MyWorker }  # Will use number of available processors
+  ]
+)
+
+# Explicitly set number of workers (useful for specific requirements)
+supervisor = Fractor::Supervisor.new(
+  worker_pools: [
+    { worker_class: MyWorker, num_workers: 4 }  # Always use exactly 4 workers
+  ]
+)
+
+# Mix auto-detection and explicit configuration
+supervisor = Fractor::Supervisor.new(
+  worker_pools: [
+    { worker_class: FastWorker },                    # Auto-detected
+    { worker_class: HeavyWorker, num_workers: 2 }    # Explicitly 2 workers
+  ]
+)
 ----
 
-==== Checking result status
+The auto-detection uses Ruby's `Etc.nprocessors` which returns the number of
+available processors. If detection fails for any reason, it falls back to 2
+workers.
+
+[TIP]
+====
+* Use auto-detection for portable code that adapts to different environments
+* Explicitly set `num_workers` when you need precise control over resource usage
+* Consider system load and other factors when choosing explicit values
+====
+
+==== Adding work
 
-You can check if a result was successful:
+You can add work items individually or in batches:
 
 [source,ruby]
 ----
-if work_result.success?
-  # Handle successful result
-  processed_value = work_result.result
-else
-  # Handle error
-  error_message = work_result.error
-end
+# Add a single item
+supervisor.add_work_item(MyWork.new(42))
+
+# Add multiple items
+supervisor.add_work_items([
+  MyWork.new(1),
+  MyWork.new(2),
+  MyWork.new(3),
+  MyWork.new(4),
+  MyWork.new(5)
+])
+
+# Add items of different work types
+supervisor.add_work_items([
+  TextWork.new("Process this text"),
+  ImageWork.new({ width: 800, height: 600 })
+])
 ----
 
-==== Accessing original work
+The Supervisor can handle any Work object that inherits from Fractor::Work.
+Workers must check the type of Work they receive and process it accordingly.
+
+==== Running and monitoring
 
-The original work item is always available:
+To start processing:
 
 [source,ruby]
 ----
-original_work = work_result.work
-input_value = original_work.input
+# Start processing and block until complete
+supervisor.run
 ----
 
-=== ResultAggregator class
+The Supervisor automatically handles:
+
+* Starting the worker Ractors
+* Distributing work items to available workers
+* Collecting results and errors
+* Graceful shutdown on completion or interruption (Ctrl+C)
+
+=== ResultAggregator for pipeline mode
 
 ==== Purpose and responsibilities
 
 The `Fractor::ResultAggregator` collects and organizes all results from the
 workers, separating successful results from errors.
 
-Completed work results may be order independent or order dependent.
-
-* For order independent results, the results may be utilized (popped) as they
-are received.
-
-* For order dependent results, the results are aggregated in the order they
-are received. The order of results is important for re-assembly or
-further processing.
-
-* For results that require aggregation, the `ResultsAggregator` is used to determine
-whether the results are completed, which signify that all work items have
-been processed and ready for further processing.
-
+In pipeline mode, results are collected throughout processing and accessed
+after the supervisor finishes running.
 
 ==== Accessing results
 
-To access successful results:
+After processing completes:
 
 [source,ruby]
 ----
-# Get all successful results
-successful_results = supervisor.results.results
+# Get the ResultAggregator
+aggregator = supervisor.results
+
+# Check counts
+puts "Processed #{aggregator.results.size} items successfully"
+puts "Encountered #{aggregator.errors.size} errors"
+
+# Access successful results
+aggregator.results.each do |result|
+  puts "Work item #{result.work.input} produced #{result.result}"
+end
+
+# Access errors
+aggregator.errors.each do |error_result|
+  puts "Work item #{error_result.work.input} failed: #{error_result.error}"
+end
+----
+
+To access successful results:
+
+[source,ruby]
+----
+# Get all successful results
+successful_results = supervisor.results.results
 
 # Extract just the result values
 result_values = successful_results.map(&:result)
 ----
 
-To access errors:
+To access errors:
+
+[source,ruby]
+----
+# Get all error results
+error_results = supervisor.results.errors
+
+# Extract error messages
+error_messages = error_results.map(&:error)
+
+# Get the work items that failed
+failed_work_items = error_results.map(&:work)
+----
+
+
+[TIP]
+====
+* Check both successful results and errors after processing completes
+* Consider implementing custom reporting based on the aggregated results
+====
+
+
+
+
+== Pipeline mode patterns
+
+=== Custom work distribution
+
+For more complex scenarios, you might want to prioritize certain work items:
+
+[source,ruby]
+----
+# Create Work objects for high priority items
+high_priority_works = high_priority_items.map { |item| MyWork.new(item) }
+
+# Add high-priority items first
+supervisor.add_work_items(high_priority_works)
+
+# Run with just enough workers for high-priority items
+supervisor.run
+
+# Create Work objects for lower priority items
+low_priority_works = low_priority_items.map { |item| MyWork.new(item) }
+
+# Add and process lower-priority items
+supervisor.add_work_items(low_priority_works)
+supervisor.run
+----
+
+=== Handling large datasets
+
+For very large datasets, consider processing in batches:
+
+[source,ruby]
+----
+large_dataset.each_slice(1000) do |batch|
+  # Convert batch items to Work objects
+  work_batch = batch.map { |item| MyWork.new(item) }
+
+  supervisor.add_work_items(work_batch)
+  supervisor.run
+
+  # Process this batch's results before continuing
+  process_batch_results(supervisor.results)
+end
+----
+
+=== Multi-work type processing
+
+The Multi-Work Type pattern demonstrates how a single supervisor and worker can
+handle multiple types of work items.
+
+[source,ruby]
+----
+class UniversalWorker < Fractor::Worker
+  def process(work)
+    case work
+    when TextWork
+      process_text(work)
+    when ImageWork
+      process_image(work)
+    else
+      Fractor::WorkResult.new(
+        error: "Unknown work type: #{work.class}",
+        work: work
+      )
+    end
+  end
+
+  private
+
+  def process_text(work)
+    result = work.text.upcase
+    Fractor::WorkResult.new(result: result, work: work)
+  end
+
+  def process_image(work)
+    result = { width: work.width * 2, height: work.height * 2 }
+    Fractor::WorkResult.new(result: result, work: work)
+  end
+end
+
+# Add different types of work
+supervisor.add_work_items([
+  TextWork.new("hello"),
+  ImageWork.new(width: 100, height: 100),
+  TextWork.new("world")
+])
+----
+
+=== Hierarchical work processing
+
+The Producer/Subscriber pattern showcases processing that generates sub-work:
+
+[source,ruby]
+----
+# First pass: Process documents
+supervisor.add_work_items(documents.map { |doc| DocumentWork.new(doc) })
+supervisor.run
+
+# Collect sections generated from documents
+sections = supervisor.results.results.flat_map do |result|
+  result.result[:sections]
+end
+
+# Second pass: Process sections
+supervisor.add_work_items(sections.map { |section| SectionWork.new(section) })
+supervisor.run
+----
+
+=== Pipeline stages
+
+The Pipeline Processing pattern implements multi-stage transformation:
+
+[source,ruby]
+----
+# Stage 1: Extract data
+supervisor1 = Fractor::Supervisor.new(
+  worker_pools: [{ worker_class: ExtractionWorker }]
+)
+supervisor1.add_work_items(raw_data.map { |d| ExtractionWork.new(d) })
+supervisor1.run
+extracted = supervisor1.results.results.map(&:result)
+
+# Stage 2: Transform data
+supervisor2 = Fractor::Supervisor.new(
+  worker_pools: [{ worker_class: TransformWorker }]
+)
+supervisor2.add_work_items(extracted.map { |e| TransformWork.new(e) })
+supervisor2.run
+transformed = supervisor2.results.results.map(&:result)
+
+# Stage 3: Load data
+supervisor3 = Fractor::Supervisor.new(
+  worker_pools: [{ worker_class: LoadWorker }]
+)
+supervisor3.add_work_items(transformed.map { |t| LoadWork.new(t) })
+supervisor3.run
+----
+
+
+
+
+== Continuous mode components
+
+=== General
+
+This section describes the components and their detailed usage specifically for
+continuous mode (long-running servers). For pipeline mode, see the Pipeline mode
+components section.
+
+Continuous mode offers two approaches: a low-level API for manual control, and
+high-level primitives that eliminate boilerplate code.
+
+=== Low-level components
+
+==== General
+
+The low-level API provides manual control over continuous mode operation. This
+approach is useful when you need fine-grained control over threading, work
+sources, or results processing.
+
+Use the low-level API when:
+
+* You need custom thread management
+* Your work source logic is complex
+* You require precise control over the supervisor lifecycle
+* You're integrating with existing thread pools or event loops
+
+For most applications, the high-level primitives (described in the next section)
+are recommended as they eliminate significant boilerplate code.
+
+==== Supervisor with continuous_mode: true
+
+To enable continuous mode, set the `continuous_mode` option:
+
+[source,ruby]
+----
+supervisor = Fractor::Supervisor.new(
+  worker_pools: [
+    { worker_class: MyWorker, num_workers: 2 }
+  ],
+  continuous_mode: true  # Enable continuous mode
+)
+----
+
+==== Work source callbacks
+
+Register a callback that provides new work on demand:
+
+[source,ruby]
+----
+supervisor.register_work_source do
+  # Return nil or empty array if no work is available
+  # Return a work item or array of work items when available
+  items = get_next_work_items
+  if items && !items.empty?
+    # Convert to Work objects if needed
+    items.map { |item| MyWork.new(item) }
+  else
+    nil
+  end
+end
+----
+
+The callback is polled every 100ms by an internal timer thread.
+
+==== Manual thread management
+
+You must manually manage threads and results processing:
+
+[source,ruby]
+----
+# Start supervisor in a background thread
+supervisor_thread = Thread.new { supervisor.run }
+
+# Start results processing thread
+results_thread = Thread.new do
+  loop do
+    # Process results
+    while (result = supervisor.results.results.shift)
+      handle_result(result)
+    end
+
+    # Process errors
+    while (error = supervisor.results.errors.shift)
+      handle_error(error)
+    end
+
+    sleep 0.1
+  end
+end
+
+# Ensure cleanup on shutdown
+begin
+  supervisor_thread.join
+rescue Interrupt
+  supervisor.stop
+ensure
+  results_thread.kill
+  supervisor_thread.join
+end
+----
+
+=== High-level components
+
+==== General
+
+Fractor provides high-level primitives that dramatically simplify continuous
+mode applications by eliminating boilerplate code.
+
+These primitives solve common problems:
+
+* *Thread management*: Automatic supervisor and results processing threads
+* *Queue synchronization*: Thread-safe work queue with automatic integration
+* *Results processing*: Callback-based handling instead of manual loops
+* *Signal handling*: Built-in support for SIGINT, SIGTERM, SIGUSR1/SIGBREAK
+* *Graceful shutdown*: Coordinated cleanup across all threads
+
+Real-world benefits:
+
+* The chat server example reduced from 279 lines to 167 lines (40% reduction)
+* Eliminates ~112 lines of thread, queue, and signal handling boilerplate
+* Simpler, more maintainable code with fewer error-prone details
+
+==== Fractor::WorkQueue
+
+===== Purpose and responsibilities
+
+`Fractor::WorkQueue` provides a thread-safe queue for continuous mode
+applications. It handles work item storage and integrates automatically with the
+supervisor's work source mechanism.
+
+===== Thread-safety
+
+The WorkQueue is *thread-safe* but not *Ractor-safe*:
+
+* *Thread-safe*: Multiple threads can safely push work items concurrently
+* *Not Ractor-safe*: The queue lives in the main process and cannot be shared
+  across Ractor boundaries
+
+This design is intentional. The WorkQueue operates in the main process where
+your application code runs. Work items are retrieved by the Supervisor (also in
+the main process) and then sent to worker Ractors.
+
+.WorkQueue architecture
+[source]
+----
+Main Process
+├─→ Your application threads (push to WorkQueue)
+├─→ WorkQueue (thread-safe, lives here)
+├─→ Supervisor (polls WorkQueue)
+│   └─→ Sends work to Worker Ractors
+└─→ Worker Ractors (receive frozen/shareable work items)
+----
+
+===== Creating a WorkQueue
+
+[source,ruby]
+----
+work_queue = Fractor::WorkQueue.new
+----
+
+===== Adding work items
+
+Use the `<<` operator for thread-safe push operations:
+
+[source,ruby]
+----
+# From any thread in your application
+work_queue << MyWork.new(data)
+
+# Thread-safe even from multiple threads
+threads = 10.times.map do |i|
+  Thread.new do
+    100.times do |j|
+      work_queue << MyWork.new("thread-#{i}-item-#{j}")
+    end
+  end
+end
+threads.each(&:join)
+----
+
+===== Checking queue status
+
+[source,ruby]
+----
+# Check if queue is empty
+if work_queue.empty?
+  puts "No work available"
+end
+
+# Get current queue size
+puts "Queue has #{work_queue.size} items"
+----
+
+===== Integration with Supervisor
+
+The WorkQueue integrates automatically with ContinuousServer (see next section).
+For manual integration with a Supervisor:
+
+[source,ruby]
+----
+supervisor = Fractor::Supervisor.new(
+  worker_pools: [{ worker_class: MyWorker }],
+  continuous_mode: true
+)
+
+# Register the work queue as a work source
+work_queue.register_with_supervisor(supervisor)
+
+# Now the supervisor will automatically poll the queue for work
+----
+
+==== Fractor::ContinuousServer
+
+===== Purpose and responsibilities
+
+`Fractor::ContinuousServer` is a high-level wrapper that handles all the
+complexity of running a continuous mode application. It manages:
+
+* Supervisor thread lifecycle
+* Results processing thread with callback system
+* Signal handling (SIGINT, SIGTERM, SIGUSR1/SIGBREAK)
+* Graceful shutdown coordination
+* Optional logging
+
+===== Creating a ContinuousServer
+
+[source,ruby]
+----
+server = Fractor::ContinuousServer.new(
+  worker_pools: [
+    { worker_class: MessageWorker, num_workers: 4 }
+  ],
+  work_queue: work_queue,  # Optional, auto-registers if provided
+  log_file: 'logs/server.log'  # Optional
+)
+----
+
+Parameters:
+
+* `worker_pools` (required): Array of worker pool configurations
+* `work_queue` (optional): A Fractor::WorkQueue instance to auto-register
+* `log_file` (optional): Path for log output
+
+===== Registering callbacks
+
+Define how to handle results and errors:
+
+[source,ruby]
+----
+# Handle successful results
+server.on_result do |result|
+  # result is a Fractor::WorkResult with result.result containing your data
+  puts "Success: #{result.result}"
+  # Send response to client, update database, etc.
+end
+
+# Handle errors
+server.on_error do |error_result|
+  # error_result is a Fractor::WorkResult with error_result.error containing the message
+  puts "Error: #{error_result.error}"
+  # Log error, send notification, etc.
+end
+----
+
+===== Running the server
+
+[source,ruby]
+----
+# Blocking: Run the server (blocks until shutdown signal)
+server.run
+
+# Non-blocking: Run in background thread
+server_thread = Thread.new { server.run }
+
+# Your application continues here...
+# Add work to queue as needed
+work_queue << MyWork.new(data)
+
+# Later, stop the server
+server.stop
+server_thread.join
+----
+
+===== Signal handling
+
+The ContinuousServer automatically handles:
+
+* *SIGINT* (Ctrl+C): Graceful shutdown
+* *SIGTERM*: Graceful shutdown (production deployment)
+* *SIGUSR1* (Unix) / *SIGBREAK* (Windows): Status output
+
+No additional code needed - signals work automatically.
+
+===== Graceful shutdown
+
+When a shutdown signal is received:
+
+. Stops accepting new work from the work queue
+. Allows in-progress work to complete (within ~2 seconds)
+. Processes remaining results through callbacks
+. Cleans up all threads and resources
+. Returns from the `run` method
+
+===== Programmatic shutdown
+
+[source,ruby]
+----
+# Stop the server programmatically
+server.stop
+
+# The run method will return shortly after
+----
+
+==== Integration architecture
+
+The high-level components work together seamlessly:
+
+.Complete architecture diagram
+[source]
+----
+┌───────────────────────────────────────────────────────────┐
+│                     Main Process                          │
+│                                                           │
+│  ┌──────────────┐     ┌──────────────────────────────┐    │
+│  │ Your App     │────>│ WorkQueue (thread-safe)      │    │
+│  │ (any thread) │     │ - Thread::Queue internally   │    │
+│  └──────────────┘     └──────────────────────────────┘    │
+│                                 │                         │
+│                                 │ polled every 100ms      │
+│                                 ▼                         │
+│  ┌────────────────────────────────────────────────────┐   │
+│  │         ContinuousServer                           │   │
+│  │  ┌─────────────────────────────────────────────┐   │   │
+│  │  │  Supervisor Thread                          │   │   │
+│  │  │  - Manages worker Ractors                   │   │   │
+│  │  │  - Distributes work                         │   │   │
+│  │  │  - Coordinates shutdown                     │   │   │
+│  │  └─────────────────────────────────────────────┘   │   │
+│  │          │                                         │   │
+│  │          ▼                                         │   │
+│  │  ┌─────────────────────────────────────────────┐   │   │
+│  │  │  Worker Ractors (parallel execution)        │   │   │
+│  │  │  - Ractor 1: WorkerInstance.process(work)   │   │   │
+│  │  │  - Ractor 2: WorkerInstance.process(work)   │   │   │
+│  │  │  - Ractor N: WorkerInstance.process(work)   │   │   │
+│  │  └─────────────────────────────────────────────┘   │   │
+│  │          │                                         │   │
+│  │          ▼ (WorkResults)                           │   │
+│  │  ┌─────────────────────────────────────────────┐   │   │
+│  │  │  Results Processing Thread                  │   │   │
+│  │  │  - on_result callback for successes         │   │   │
+│  │  │  - on_error callback for failures           │   │   │
+│  │  └─────────────────────────────────────────────┘   │   │
+│  │                                                    │   │
+│  │  ┌─────────────────────────────────────────────┐   │   │
+│  │  │  Signal Handler Thread                      │   │   │
+│  │  │  - SIGINT/SIGTERM: Shutdown                 │   │   │
+│  │  │  - SIGUSR1/SIGBREAK: Status                 │   │   │
+│  │  └─────────────────────────────────────────────┘   │   │
+│  └────────────────────────────────────────────────────┘   │
+└───────────────────────────────────────────────────────────┘
+----
+
+Key points:
+
+* WorkQueue lives in main process (thread-safe, not Ractor-safe)
+* Supervisor polls WorkQueue and distributes to Ractors
+* Work items must be frozen/shareable to cross Ractor boundary
+* Results come back through callbacks, not batch collection
+* All thread management is automatic
+
+
+
+
+== Continuous mode patterns
+
+=== Basic server with callbacks
+
+The most common pattern uses WorkQueue + ContinuousServer:
+
+[source,ruby]
+----
+require 'fractor'
+
+# Define work and worker
+class RequestWork < Fractor::Work
+  def initialize(request_id, data)
+    super({ request_id: request_id, data: data })
+  end
+end
+
+class RequestWorker < Fractor::Worker
+  def process(work)
+    # Process the request
+    result = perform_computation(work.input[:data])
+
+    Fractor::WorkResult.new(
+      result: { request_id: work.input[:request_id], response: result },
+      work: work
+    )
+  rescue => e
+    Fractor::WorkResult.new(error: e.message, work: work)
+  end
+
+  private
+
+  def perform_computation(data)
+    # Your business logic here
+    data.upcase
+  end
+end
+
+# Set up server
+work_queue = Fractor::WorkQueue.new
+
+server = Fractor::ContinuousServer.new(
+  worker_pools: [{ worker_class: RequestWorker, num_workers: 4 }],
+  work_queue: work_queue
+)
+
+server.on_result { |result| puts "Success: #{result.result}" }
+server.on_error { |error| puts "Error: #{error.error}" }
+
+# Run server (blocks until shutdown)
+Thread.new { server.run }
+
+# Application logic adds work as needed
+work_queue << RequestWork.new(1, "hello")
+work_queue << RequestWork.new(2, "world")
+
+sleep # Keep main thread alive
+----
+
+=== Event-driven processing
+
+Process events from external sources as they arrive:
+
+[source,ruby]
+----
+# Event source (could be webhooks, message queue, etc.)
+event_source = EventSource.new
+
+# Set up work queue and server
+work_queue = Fractor::WorkQueue.new
+server = Fractor::ContinuousServer.new(
+  worker_pools: [{ worker_class: EventWorker, num_workers: 8 }],
+  work_queue: work_queue
+)
+
+server.on_result do |result|
+  # Publish result to subscribers
+  publish_event(result.result)
+end
+
+# Event loop adds work to queue
+event_source.on_event do |event|
+  work_queue << EventWork.new(event)
+end
+
+# Start server
+server.run
+----
+
+=== Dynamic work sources
+
+Combine multiple work sources:
 
 [source,ruby]
 ----
-# Get all error results
-error_results = supervisor.results.errors
+work_queue = Fractor::WorkQueue.new
 
-# Extract error messages
-error_messages = error_results.map(&:error)
+# Source 1: HTTP requests
+http_server.on_request do |request|
+  work_queue << HttpWork.new(request)
+end
 
-# Get the work items that failed
-failed_work_items = error_results.map(&:work)
+# Source 2: Message queue
+message_queue.subscribe do |message|
+  work_queue << MessageWork.new(message)
+end
+
+# Source 3: Scheduled tasks
+scheduler.every('1m') do
+  work_queue << ScheduledWork.new(Time.now)
+end
+
+# Single server processes all work types
+server = Fractor::ContinuousServer.new(
+  worker_pools: [
+    { worker_class: HttpWorker, num_workers: 4 },
+    { worker_class: MessageWorker, num_workers: 2 },
+    { worker_class: ScheduledWorker, num_workers: 1 }
+  ],
+  work_queue: work_queue
+)
+
+server.run
 ----
 
+=== Graceful shutdown strategies
 
-[TIP]
-====
-* Check both successful results and errors after processing completes
-* Consider implementing custom reporting based on the aggregated results
-====
+==== Signal-based shutdown (production)
 
+[source,ruby]
+----
+# Server automatically handles SIGTERM
+server = Fractor::ContinuousServer.new(
+  worker_pools: [{ worker_class: MyWorker }],
+  work_queue: work_queue,
+  log_file: '/var/log/myapp/server.log'
+)
 
-=== WrappedRactor class
+# Just run the server - signals handled automatically
+server.run
 
-==== Purpose and responsibilities
+# In production:
+# systemctl stop myapp  # Sends SIGTERM
+# docker stop container # Sends SIGTERM
+# kill -TERM <pid>      # Manual SIGTERM
+----
 
-The `Fractor::WrappedRactor` class manages an individual Ruby Ractor, handling
-the communication between the Supervisor and the Worker instance running inside
-the Ractor.
+==== Time-based shutdown
 
-==== Usage notes
+[source,ruby]
+----
+server_thread = Thread.new { server.run }
 
-This class is primarily used internally by the Supervisor, but understanding its
-role helps with debugging:
+# Run for specific duration
+sleep 3600  # Run for 1 hour
+server.stop
+server_thread.join
+----
 
-* Each WrappedRactor creates and manages one Ractor
-* The Worker instance lives inside the Ractor
-* Work items are sent to the Ractor via the WrappedRactor's `send` method
-* Results are yielded back to the Supervisor
+==== Condition-based shutdown
 
-==== Error propagation
+[source,ruby]
+----
+server_thread = Thread.new { server.run }
+
+# Monitor thread checks conditions
+monitor = Thread.new do
+  loop do
+    if should_shutdown?
+      server.stop
+      break
+    end
+    sleep 10
+  end
+end
 
-The WrappedRactor handles error propagation in two ways:
+server_thread.join
+monitor.kill
+----
 
-. Errors from the Worker's `process` method are wrapped in a WorkResult and
-  yielded back
-. Unexpected errors in the Ractor itself are caught and logged
+=== Before/after comparison
 
+The chat server example demonstrates the real-world impact of using the
+high-level primitives.
 
-=== Supervisor class
+==== Before: Low-level API (279 lines)
 
-==== Purpose and responsibilities
+Required manual management of:
 
-The `Fractor::Supervisor` class orchestrates the entire framework, managing
-worker Ractors, distributing work, and collecting results.
+* Supervisor thread creation and lifecycle (~15 lines)
+* Results processing thread with loops (~50 lines)
+* Queue creation and synchronization (~10 lines)
+* Signal handling setup (~15 lines)
+* Thread coordination and shutdown (~20 lines)
+* IO.select event loop (~110 lines)
+* Manual error handling throughout (~59 lines)
 
-==== Configuration options
+==== After: High-level primitives (167 lines)
 
-When creating a Supervisor, you can configure:
+Eliminated boilerplate:
 
-[source,ruby]
-----
-supervisor = Fractor::Supervisor.new(
-  worker_pools: [
-    # Pool 1 - for general data processing
-    { worker_class: MyWorker, num_workers: 4 },
+* WorkQueue handles queue and synchronization (automatic)
+* ContinuousServer manages all threads (automatic)
+* Callbacks replace manual results loops (automatic)
+* Signal handling built-in (automatic)
+* Graceful shutdown coordinated (automatic)
 
-    # Pool 2 - for specialized image processing
-    { worker_class: ImageWorker, num_workers: 2 }
-  ],
-  continuous_mode: false      # Optional: Run in continuous mode (default: false)
-)
-----
+Result: **40% code reduction** (112 fewer lines), simpler architecture, fewer
+error-prone details.
 
-==== Adding work
+See link:examples/continuous_chat_fractor/chat_server.rb[the refactored chat
+server] for the complete example.
 
-You can add work items individually or in batches:
 
-[source,ruby]
+
+
+== Process monitoring and logging
+
+=== Status monitoring and health checks
+
+The signals SIGUSR1 (or SIGBREAK on Windows) can be used for health checks.
+
+When the signal is received, the supervisor prints its current status to
+standard output.
+
+[example]
+Sending the signal:
+
+Unix:
+
+[source,sh]
+----
+# Send SIGUSR1 to the supervisor process
+kill -USR1 <pid>
 ----
-# Add a single item
-supervisor.add_work_item(MyWork.new(42))
 
-# Add multiple items
-supervisor.add_work_items([
-  MyWork.new(1),
-  MyWork.new(2),
-  MyWork.new(3),
-  MyWork.new(4),
-  MyWork.new(5)
-])
+Windows:
 
-# Add items of different work types
-supervisor.add_work_items([
-  TextWork.new("Process this text"),
-  ImageWork.new({ width: 800, height: 600 })
-])
+[source,sh]
+----
+# Send SIGBREAK to the supervisor process
+kill -BREAK <pid>
 ----
 
-The Supervisor can handle any Work object that inherits from Fractor::Work.
-Workers must check the type of Work they receive and process it accordingly.
+Output:
 
-==== Running and monitoring
+[source]
+----
+=== Fractor Supervisor Status ===
+Mode: Continuous
+Running: true
+Workers: 4
+Idle workers: 2
+Queue size: 15
+Results: 127
+Errors: 3
+----
 
-To start processing:
+=== Logging
+
+Fractor supports logging of its operations to a specified log file.
+
+For ContinuousServer, pass the `log_file` parameter:
 
 [source,ruby]
 ----
-# Start processing and block until complete
-supervisor.run
+server = Fractor::ContinuousServer.new(
+  worker_pools: [{ worker_class: MyWorker }],
+  work_queue: work_queue,
+  log_file: 'logs/server.log'
+)
 ----
 
-The Supervisor automatically handles:
+For manual Supervisor usage, set the `FRACTOR_LOG_FILE` environment variable
+before starting your application:
 
-* Starting the worker Ractors
-* Distributing work items to available workers
-* Collecting results and errors
-* Graceful shutdown on completion or interruption (Ctrl+C)
+[source,sh]
+----
+export FRACTOR_LOG_FILE=/path/to/logs/server.log
+ruby my_fractor_app.rb
+----
 
+The log file will contain detailed information about the supervisor's
+operations, including worker activity, work distribution, results, and errors.
 
-==== Accessing results
+.Examples of accessing logs
+[example]
+[source,sh]
+----
+# Check if server is responsive (Unix/Linux/macOS)
+kill -USR1 <pid> && tail -f /path/to/logs/server.log
 
-After processing completes:
+# Monitor with systemd
+systemctl status fractor-server
+journalctl -u fractor-server -f
 
-[source,ruby]
+# Monitor with Docker
+docker logs -f <container_id>
 ----
-# Get the ResultAggregator
-aggregator = supervisor.results
 
-# Check counts
-puts "Processed #{aggregator.results.size} items successfully"
-puts "Encountered #{aggregator.errors.size} errors"
 
-# Access successful results
-aggregator.results.each do |result|
-  puts "Work item #{result.work.input} produced #{result.result}"
-end
 
-# Access errors
-aggregator.errors.each do |error_result|
-  puts "Work item #{error_result.work.input} failed: #{error_result.error}"
-end
-----
 
-== Advanced usage patterns
+== Signal handling
 
-=== Custom work distribution
+=== General
 
-For more complex scenarios, you might want to prioritize certain work items:
+Fractor provides production-ready signal handling for process control and
+monitoring. The framework supports different signals depending on the operating
+system, enabling graceful shutdown and runtime status monitoring.
 
-[source,ruby]
-----
-# Create Work objects for high priority items
-high_priority_works = high_priority_items.map { |item| MyWork.new(item) }
+=== Unix signals (Linux, macOS, Unix)
 
-# Add high-priority items first
-supervisor.add_work_items(high_priority_works)
+==== SIGINT (Ctrl+C)
 
-# Run with just enough workers for high-priority items
-supervisor.run
+Interactive interrupt signal for graceful shutdown.
 
-# Create Work objects for lower priority items
-low_priority_works = low_priority_items.map { |item| MyWork.new(item) }
+Usage:
 
-# Add and process lower-priority items
-supervisor.add_work_items(low_priority_works)
-supervisor.run
+* Press `Ctrl+C` in the terminal running Fractor
+* Behavior depends on mode:
+** *Batch mode*: Stops immediately after current work completes
+** *Continuous mode*: Initiates graceful shutdown
+
+==== SIGTERM
+
+Standard Unix termination signal, preferred for production deployments.
+
+This ensures a graceful shutdown of the Fractor supervisor and its workers.
+
+Usage:
+
+[source,sh]
+----
+kill -TERM <pid>
+# or simply
+kill <pid>  # SIGTERM is the default
 ----
 
-=== Handling large datasets
+Typical signals from service managers:
 
-For very large datasets, consider processing in batches:
+* Systemd sends SIGTERM on `systemctl stop`
+* Docker sends SIGTERM on `docker stop`
+* Kubernetes sends SIGTERM during pod termination
 
-[source,ruby]
+[source,ini]
+----
+# Example systemd service
+[Service]
+ExecStart=/usr/bin/ruby /path/to/fractor_server.rb
+KillMode=process
+KillSignal=SIGTERM
+TimeoutStopSec=30
 ----
-large_dataset.each_slice(1000) do |batch|
-  # Convert batch items to Work objects
-  work_batch = batch.map { |item| MyWork.new(item) }
 
-  supervisor.add_work_items(work_batch)
-  supervisor.run
+==== SIGUSR1
 
-  # Process this batch's results before continuing
-  process_batch_results(supervisor.results)
-end
+Real-time status monitoring without stopping the process.
+
+Usage:
+
+[source,sh]
+----
+kill -USR1 <pid>
+----
+
+Output example:
+
+[example]
+[source]
 ----
+=== Fractor Supervisor Status ===
+Mode: Continuous
+Running: true
+Workers: 4
+Idle workers: 2
+Queue size: 15
+Results: 127
+Errors: 3
+----
+
+=== Windows signals
+
+==== SIGBREAK (Ctrl+Break)
+
+Windows alternative to SIGUSR1 for status monitoring.
+
+Usage:
+
+* Press `Ctrl+Break` in the terminal running Fractor
+* Same output as SIGUSR1 on Unix
+
+[NOTE]
+SIGUSR1 is not available on Windows. Use `Ctrl+Break` instead for status
+monitoring on Windows platforms.
+
+
+=== Signal behavior by mode
+
+==== Batch mode
+
+In batch processing mode:
+
+* SIGINT/SIGTERM: Stops immediately after current work completes
+* SIGUSR1/SIGBREAK: Displays current status
+
+==== Continuous mode
+
+In continuous mode (long-running servers):
+
+* SIGINT/SIGTERM: Graceful shutdown within ~2 seconds
+** Stops accepting new work
+** Completes in-progress work
+** Cleans up resources
+* SIGUSR1/SIGBREAK: Displays current status
+
+
 
 
 == Running a basic example
@@ -756,7 +1814,10 @@ class MyWorker < Fractor::Worker
   def process(work)
     if work.input == 5
       # Return a Fractor::WorkResult for errors
-      return Fractor::WorkResult.new(error: "Error processing work #{work.input}", work: work)
+      return Fractor::WorkResult.new(
+        error: "Error processing work #{work.input}",
+        work: work
+      )
     end
 
     calculated = work.input * 2
@@ -798,81 +1859,6 @@ the final aggregated results, including any errors encountered. Press `Ctrl+C`
 during execution to test the graceful shutdown.
 
 
-== Continuous mode
-
-=== General
-
-Fractor provides a powerful feature called "continuous mode" that allows
-supervisors to run indefinitely, processing work items as they arrive without
-stopping after the initial work queue is empty.
-
-=== Features
-
-* *Non-stopping Execution*: Supervisors run indefinitely until explicitly stopped
-* *On-demand Work*: Workers only process work when it's available
-* *Resource Efficiency*: Workers idle when no work is available, without consuming excessive resources
-* *Dynamic Work Addition*: New work can be added at any time through the work source callback
-* *Graceful Shutdown*: Resources are properly cleaned up when the supervisor is stopped
-
-Continuous mode is particularly useful for:
-
-* *Chat servers*: Processing incoming messages as they arrive
-* *Background job processors*: Handling tasks from a job queue
-* *Real-time data processing*: Analyzing data streams as they come in
-* *Web servers*: Responding to incoming requests in parallel
-* *Monitoring systems*: Continuously checking system statuses
-
-See the Chat Server example in the examples directory for a complete implementation of continuous mode.
-
-
-=== Using continuous mode
-
-==== Step 1. Create a supervisor with the `continuous_mode: true` option
-
-[source,ruby]
-----
-supervisor = Fractor::Supervisor.new(
-  worker_pools: [
-    { worker_class: MyWorker, num_workers: 2 }
-  ],
-  continuous_mode: true  # Enable continuous mode
-)
-----
-
-==== Step 2. Register a work source callback that provides new work on demand
-
-[source,ruby]
-----
-supervisor.register_work_source do
-  # Return nil or empty array if no work is available
-  # Return a work item or array of work items when available
-  items = get_next_work_items
-  if items && !items.empty?
-    # Convert to Work objects if needed
-    items.map { |item| MyWork.new(item) }
-  else
-    nil
-  end
-end
-----
-
-==== Step 4. Run the supervisor in a non-blocking way
-
-Typically in a background thread.
-
-[source,ruby]
-----
-supervisor_thread = Thread.new { supervisor.run }
-----
-
-==== Step 4. Explicitly call `stop` on the supervisor to stop processing
-
-[source,ruby]
-----
-supervisor.stop
-supervisor_thread.join  # Wait for the supervisor thread to finish
-----
-
 
 
 == Example applications
@@ -883,7 +1869,9 @@ The Fractor gem comes with several example applications that demonstrate various
 patterns and use cases. Each example can be found in the `examples` directory of
 the gem repository. Detailed descriptions for these are provided below.
 
-=== Simple example
+=== Pipeline mode examples
+
+==== Simple example
 
 The Simple Example (link:examples/simple/[examples/simple/]) demonstrates the
 basic usage of the Fractor framework. It shows how to create a simple Work
@@ -897,9 +1885,26 @@ Key features:
 * Simple Supervisor setup
 * Parallel processing of work items
 * Error handling and result aggregation
+* Auto-detection of available processors
 * Graceful shutdown on completion
 
-=== Hierarchical hasher
+==== Auto-detection example
+
+The Auto-Detection Example
+(link:examples/auto_detection/[examples/auto_detection/]) demonstrates
+Fractor's automatic worker detection feature. It shows how to use
+auto-detection, explicit configuration, and mixed approaches for controlling
+the number of workers.
+
+Key features:
+
+* Automatic detection of available processors
+* Comparison of auto-detection vs explicit configuration
+* Mixed configuration with multiple worker pools
+* Best practices for worker configuration
+* Portable code that adapts to different environments
+
+==== Hierarchical hasher
 
 The Hierarchical Hasher example
 (link:examples/hierarchical_hasher/[examples/hierarchical_hasher/]) demonstrates
@@ -914,7 +1919,7 @@ Key features:
 * Independent processing of data segments
 * Aggregation of results to form a final output
 
-=== Multi-work type
+==== Multi-work type
 
 The Multi-Work Type example
 (link:examples/multi_work_type/[examples/multi_work_type/]) demonstrates how a
@@ -928,7 +1933,7 @@ Key features:
 * Polymorphic worker processing based on work type
 * Unified workflow for diverse tasks
 
-=== Pipeline processing
+==== Pipeline processing
 
 The Pipeline Processing example
 (link:examples/pipeline_processing/[examples/pipeline_processing/]) implements a
@@ -942,7 +1947,7 @@ Key features:
 * Concurrent execution of different pipeline stages
 * Data transformation at each step of the pipeline
 
-=== Producer/subscriber
+==== Producer/subscriber
 
 The Producer/Subscriber example
 (link:examples/producer_subscriber/[examples/producer_subscriber/]) showcases a
@@ -956,7 +1961,7 @@ Key features:
 * Dynamic generation of sub-work based on initial processing
 * Construction of hierarchical result structures
 
-=== Scatter/gather
+==== Scatter/gather
 
 The Scatter/Gather example
 (link:examples/scatter_gather/[examples/scatter_gather/]) illustrates how a
@@ -971,7 +1976,7 @@ Key features:
 * Concurrent processing of subtasks
 * Aggregation of partial results into a final result
 
-=== Specialized workers
+==== Specialized workers
 
 The Specialized Workers example
 (link:examples/specialized_workers/[examples/specialized_workers/]) demonstrates
@@ -986,10 +1991,59 @@ Key features:
 * Routing of work items to appropriately specialized workers
 * Optimization of resources and logic per task type
 
+=== Continuous mode examples
+
+==== Plain socket implementation
+
+The plain socket implementation
+(link:examples/continuous_chat_server/[examples/continuous_chat_server/])
+provides a baseline chat server using plain TCP sockets without Fractor. This
+serves as a comparison point to understand the benefits of using Fractor for
+continuous processing.
+
+==== Fractor-based implementation
+
+The Fractor-based implementation
+(link:examples/continuous_chat_fractor/[examples/continuous_chat_fractor/])
+demonstrates how to build a production-ready chat server using Fractor's
+continuous mode with high-level primitives.
+
+Key features:
+
+* *Continuous mode operation*: Server runs indefinitely processing messages as
+  they arrive
+* *High-level primitives*: Uses WorkQueue and ContinuousServer to eliminate
+  boilerplate
+* *Graceful shutdown*: Production-ready signal handling (SIGINT, SIGTERM,
+  SIGUSR1/SIGBREAK)
+* *Callback-based results*: Clean separation of concerns with on_result and
+  on_error callbacks
+* *Cross-platform support*: Works on Unix/Linux/macOS and Windows
+* *Process monitoring*: Runtime status checking via signals
+* *40% code reduction*: 167 lines vs 279 lines with low-level API
+
+The implementation includes:
+
+* `chat_common.rb`: Work and Worker class definitions for chat message
+  processing
+* `chat_server.rb`: Main server using high-level primitives
+* `simulate.rb`: Test client simulator
+
+This example demonstrates production deployment patterns including:
+
+* Systemd service integration
+* Docker container deployment
+* Process monitoring and health checks
+* Graceful restart procedures
+
+See link:examples/continuous_chat_fractor/README.adoc[the chat server README]
+for detailed implementation documentation.
+
+
 
 
 == Copyright and license
 
 Copyright Ribose.
 
-Licensed under the MIT License.
+Licensed under the Ribose BSD 2-Clause License.