fractor 0.1.4 → 0.1.7

data/README.adoc

@@ -1,1061 +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
-
-
-
-
-== Core components
-
-=== General
-
-The Fractor framework consists of the following main classes, all residing
-within the `Fractor` module.
-
-
-=== 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).
-
-
-
-== Quick start
-
-=== General
-
-This quick start guide shows the minimum steps needed to get a simple parallel
-execution 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.
-
-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 optionally the number of workers to create. If you don't specify `num_workers`,
-Fractor will automatically detect the number of available processors on your system
-and use that value. 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 with auto-detected number of workers
-supervisor = Fractor::Supervisor.new(
-  worker_pools: [
-    { worker_class: MyWorker }  # Number of workers auto-detected
-  ]
-)
 
-# Or explicitly specify the number of workers
+# Create supervisor and process work
 supervisor = Fractor::Supervisor.new(
-  worker_pools: [
-    { worker_class: MyWorker, num_workers: 4 }  # Explicitly use 4 workers
-  ]
+  worker_pools: [{ worker_class: MyWorker }]
 )
 
-# Add individual work items (instances of Work subclasses)
-supervisor.add_work_item(MyWork.new(1))
-
-# Add multiple work items
 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")
+  MyWork.new(3)
 ])
 
-# Run the processing
 supervisor.run
 
-# Access results
 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.
-
-
-== Usage
-
-=== 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
-
-[source,ruby]
-----
-class MyWork < Fractor::Work
-  def initialize(input)
-    super(input) # This stores input in @input
-    # Add any additional initialization if needed
-  end
-end
-----
-
-==== Advanced usage
-
-You can extend your Work class to include additional data or methods:
-
-[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
-
-[source,ruby]
-----
-class MyWorker < Fractor::Worker
-  def process(work)
-    # Process the work
-
-    if work.input < 0
-      return Fractor::WorkResult.new(
-        error: "Cannot process negative numbers",
-        work: work
-      )
-    end
-
-    # Normal processing...
-    result = work.input * 2
-
-    # Return a WorkResult
-    Fractor::WorkResult.new(result: result, work: work)
-  end
-end
-----
-
-
-==== Error handling
-
-The Worker class should handle two types of errors.
-
-
-===== Handled errors
-
-These are expected error conditions that your code explicitly checks for.
-
-[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)
-end
+# => Results: [2, 4, 6]
 ----
 
-===== Unexpected errors caught by rescue
+== Key features
 
-These are unexpected exceptions that may occur during processing. You should
-catch these and convert them into error results.
+* *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
 
-[source,ruby]
-----
-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
-====
+== Documentation
 
-=== WorkResult class
+=== Getting started
 
-==== Purpose and responsibilities
+* 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
 
-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.
+=== Operating modes
 
-==== Creating results
+* 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
 
-To create a successful result:
+=== Advanced features
 
-[source,ruby]
-----
-# For successful processing
-Fractor::WorkResult.new(result: calculated_value, work: work_object)
-----
+* 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
 
-To create an error result:
+=== Reference
 
-[source,ruby]
-----
-# For error conditions
-Fractor::WorkResult.new(error: "Error message", work: work_object)
-----
+* 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
 
-==== Checking result status
+== Operating modes
 
-You can check if a result was successful:
+Fractor supports two distinct modes:
 
-[source,ruby]
-----
-if work_result.success?
-  # Handle successful result
-  processed_value = work_result.result
-else
-  # Handle error
-  error_message = work_result.error
-end
-----
+[cols="1,2,2",options="header"]
+|===
+|Mode |Best for |Example use cases
 
-==== Accessing original work
+|*Pipeline Mode*
+|Batch processing, one-time jobs
+|File processing, ETL pipelines, data transformations
 
-The original work item is always available:
+|*Continuous Mode*
+|Long-running servers, streaming
+|Chat servers, job processors, event streams
+|===
 
-[source,ruby]
-----
-original_work = work_result.work
-input_value = original_work.input
-----
+See link:docs/getting-started.adoc#choosing-your-mode[Choosing Your Mode] for detailed guidance.
 
-=== ResultAggregator class
-
-==== 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.
-
-
-==== Accessing results
-
-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
-====
-
-
-=== WrappedRactor class
-
-==== Purpose and responsibilities
-
-The `Fractor::WrappedRactor` class manages an individual Ruby Ractor, handling
-the communication between the Supervisor and the Worker instance running inside
-the Ractor.
-
-==== Usage notes
-
-This class is primarily used internally by the Supervisor, but understanding its
-role helps with debugging:
-
-* 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
-
-==== Error propagation
-
-The WrappedRactor handles error propagation in two ways:
-
-. 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
-
-
-=== Supervisor class
-
-==== Purpose and responsibilities
-
-The `Fractor::Supervisor` class orchestrates the entire framework, managing
-worker Ractors, distributing work, and collecting results.
-
-==== Configuration options
-
-When creating a Supervisor, you can configure:
-
-[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 }
-  ],
-  continuous_mode: false      # Optional: Run in continuous mode (default: false)
-)
-----
-
-==== Worker auto-detection
+== Example applications
 
-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.
+=== Pipeline mode
 
 [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
-  ]
-)
-
-# 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
-  ]
+  worker_pools: [{ worker_class: DataWorker }]
 )
-----
-
-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 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.add_work_items(dataset.map { |item| DataWork.new(item) })
 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)
-
-
-==== 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
+puts "Processed #{supervisor.results.results.size} items"
 ----
 
-== Advanced usage patterns
-
-=== Custom work distribution
+See link:examples/simple/[Simple Example] and link:docs/examples.adoc#pipeline-mode-examples[more examples].
 
-For more complex scenarios, you might want to prioritize certain work items:
+=== Continuous mode
 
 [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
-----
+work_queue = Fractor::WorkQueue.new
 
-=== 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
-----
-
-
-== 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 }
-  ]
+server = Fractor::ContinuousServer.new(
+  worker_pools: [{ worker_class: MessageWorker, num_workers: 4 }],
+  work_queue: work_queue
 )
 
-# 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(', ')}"
-----
+server.on_result { |result| puts "Processed: #{result.result}" }
+server.on_error { |error| puts "Error: #{error.error}" }
 
-. Run the example from your terminal:
+Thread.new { server.run }
 
-[source,sh]
+# Add work dynamically
+work_queue << MessageWork.new(client_id: 1, message: "Hello")
 ----
-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.
-
 
-== Continuous mode
+See link:examples/continuous_chat_fractor/[Chat Server Example] and link:docs/examples.adoc#continuous-mode-examples[more examples].
 
-=== 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
+=== Workflows
 
 [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
+# 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
-----
-
-==== 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
+# Execute workflow
+result = workflow.new.execute(input_data)
 ----
 
+See link:examples/workflow/simplified/README.adoc[Simplified Workflows] and link:docs/workflows.adoc[Workflow Guide].
 
+== Production deployment
 
-== 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.
-
-=== 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.
+Fractor includes production-ready features:
 
-Key features:
+* **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
 
-* 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
+See link:docs/signal-handling.adoc[Signal Handling Guide] for deployment patterns.
 
-=== Hierarchical hasher
+== Contributing
 
-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.
+Bug reports and pull requests are welcome on GitHub at https://github.com/metanorma/fractor.
 
-Key features:
+== License
 
-* Parallel data chunking for large files
-* Independent processing of data segments
-* Aggregation of results to form a final output
+The gem is available as open source under the terms of the Ribose BSD 2-Clause License.
 
-=== 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
-
-
-
-== Copyright and license
+== Copyright
 
 Copyright Ribose.
-
-Licensed under the MIT License.