fractor 0.1.6 → 0.1.7

data/README.adoc

@@ -1,2049 +1,222 @@
 = Fractor: Function-driven Ractors framework
 
-Fractor is a lightweight Ruby framework designed to simplify the process of
-distributing computational work across multiple Ractors.
+image:https://img.shields.io/gem/v/fractor.svg[RubyGems Version, link=https://rubygems.org/gems/fractor]
+image:https://img.shields.io/github/license/metanorma/fractor.svg[License, link=https://github.com/metanorma/fractor/blob/main/LICENSE]
+image:https://github.com/metanorma/fractor/actions/workflows/rake.yml/badge.svg[Build Status, link=https://github.com/metanorma/fractor/actions/workflows/rake.yml]
+image:https://img.shields.io/badge/ruby-3.0%20%E2%86%92%204.0%2B-ruby.svg[Ruby 3.0 to 4.0+, link=https://www.ruby-lang.org]
 
-== Introduction
+Fractor is a lightweight Ruby framework for parallel processing using Ractors
+(Ruby Actors).
 
-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).
+It provides a structured way to distribute computational work across multiple
+Ractors with minimal boilerplate.
 
-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
-abstracting away much of the boilerplate code involved in Ractor management and
-communication.
+== Ruby version support
 
-== Installation
+Fractor fully supports both **Ruby 3.x** and **Ruby 4.0+**:
 
-=== Using RubyGems
+* *Ruby 3.0+*: Uses `Ractor.yield` for message passing from workers
 
-[source,sh]
-----
-gem install fractor
-----
+* *Ruby 4.0+*: Uses `Ractor::Port` for more efficient communication patterns
 
-=== Using Bundler
+Fractor automatically detects your Ruby version and uses the appropriate
+internal implementation. The user-facing API is identical across versions --
+write your code once, and Fractor handles the differences internally.
 
-Add this line to your application's Gemfile:
+See
+link:docs/_pages/architecture.adoc#ruby-version-compatibility[Architecture: Ruby Version Compatibility]
+for details on the internal differences.
 
-[source,ruby]
-----
-gem 'fractor'
-----
+== Quick start
 
-And then execute:
+=== Installation
 
 [source,sh]
 ----
-bundle install
+gem install fractor
 ----
 
+See link:docs/_pages/installation.adoc[Installation Guide] for more options.
 
-=== Key concepts
-
-* *Function-driven:* You define the core processing logic by subclassing
-  `Fractor::Worker` and implementing the `process` method.
-
-* *Parallel execution:* Work items are automatically distributed to available
-  worker Ractors for concurrent processing.
-
-* *Result aggregation:* The framework collects both successful results and
-  errors from the workers.
-
-* *Separation of concerns:* Keeps the framework logic (`fractor.rb`) separate
-  from the client's specific implementation (`sample.rb`).
-
-== Scope
-
-This document describes the design, implementation, and usage of the Fractor
-framework. It provides detailed information about the framework's components,
-their interactions, and how to use them to implement parallel processing in Ruby
-applications.
-
-[bibliography]
-== Normative references
-
-* [[[ruby-ractor,Ruby Ractor Documentation]]], https://docs.ruby-lang.org/en/master/Ractor.html
-
-== Terms and definitions
-
-=== ractor
-
-concurrent programming abstraction in Ruby that enables parallel execution
-with thread safety
-
-[.source]
-<<ruby>>
-
-=== worker
-
-component that processes work items to produce work results
-
-=== work item
-
-unit of computation to be processed by a ractor
-
-=== work result
-
-result of processing a work item, either successful or an error
-
-=== work item class
-
-class that represents a work item, typically subclassing `Fractor::Work`
-
-=== worker class
-
-class that represents a worker, typically subclassing `Fractor::Worker`
-
-=== wrapped ractor
-
-component that manages a single ractor and its associated worker
-
-=== supervisor
-
-component that manages the pool of workers and distributes work items
-
-=== result aggregator
-
-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
-
-operating mode where Fractor runs indefinitely, processing work items as they
-arrive
-
-
-
-
-== Understanding Fractor operating modes
-
-=== General
-
-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.
-
-=== Pipeline mode (batch processing)
-
-Pipeline mode is designed for processing a defined set of work items with a
-clear beginning and end.
-
-Characteristics:
-
-* 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
-
-Common use cases:
-
-* Processing a file or dataset
-* Batch data transformations
-* One-time parallel computations
-* Scheduled batch jobs
-* Hierarchical or multi-stage processing
-
-=== Continuous mode (long-running servers)
-
-Continuous mode is designed for applications that need to run indefinitely,
-processing work items as they arrive.
-
-Characteristics:
-
-* 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
-
-Common use cases:
-
-* 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
-
-=== Comparison
-
-[cols="1,2,2",options="header"]
-|===
-|Aspect |Pipeline Mode |Continuous Mode
-
-|Duration
-|Finite (stops when done)
-|Indefinite (runs until stopped)
-
-|Work arrival
-|All work known upfront
-|Work arrives dynamically
-
-|Result handling
-|Batch collection after completion
-|Callback-based processing
-
-|Typical lifetime
-|Seconds to minutes
-|Hours to days/weeks
-
-|Shutdown
-|Automatic on completion
-|Manual or signal-based
-
-|Best for
-|Batch jobs, file processing
-|Servers, streams, job queues
-|===
-
-=== Decision guide
-
-Choose *Pipeline mode* when:
-
-* 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
-
-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
-
-
-
-
-== Quick start: Pipeline mode
-
-=== General
-
-This quick start guide shows the minimum steps needed to get parallel batch
-processing working with Fractor.
-
-=== Step 1: Create a minimal Work class
-
-The Work class represents a unit of work to be processed by a Worker. It
-encapsulates the input data needed for processing.
+=== 30-second example
 
 [source,ruby]
 ----
 require 'fractor'
 
+# Define your work
 class MyWork < Fractor::Work
-  # Store all properties in the input hash
   def initialize(value)
     super({ value: value })
   end
 
-  # Accessor method for the stored value
   def value
     input[:value]
   end
-
-  def to_s
-    "MyWork: #{value}"
-  end
 end
-----
-
-A Work is instantiated with the input data it will process this way:
-
-[source,ruby]
-----
-work_item = MyWork.new(42)
-puts work_item.to_s  # Output: MyWork: 42
-----
-
-
-=== Step 2: Create a minimal Worker class
 
-The Worker class defines the processing logic for work items. Each Worker
-instance runs within its own Ractor and processes Work objects sent to it.
-
-It must implement the `process(work)` method, which takes a Work object as
-input and returns a `Fractor::WorkResult` object.
-
-The `process` method should handle both successful processing and error
-conditions.
-
-[source,ruby]
-----
+# Define your worker
 class MyWorker < Fractor::Worker
   def process(work)
-    # Your processing logic here
-    result = work.input * 2
-
-    # Return a success result
+    result = work.value * 2
     Fractor::WorkResult.new(result: result, work: work)
   rescue => e
-    # Return an error result if something goes wrong
     Fractor::WorkResult.new(error: e.message, work: work)
   end
 end
-----
-
-The `process` method can perform any computation you need. In this example, it
-multiplies the input by 2. If an error occurs, it catches the exception and
-returns an error result.
 
-=== Step 3: Set up and run the Supervisor
-
-The Supervisor class orchestrates the entire framework, managing worker Ractors,
-distributing work, and collecting results.
-
-[source,ruby]
-----
-# Create the supervisor with auto-detected number of workers
+# Create supervisor and process work
 supervisor = Fractor::Supervisor.new(
-  worker_pools: [
-    { worker_class: MyWorker }  # Number of workers auto-detected
-  ]
+  worker_pools: [{ worker_class: MyWorker }]
 )
 
-# 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)
+  MyWork.new(3)
 ])
 
-# Run the processing
 supervisor.run
 
-# Access results after completion
 puts "Results: #{supervisor.results.results.map(&:result)}"
-puts "Errors: #{supervisor.results.errors.size}"
+# => Results: [2, 4, 6]
 ----
 
-That's it! With these three simple steps, you have a working parallel processing
-system using Fractor in pipeline mode.
+== Key features
 
+* *Function-driven*: Define processing logic by subclassing `Fractor::Worker`
+* *Parallel execution*: Work automatically distributed across Ractor workers
+* *Two operating modes*:
+  ** **Pipeline mode** for batch processing
+  ** **Continuous mode** for long-running servers
+* *Workflow system*: GitHub Actions-style declarative workflows
+* *Error handling*: Retry logic, circuit breakers, dead letter queues, error reporting
+* *Production-ready*: Signal handling, logging, monitoring, graceful shutdown
+* *Performance tools*: Built-in monitoring, benchmarking, and error analytics
+* *High-level primitives*: WorkQueue and ContinuousServer eliminate boilerplate
 
+== Documentation
 
+=== Getting started
 
-== Quick start: Continuous mode
+* link:docs/_pages/installation.adoc[Installation] - System requirements and installation methods
+* link:docs/_pages/getting-started.adoc[Getting Started] - Quick start guides for both modes
+* link:docs/_pages/core-concepts.adoc[Core Concepts] - Understanding Fractor components
 
-=== General
+=== Operating modes
 
-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.
+* link:docs/_guides/pipeline-mode.adoc[Pipeline Mode] - Batch processing with predefined work
+* link:docs/_guides/continuous-mode.adoc[Continuous Mode] - Long-running servers and streaming
 
-=== Step 1: Create Work and Worker classes
+=== Advanced features
 
-Just like pipeline mode, you need Work and Worker classes:
+* link:docs/_features/workflows.adoc[Workflows] - Declarative workflow system for complex pipelines
+* link:docs/_features/error-handling.adoc[Error Handling] - Retry logic, circuit breakers, and dead letter queues
+* link:docs/_features/monitoring.adoc[Monitoring] - Performance monitoring and metrics
+* link:docs/_features/signal-handling.adoc[Signal Handling] - Process monitoring and graceful shutdown
 
-[source,ruby]
-----
-require 'fractor'
-
-class MessageWork < Fractor::Work
-  def initialize(client_id, message)
-    super({ client_id: client_id, message: message })
-  end
+=== Reference
 
-  def client_id
-    input[:client_id]
-  end
+* link:docs/_reference/api.adoc[API Reference] - Complete API documentation
+* link:docs/_reference/examples.adoc[Examples] - Complete examples for all patterns
+* link:docs/_reference/troubleshooting.adoc[Troubleshooting] - Common issues and solutions
 
-  def message
-    input[:message]
-  end
-end
+== Operating modes
 
-class MessageWorker < Fractor::Worker
-  def process(work)
-    # Process the message
-    processed = "Echo: #{work.message}"
+Fractor supports two distinct modes:
 
-    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
-----
+[cols="1,2,2",options="header"]
+|===
+|Mode |Best for |Example use cases
 
-=== Step 2: Set up WorkQueue
+|*Pipeline Mode*
+|Batch processing, one-time jobs
+|File processing, ETL pipelines, data transformations
 
-Create a thread-safe work queue that will hold incoming work items:
+|*Continuous Mode*
+|Long-running servers, streaming
+|Chat servers, job processors, event streams
+|===
 
-[source,ruby]
-----
-# Create a thread-safe work queue
-work_queue = Fractor::WorkQueue.new
-----
+See link:docs/getting-started.adoc#choosing-your-mode[Choosing Your Mode] for detailed guidance.
 
-=== Step 3: Set up ContinuousServer with callbacks
+== Example applications
 
-The ContinuousServer handles all the boilerplate: thread management, signal
-handling, and results processing.
+=== Pipeline mode
 
 [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
+supervisor = Fractor::Supervisor.new(
+  worker_pools: [{ worker_class: DataWorker }]
 )
 
-# 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.
-
-Pipeline mode uses only the core components without any additional primitives.
-
-=== Work class
-
-==== Purpose and responsibilities
-
-The `Fractor::Work` class represents a unit of work to be processed by a Worker.
-Its primary responsibility is to encapsulate the input data needed for
-processing.
-
-==== Implementation requirements
-
-At minimum, your Work subclass should:
-
-. Inherit from `Fractor::Work`
-. Pass the input data to the superclass constructor
+supervisor.add_work_items(dataset.map { |item| DataWork.new(item) })
+supervisor.run
 
-[source,ruby]
-----
-class MyWork < Fractor::Work
-  def initialize(input)
-    super(input) # This stores input in @input
-    # Add any additional initialization if needed
-  end
-end
+puts "Processed #{supervisor.results.results.size} items"
 ----
 
-==== Advanced usage
+See link:examples/simple/[Simple Example] and link:docs/examples.adoc#pipeline-mode-examples[more examples].
 
-You can extend your Work class to include additional data or methods:
+=== Continuous mode
 
 [source,ruby]
 ----
-class ComplexWork < Fractor::Work
-  attr_reader :options
-
-  def initialize(input, options = {})
-    super(input)
-    @options = options
-  end
-
-  def high_priority?
-    @options[:priority] == :high
-  end
-
-  def to_s
-    "ComplexWork: #{@input} (#{@options[:priority]} priority)"
-  end
-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
-====
-
-=== Worker class
-
-==== Purpose and responsibilities
-
-The `Fractor::Worker` class defines the processing logic for work items. Each
-Worker instance runs within its own Ractor and processes Work objects sent to
-it.
-
-==== Implementation requirements
-
-Your Worker subclass must:
-
-. Inherit from `Fractor::Worker`
-. Implement the `process(work)` method
-. Return a `Fractor::WorkResult` object from the `process` method
-. Handle both successful processing and error conditions
+work_queue = Fractor::WorkQueue.new
 
-[source,ruby]
-----
-class MyWorker < Fractor::Worker
-  def process(work)
-    # Process the work
+server = Fractor::ContinuousServer.new(
+  worker_pools: [{ worker_class: MessageWorker, num_workers: 4 }],
+  work_queue: work_queue
+)
 
-    if work.input < 0
-      return Fractor::WorkResult.new(
-        error: "Cannot process negative numbers",
-        work: work
-      )
-    end
+server.on_result { |result| puts "Processed: #{result.result}" }
+server.on_error { |error| puts "Error: #{error.error}" }
 
-    # Normal processing...
-    result = work.input * 2
+Thread.new { server.run }
 
-    # Return a WorkResult
-    Fractor::WorkResult.new(result: result, work: work)
-  end
-end
+# Add work dynamically
+work_queue << MessageWork.new(client_id: 1, message: "Hello")
 ----
 
+See link:examples/continuous_chat_fractor/[Chat Server Example] and link:docs/examples.adoc#continuous-mode-examples[more examples].
 
-==== Error handling
-
-The Worker class should handle two types of errors.
-
-
-===== Handled errors
-
-These are expected error conditions that your code explicitly checks for.
+=== Workflows
 
 [source,ruby]
 ----
-def process(work)
-  if work.input < 0
-    return Fractor::WorkResult.new(
-      error: "Cannot process negative numbers",
-      work: work
-    )
-  end
-
-  # Normal processing...
-  Fractor::WorkResult.new(result: calculated_value, work: work)
+# Define workflow with simplified syntax
+workflow = Fractor::Workflow.define("data-pipeline") do
+  job :extract, ExtractWorker
+  job :transform, TransformWorker, needs: :extract
+  job :load, LoadWorker, needs: :transform
 end
-----
-
-===== Unexpected errors caught by rescue
 
-These are unexpected exceptions that may occur during processing. You should
-catch these and convert them into error results.
-
-[source,ruby]
+# Execute workflow
+result = workflow.new.execute(input_data)
 ----
-def process(work)
-  # Processing that might raise exceptions
-  result = complex_calculation(work.input)
-
-  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
-  )
-end
-----
-
-[TIP]
-====
-* Keep the `process` method focused on a single responsibility
-* Use meaningful error messages that help diagnose issues
-* Consider adding logging within the `process` method for debugging
-* Ensure all paths return a valid `WorkResult` object
-====
-
-=== Supervisor class for pipeline mode
 
-==== Purpose and responsibilities
+See link:examples/workflow/simplified/README.adoc[Simplified Workflows] and link:docs/workflows.adoc[Workflow Guide].
 
-The `Fractor::Supervisor` class orchestrates the entire framework, managing
-worker Ractors, distributing work, and collecting results.
+== Production deployment
 
-==== Configuration options
+Fractor includes production-ready features:
 
-When creating a Supervisor for pipeline mode, configure worker pools:
+* **Signal handling**: SIGTERM, SIGINT, SIGUSR1/SIGBREAK
+* **Graceful shutdown**: Complete in-progress work before exit
+* **Process monitoring**: Runtime status via signals
+* **Structured logging**: JSON logging with correlation IDs
+* **Workflow visualization**: Mermaid, DOT, ASCII diagrams
 
-[source,ruby]
-----
-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
-)
-----
-
-==== Worker auto-detection
+See link:docs/signal-handling.adoc[Signal Handling Guide] for deployment patterns.
 
-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]
-----
-# Auto-detect number of workers (recommended for most cases)
-supervisor = Fractor::Supervisor.new(
-  worker_pools: [
-    { worker_class: MyWorker }  # Will use number of available processors
-  ]
-)
+== Contributing
 
-# 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
-  ]
-)
+Bug reports and pull requests are welcome on GitHub at https://github.com/metanorma/fractor.
 
-# 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
-  ]
-)
-----
+== License
 
-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.
+The gem is available as open source under the terms of the Ribose BSD 2-Clause License.
 
-[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 add work items individually or in batches:
-
-[source,ruby]
-----
-# 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 })
-])
-----
-
-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
-
-To start processing:
-
-[source,ruby]
-----
-# Start processing and block until complete
-supervisor.run
-----
-
-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.
-
-In pipeline mode, results are collected throughout processing and accessed
-after the supervisor finishes running.
-
-==== Accessing results
-
-After processing completes:
-
-[source,ruby]
-----
-# 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:
-
-[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]
-----
-work_queue = Fractor::WorkQueue.new
-
-# Source 1: HTTP requests
-http_server.on_request do |request|
-  work_queue << HttpWork.new(request)
-end
-
-# 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
-
-==== 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'
-)
-
-# Just run the server - signals handled automatically
-server.run
-
-# In production:
-# systemctl stop myapp  # Sends SIGTERM
-# docker stop container # Sends SIGTERM
-# kill -TERM <pid>      # Manual SIGTERM
-----
-
-==== Time-based shutdown
-
-[source,ruby]
-----
-server_thread = Thread.new { server.run }
-
-# Run for specific duration
-sleep 3600  # Run for 1 hour
-server.stop
-server_thread.join
-----
-
-==== Condition-based shutdown
-
-[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
-
-server_thread.join
-monitor.kill
-----
-
-=== Before/after comparison
-
-The chat server example demonstrates the real-world impact of using the
-high-level primitives.
-
-==== Before: Low-level API (279 lines)
-
-Required manual management of:
-
-* 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)
-
-==== After: High-level primitives (167 lines)
-
-Eliminated boilerplate:
-
-* 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)
-
-Result: **40% code reduction** (112 fewer lines), simpler architecture, fewer
-error-prone details.
-
-See link:examples/continuous_chat_fractor/chat_server.rb[the refactored chat
-server] for the complete example.
-
-
-
-
-== 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>
-----
-
-Windows:
-
-[source,sh]
-----
-# Send SIGBREAK to the supervisor process
-kill -BREAK <pid>
-----
-
-Output:
-
-[source]
-----
-=== Fractor Supervisor Status ===
-Mode: Continuous
-Running: true
-Workers: 4
-Idle workers: 2
-Queue size: 15
-Results: 127
-Errors: 3
-----
-
-=== Logging
-
-Fractor supports logging of its operations to a specified log file.
-
-For ContinuousServer, pass the `log_file` parameter:
-
-[source,ruby]
-----
-server = Fractor::ContinuousServer.new(
-  worker_pools: [{ worker_class: MyWorker }],
-  work_queue: work_queue,
-  log_file: 'logs/server.log'
-)
-----
-
-For manual Supervisor usage, set the `FRACTOR_LOG_FILE` environment variable
-before starting your application:
-
-[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.
-
-.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
-
-# Monitor with systemd
-systemctl status fractor-server
-journalctl -u fractor-server -f
-
-# Monitor with Docker
-docker logs -f <container_id>
-----
-
-
-
-
-== Signal handling
-
-=== General
-
-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.
-
-=== Unix signals (Linux, macOS, Unix)
-
-==== SIGINT (Ctrl+C)
-
-Interactive interrupt signal for graceful shutdown.
-
-Usage:
-
-* 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
-----
-
-Typical signals from service managers:
-
-* Systemd sends SIGTERM on `systemctl stop`
-* Docker sends SIGTERM on `docker stop`
-* Kubernetes sends SIGTERM during pod termination
-
-[source,ini]
-----
-# Example systemd service
-[Service]
-ExecStart=/usr/bin/ruby /path/to/fractor_server.rb
-KillMode=process
-KillSignal=SIGTERM
-TimeoutStopSec=30
-----
-
-==== SIGUSR1
-
-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
-
-. Install the gem as described in the Installation section.
-
-. Create a new Ruby file (e.g., `my_fractor_example.rb`) with your
-implementation:
-
-[source,ruby]
-----
-require 'fractor'
-
-# Define your Work class
-class MyWork < Fractor::Work
-  def to_s
-    "MyWork: #{@input}"
-  end
-end
-
-# Define your Worker class
-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
-      )
-    end
-
-    calculated = work.input * 2
-    # Return a Fractor::WorkResult for success
-    Fractor::WorkResult.new(result: calculated, work: work)
-  end
-end
-
-# Create supervisor with a worker pool
-supervisor = Fractor::Supervisor.new(
-  worker_pools: [
-    { worker_class: MyWorker, num_workers: 2 }
-  ]
-)
-
-# Create Work objects
-work_items = (1..10).map { |i| MyWork.new(i) }
-
-# Add work items
-supervisor.add_work_items(work_items)
-
-# Run processing
-supervisor.run
-
-# Display results
-puts "Results: #{supervisor.results.results.map(&:result).join(', ')}"
-puts "Errors: #{supervisor.results.errors.map { |e| e.work.input }.join(', ')}"
-----
-
-. Run the example from your terminal:
-
-[source,sh]
-----
-ruby my_fractor_example.rb
-----
-
-You will see output showing Ractors starting, receiving work, processing it, and
-the final aggregated results, including any errors encountered. Press `Ctrl+C`
-during execution to test the graceful shutdown.
-
-
-
-
-== Example applications
-
-=== General
-
-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.
-
-=== 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
-class, a Worker class, and a Supervisor to manage the processing of work items
-in parallel. This example serves as a starting point for understanding how to
-use Fractor.
-
-Key features:
-
-* Basic Work and Worker class implementation
-* Simple Supervisor setup
-* Parallel processing of work items
-* Error handling and result aggregation
-* Auto-detection of available processors
-* Graceful shutdown on completion
-
-==== 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
-how to use the Fractor framework to process a file in parallel by breaking it
-into chunks, hashing each chunk independently, and then combining the results
-into a final hash. This approach is useful for processing large files
-efficiently.
-
-Key features:
-
-* Parallel data chunking for large files
-* Independent processing of data segments
-* Aggregation of results to form a final output
-
-==== Multi-work type
-
-The Multi-Work Type example
-(link:examples/multi_work_type/[examples/multi_work_type/]) demonstrates how a
-single Fractor supervisor and worker can handle multiple types of work items
-(e.g., `TextWork` and `ImageWork`). The worker intelligently adapts its
-processing strategy based on the class of the incoming work item.
-
-Key features:
-
-* Support for multiple `Fractor::Work` subclasses
-* Polymorphic worker processing based on work type
-* Unified workflow for diverse tasks
-
-==== Pipeline processing
-
-The Pipeline Processing example
-(link:examples/pipeline_processing/[examples/pipeline_processing/]) implements a
-multi-stage processing pipeline where data flows sequentially through a series
-of transformations. The output of one stage becomes the input for the next, and
-different stages can operate concurrently on different data items.
-
-Key features:
-
-* Sequential data flow through multiple processing stages
-* Concurrent execution of different pipeline stages
-* Data transformation at each step of the pipeline
-
-==== Producer/subscriber
-
-The Producer/Subscriber example
-(link:examples/producer_subscriber/[examples/producer_subscriber/]) showcases a
-multi-stage document processing system where initial work (processing a
-document) can generate additional sub-work items (processing sections of the
-document). This creates a hierarchical processing pattern.
-
-Key features:
-
-* Implementation of producer-consumer patterns
-* Dynamic generation of sub-work based on initial processing
-* Construction of hierarchical result structures
-
-==== Scatter/gather
-
-The Scatter/Gather example
-(link:examples/scatter_gather/[examples/scatter_gather/]) illustrates how a
-large task or dataset is broken down (scattered) into smaller, independent
-subtasks. These subtasks are processed in parallel by multiple workers, and
-their results are then collected (gathered) and combined to produce the final
-output.
-
-Key features:
-
-* Distribution of a large task into smaller, parallelizable subtasks
-* Concurrent processing of subtasks
-* Aggregation of partial results into a final result
-
-==== Specialized workers
-
-The Specialized Workers example
-(link:examples/specialized_workers/[examples/specialized_workers/]) demonstrates
-creating distinct worker types, each tailored to handle specific kinds of tasks
-(e.g., `ComputeWorker` for CPU-intensive operations and `DatabaseWorker` for
-I/O-bound database interactions). This allows for optimized resource utilization
-and domain-specific logic.
-
-Key features:
-
-* Creation of worker classes for specific processing domains
-* 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
 
 Copyright Ribose.
-
-Licensed under the Ribose BSD 2-Clause License.