fractor 0.1.8 → 0.1.10

data/docs/ARCHITECTURE.md

@@ -0,0 +1,317 @@
+# Fractor Architecture
+
+This document provides architecture diagrams and descriptions of the Fractor framework's components.
+
+## Overview
+
+Fractor is a function-driven Ractors framework for Ruby that provides true parallelism using Ruby's Ractor feature with automatic work distribution across isolated workers.
+
+## High-Level Architecture
+
+```mermaid
+graph TB
+    subgraph "Application Layer"
+        Work[Work<br/>Immutable Input]
+        Worker[Worker<br/>Processing Logic]
+        WorkResult[WorkResult<br/>Success/Error Output]
+    end
+
+    subgraph "Orchestration Layer"
+        Supervisor[Supervisor<br/>Main Orchestrator]
+        ContinuousServer[ContinuousServer<br/>Long-Running Mode]
+        WorkflowExecutor[WorkflowExecutor<br/>Multi-Step Pipelines]
+    end
+
+    subgraph "Concurrency Layer"
+        WorkQueue[WorkQueue<br/>Thread-Safe Queue]
+        ResultAggregator[ResultAggregator<br/>Thread-Safe Results]
+        CallbackRegistry[CallbackRegistry<br/>Event Callbacks]
+        WrappedRactor[WrappedRactor<br/>Ractor Wrapper]
+        WorkDistributionManager[WorkDistributionManager<br/>Idle Worker Tracking]
+    end
+
+    subgraph "Ractor Layer"
+        Ractor1[Ractor 1]
+        Ractor2[Ractor 2]
+        Ractor3[Ractor 3]
+    end
+
+    Work --> Supervisor
+    Worker --> WorkflowExecutor
+    WorkResult --> ResultAggregator
+
+    Supervisor --> WorkQueue
+    Supervisor --> ResultAggregator
+    Supervisor --> CallbackRegistry
+    Supervisor --> WorkDistributionManager
+
+    ContinuousServer --> Supervisor
+
+    WorkflowExecutor --> Supervisor
+    WorkflowExecutor --> WorkQueue
+
+    WorkDistributionManager --> WrappedRactor
+    WrappedRactor --> Ractor1
+    WrappedRactor --> Ractor2
+    WrappedRactor --> Ractor3
+
+    Ractor1 --> Worker
+    Ractor2 --> Worker
+    Ractor3 --> Worker
+
+    style Work fill:#e1f5e1
+    style Worker fill:#e1f5e1
+    style WorkResult fill:#e1f5e1
+    style Supervisor fill:#e3f2fd
+    style ContinuousServer fill:#e3f2fd
+    style WorkflowExecutor fill:#e3f2fd
+    style WrappedRactor fill:#fff3e0
+    style Ractor1 fill:#fce4ec
+    style Ractor2 fill:#fce4ec
+    style Ractor3 fill:#fce4ec
+```
+
+## Component Relationships
+
+```mermaid
+graph LR
+    subgraph "User Code"
+        MyWork[MyWork < Work]
+        MyWorker[MyWorker < Worker]
+    end
+
+    subgraph "Fractor Core"
+        Supervisor[Supervisor]
+        Queue[WorkQueue]
+        Results[ResultAggregator]
+    end
+
+    subgraph "Worker Pool"
+        W1[Worker Ractor 1]
+        W2[Worker Ractor 2]
+        W3[Worker Ractor 3]
+    end
+
+    MyWork --> Supervisor
+    MyWorker --> Supervisor
+
+    Supervisor --> Queue
+    Queue --> W1
+    Queue --> W2
+    Queue --> W3
+
+    W1 --> Results
+    W2 --> Results
+    W3 --> Results
+
+    Results --> Supervisor
+    Supervisor --> MyWork
+```
+
+## Pipeline Mode Execution Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Supervisor
+    participant WorkQueue
+    participant Worker as Worker Ractor
+    participant Results
+    participant Callback as CallbackRegistry
+
+    User->>Supervisor: new(worker_pools: [...])
+    User->>Supervisor: add_work_items(items)
+    Supervisor->>WorkQueue: enqueue items
+    User->>Supervisor: run()
+
+    loop Main Loop
+        Supervisor->>WorkQueue: pop_batch()
+        WorkQueue-->>Supervisor: work items
+
+        Supervisor->>Worker: send work
+        Worker->>Worker: process(work)
+        Worker-->>Supervisor: WorkResult
+        Supervisor->>Results: add(result)
+
+        Supervisor->>Callback: process_work_callbacks()
+        Callback-->>Supervisor: new_work (optional)
+    end
+
+    Supervisor-->>User: results
+```
+
+## Continuous Mode Execution Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Server as ContinuousServer
+    participant Supervisor
+    participant Queue as WorkQueue
+    participant Callbacks as CallbackRegistry
+
+    User->>Server: new(worker_pools, work_queue)
+    Server->>Supervisor: new(continuous_mode: true)
+    Queue->>Supervisor: register_work_source()
+    Server->>Server: run()
+
+    loop Continuous Processing
+        Supervisor->>Callbacks: process_work_callbacks()
+        Callbacks-->>Supervisor: new work items
+        Supervisor->>Queue: enqueue new work
+        Note over Supervisor,Queue: Distribute to workers
+
+        Server->>Server: on_result callback
+        Server->>Server: on_error callback
+    end
+
+    User->>Server: stop() / Ctrl+C
+    Server->>Supervisor: stop()
+    Server-->>User: shutdown complete
+```
+
+## Workflow System Architecture
+
+```mermaid
+graph TB
+    subgraph "Workflow Definition"
+        DSL[Workflow DSL]
+        Builder[Workflow Builder]
+        Job[Job Definitions]
+    end
+
+    subgraph "Workflow Execution"
+        Executor[WorkflowExecutor]
+        Resolver[DependencyResolver<br/>Topological Sort]
+        Logger[WorkflowExecutionLogger]
+    end
+
+    subgraph "Execution Components"
+        JobExecutor[JobExecutor]
+        Retry[RetryOrchestrator]
+        Circuit[CircuitBreakerOrchestrator]
+        Fallback[FallbackJobHandler]
+        DLQ[DeadLetterQueue]
+    end
+
+    DSL --> Builder
+    Builder --> Job
+    Job --> Executor
+
+    Executor --> Resolver
+    Executor --> Logger
+    Executor --> JobExecutor
+
+    JobExecutor --> Retry
+    JobExecutor --> Circuit
+    JobExecutor --> Fallback
+    JobExecutor --> DLQ
+```
+
+## Ruby Version-Specific Architecture
+
+```mermaid
+graph LR
+    subgraph "Ruby 3.x"
+        R3Handler[MainLoopHandler]
+        R3Wrapped[WrappedRactor]
+        R3Method[Ractor.yield / Ractor.receive]
+    end
+
+    subgraph "Ruby 4.0+"
+        R4Handler[MainLoopHandler4]
+        R4Wrapped[WrappedRactor4]
+        R4Method[Ractor::Port / Ractor.select]
+    end
+
+    subgraph "Shared"
+        Supervisor[Supervisor]
+        Common[Common Components]
+    end
+
+    Supervisor --> R3Handler
+    Supervisor --> R4Handler
+
+    R3Handler --> R3Wrapped
+    R3Wrapped --> R3Method
+
+    R4Handler --> R4Wrapped
+    R4Wrapped --> R4Method
+
+    R3Handler --> Common
+    R4Handler --> Common
+```
+
+## Component Responsibilities
+
+### Application Layer
+
+| Component | Responsibility |
+|-----------|---------------|
+| **Work** | Immutable data container with input data |
+| **Worker** | Processing logic with `process(work)` method |
+| **WorkResult** | Contains success/failure status, result value, or error |
+
+### Orchestration Layer
+
+| Component | Responsibility |
+|-----------|---------------|
+| **Supervisor** | Main orchestrator for pipeline mode, manages worker lifecycle |
+| **ContinuousServer** | High-level wrapper for long-running services |
+| **WorkflowExecutor** | Orchestrates multi-step workflow executions |
+
+### Concurrency Layer
+
+| Component | Responsibility |
+|-----------|---------------|
+| **WorkQueue** | Thread-safe queue for work items |
+| **ResultAggregator** | Thread-safe result collection with event notifications |
+| **CallbackRegistry** | Manages work source and error callbacks |
+| **WrappedRactor** | Safe wrapper around Ruby Ractor with version-specific implementations |
+| **WorkDistributionManager** | Tracks idle workers and distributes work efficiently |
+
+### Ractor Layer
+
+| Component | Responsibility |
+|-----------|---------------|
+| **Ractor 1, 2, 3...** | Isolated Ruby Ractors containing Worker instances |
+| **Worker instances** | Each Ractor has its own Worker instance for processing |
+
+## Data Flow
+
+### Work Processing Flow
+
+```mermaid
+graph LR
+    A[User creates Work] --> B[Supervisor.add_work_item]
+    B --> C[WorkQueue]
+    C --> D[WorkDistributionManager]
+    D --> E[Idle Worker Ractor]
+    E --> F[Worker.process]
+    F --> G[WorkResult]
+    G --> H[ResultAggregator]
+    H --> I[User retrieves results]
+```
+
+### Error Handling Flow
+
+```mermaid
+graph LR
+    A[Worker.process raises error] --> B[WorkResult with error]
+    B --> C[ErrorReporter]
+    C --> D[ErrorStatistics]
+    C --> E[ErrorCallbacks]
+    E --> F[User error handler]
+    D --> G[ErrorReportGenerator]
+    G --> H[Formatted error output]
+```
+
+## Key Design Principles
+
+1. **Function-Driven**: Work is defined as input → processing → output
+2. **Message Passing**: Ractors communicate via messages, no shared state
+3. **Immutability**: Work objects are immutable, ensuring thread safety
+4. **Isolation**: Each Worker runs in its own Ractor with isolated memory
+5. **Scalability**: Automatically distribute work across available workers
+6. **Fault Tolerance**: Errors are captured without crashing other workers
+7. **Version Compatibility**: Separate implementations for Ruby 3.x and 4.0+

data/docs/PERFORMANCE_TUNING.md

@@ -0,0 +1,355 @@
+# Performance Tuning Guide
+
+This guide helps you optimize Fractor for your specific use case.
+
+## Table of Contents
+
+- [Worker Pool Configuration](#worker-pool-configuration)
+- [Work Item Design](#work-item-design)
+- [Batch Size Tuning](#batch-size-tuning)
+- [Memory Management](#memory-management)
+- [Workflow Optimization](#workflow-optimization)
+- [Monitoring and Profiling](#monitoring-and-profiling)
+- [Common Performance Issues](#common-performance-issues)
+
+## Worker Pool Configuration
+
+### Determining Optimal Worker Count
+
+The number of workers depends on your workload characteristics:
+
+```ruby
+# CPU-bound tasks: Use number of processors
+num_workers: Etc.nprocessors
+
+# I/O-bound tasks: Use 2-4x processors
+num_workers: Etc.nprocessors * 2
+
+# Mixed workload: Start with processors, tune from there
+num_workers: Etc.nprocessors
+```
+
+**Guidelines:**
+- **CPU-bound** (data processing, computation): Use `Etc.nprocessors`
+- **I/O-bound** (HTTP requests, database queries): Use `2-4 * Etc.nprocessors`
+- **Mixed workload**: Start with `Etc.nprocessors`, monitor, and adjust
+
+### Multiple Worker Pools
+
+Use different worker pools for different task types:
+
+```ruby
+Fractor::Supervisor.new(
+  worker_pools: [
+    # Fast CPU-bound tasks - more workers
+    { worker_class: FastProcessor, num_workers: 8 },
+    # Slow I/O-bound tasks - fewer workers
+    { worker_class: SlowAPICaller, num_workers: 2 },
+  ]
+)
+```
+
+## Work Item Design
+
+### Keep Work Items Small
+
+**Optimal**: Small, independent work items
+
+```ruby
+# Good: Many small items
+1000.times do |i|
+  queue << ProcessDataWork.new(data[i])
+end
+```
+
+**Suboptimal**: Large, monolithic work items
+
+```ruby
+# Less efficient: One large item
+queue << ProcessAllDataWork.new(all_data)
+```
+
+### Avoid Shared State
+
+Work items should be self-contained:
+
+```ruby
+# Good: Self-contained work
+class ProcessUserWork < Fractor::Work
+  def initialize(user_id)
+    super({ user_id: user_id })
+  end
+end
+
+# Bad: Work that depends on external state
+class ProcessUserWork < Fractor::Work
+  def initialize(user_id)
+    super({ user_id: user_id, cache: $shared_cache }) # Avoid!
+  end
+end
+```
+
+### Use Result Caching for Expensive Operations
+
+```ruby
+cache = Fractor::ResultCache.new(ttl: 300) # 5 minute TTL
+
+# Cached expensive operation
+result = cache.get(expensive_work) do
+  # Only executes if not cached
+  expensive_work.process
+end
+```
+
+## Batch Size Tuning
+
+### WorkQueue Batch Size
+
+When using `WorkQueue`, the default batch size is 10. Adjust based on:
+
+```ruby
+# For many small, quick tasks: larger batch
+queue.register_with_supervisor(supervisor, batch_size: 50)
+
+# For fewer, slower tasks: smaller batch
+queue.register_with_supervisor(supervisor, batch_size: 5)
+```
+
+### Worker Processing Batch Size
+
+Workers can process multiple items per message:
+
+```ruby
+class BatchWorker < Fractor::Worker
+  def process(work)
+    # Process single item
+  end
+end
+```
+
+## Memory Management
+
+### Result Aggregator Memory
+
+For large result sets, consider processing incrementally:
+
+```ruby
+# Instead of collecting all results:
+supervisor.run
+all_results = supervisor.results.results # May use lots of memory
+
+# Use on_complete callbacks:
+supervisor.results.on_new_result do |result|
+  # Process each result as it arrives
+  save_to_database(result)
+end
+supervisor.run
+```
+
+### Result Cache Memory Limits
+
+Configure cache limits for memory-constrained environments:
+
+```ruby
+# Limit by entry count
+cache = Fractor::ResultCache.new(max_size: 1000)
+
+# Limit by memory (approximate)
+cache = Fractor::ResultCache.new(max_memory: 100_000_000) # 100MB
+
+# Both limits
+cache = Fractor::ResultCache.new(
+  max_size: 1000,
+  max_memory: 100_000_000
+)
+```
+
+### Queue Memory Limits
+
+For very large work sets, use persistent queue:
+
+```ruby
+# Use file-based queue for large datasets
+queue = Fractor::PersistentWorkQueue.new(
+  queue_file: "/tmp/work_queue.db"
+)
+```
+
+## Workflow Optimization
+
+### Enable Execution Order Caching
+
+For repeated workflow executions:
+
+```ruby
+class MyWorkflow < Fractor::Workflow
+  # Enable caching for repeated executions
+  enable_cache
+end
+```
+
+### Optimize Job Dependencies
+
+Minimize dependencies for better parallelism:
+
+```ruby
+Fractor::Workflow.define("optimized") do
+  job "fetch_data" do
+    runs FetchWorker
+  end
+
+  # These can run in parallel (both depend only on fetch_data)
+  job "process_a" do
+    runs ProcessAWorker
+    needs "fetch_data"
+  end
+
+  job "process_b" do
+    runs ProcessBWorker
+    needs "fetch_data"
+  end
+
+  # This depends on both, so runs after them
+  job "combine" do
+    runs CombineWorker
+    needs ["process_a", "process_b"]
+  end
+end
+```
+
+### Use Circuit Breakers for Failing Services
+
+```ruby
+Fractor::Workflow.define("resilient") do
+  job "external_api" do
+    runs ExternalAPIWorker
+
+    # Circuit breaker prevents cascading failures
+    circuit_breaker threshold: 5, timeout: 60
+  end
+end
+```
+
+## Monitoring and Profiling
+
+### Enable Performance Monitoring
+
+```ruby
+supervisor = Fractor::Supervisor.new(
+  worker_pools: [{ worker_class: MyWorker }],
+  enable_performance_monitoring: true
+)
+
+supervisor.run
+
+# Get performance metrics
+metrics = supervisor.performance_metrics
+puts "Latency: #{metrics.avg_latency}ms"
+puts "Throughput: #{metrics.throughput} items/sec"
+```
+
+### Monitor Cache Performance
+
+```ruby
+cache = Fractor::ResultCache.new
+
+# Run workload
+# ...
+
+stats = cache.stats
+puts "Hit rate: #{stats[:hit_rate]}%"
+puts "Cache size: #{stats[:size]}"
+```
+
+### Use Debug Output
+
+```ruby
+supervisor = Fractor::Supervisor.new(
+  worker_pools: [{ worker_class: MyWorker }],
+  debug: true # Enable verbose output
+)
+```
+
+## Common Performance Issues
+
+### Issue: Workers Idle but Work in Queue
+
+**Symptom**: `workers_status` shows idle workers but work isn't being distributed.
+
+**Solution**: Check that `work_distribution_manager` is properly initialized:
+
+```ruby
+# This is handled automatically by Supervisor
+# If using custom setup, ensure:
+@work_distribution_manager = WorkDistributionManager.new(...)
+```
+
+### Issue: High Memory Usage
+
+**Symptom**: Memory grows continuously during execution.
+
+**Solutions**:
+1. Process results incrementally with `on_new_result` callbacks
+2. Configure cache limits with `max_size` and `max_memory`
+3. Use persistent queue for large datasets
+
+### Issue: Slow Workflow Execution
+
+**Symptom**: Workflow takes longer than expected.
+
+**Solutions**:
+1. Enable execution order caching
+2. Optimize job dependencies for parallelism
+3. Use `parallel_map` for independent transformations
+
+### Issue: Uneven Worker Utilization
+
+**Symptom**: Some workers busy, others idle.
+
+**Solution**: Use separate worker pools for different task types:
+
+```ruby
+# Instead of mixed workload in one pool:
+# { worker_class: MixedWorker, num_workers: 8 }
+
+# Use separate pools:
+worker_pools: [
+  { worker_class: FastWorker, num_workers: 6 },
+  { worker_class: SlowWorker, num_workers: 2 },
+]
+```
+
+## Performance Benchmarks
+
+### Typical Throughput (CPU-bound)
+
+| Workers | Throughput (items/sec) | Speedup |
+|---------|------------------------|---------|
+| 1       | 1,000                  | 1x      |
+| 2       | 1,900                  | 1.9x    |
+| 4       | 3,600                  | 3.6x    |
+| 8       | 6,800                  | 6.8x    |
+
+*Benchmarks on 8-core system, CPU-bound workload*
+
+### Typical Throughput (I/O-bound)
+
+| Workers | Throughput (requests/sec) | Speedup |
+|---------|---------------------------|---------|
+| 1       | 100                       | 1x      |
+| 2       | 190                       | 1.9x    |
+| 4       | 380                       | 3.8x    |
+| 8       | 750                       | 7.5x    |
+| 16      | 1,400                     | 14x     |
+
+*Benchmarks with HTTP API calls, 100ms latency*
+
+## Best Practices Summary
+
+1. **Start simple**: Use default settings, then optimize based on measurements
+2. **Measure first**: Enable performance monitoring before tuning
+3. **Profile**: Use debug output to understand bottlenecks
+4. **Batch appropriately**: Balance batch size for your workload
+5. **Cache wisely**: Use result caching for expensive, deterministic operations
+6. **Monitor memory**: Set limits on cache and queue sizes
+7. **Design for isolation**: Keep work items independent and self-contained