fractor 0.1.4 → 0.1.7

data/examples/scatter_gather/scatter_gather.rb

@@ -42,7 +42,7 @@ module ScatterGather
                  error = ArgumentError.new("Unknown source: #{work.source}")
                  return Fractor::WorkResult.new(
                    error: error,
-                   work: work
+                   work: work,
                  )
                end
 
@@ -53,9 +53,9 @@ module ScatterGather
           query: work.query,
           hits: result[:hits],
           metadata: result[:metadata],
-          timing: result[:timing]
+          timing: result[:timing],
         },
-        work: work
+        work: work,
       )
     end
 
@@ -72,12 +72,12 @@ module ScatterGather
 
       # Generate simulated records
       record_count = rand(3..10)
-      hits = record_count.times.map do |i|
+      hits = Array.new(record_count) do |i|
         {
           id: "db-#{i + 1}",
           title: "Database Result #{i + 1} for '#{work.query}'",
           content: "This is database content for #{work.query}",
-          relevance: rand(0.1..1.0).round(2)
+          relevance: rand(0.1..1.0).round(2),
         }
       end
 
@@ -86,9 +86,9 @@ module ScatterGather
         metadata: {
           source_type: "PostgreSQL Database",
           total_available: record_count + rand(10..50),
-          query_type: "Full-text search"
+          query_type: "Full-text search",
         },
-        timing: rand(0.01..0.3).round(3)
+        timing: rand(0.01..0.3).round(3),
       }
     end
 
@@ -98,12 +98,12 @@ module ScatterGather
 
       # Generate simulated API results
       record_count = rand(2..8)
-      hits = record_count.times.map do |i|
+      hits = Array.new(record_count) do |i|
         {
           id: "api-#{i + 1}",
           title: "API Result #{i + 1} for '#{work.query}'",
           content: "This is API content for #{work.query}",
-          relevance: rand(0.1..1.0).round(2)
+          relevance: rand(0.1..1.0).round(2),
         }
       end
 
@@ -112,9 +112,9 @@ module ScatterGather
         metadata: {
           source_type: "External REST API",
           provider: %w[Google Bing DuckDuckGo].sample,
-          response_code: 200
+          response_code: 200,
         },
-        timing: rand(0.1..0.5).round(3)
+        timing: rand(0.1..0.5).round(3),
       }
     end
 
@@ -128,12 +128,12 @@ module ScatterGather
       if cache_hit
         # Cache hit - return cached results
         record_count = rand(1..5)
-        hits = record_count.times.map do |i|
+        hits = Array.new(record_count) do |i|
           {
             id: "cache-#{i + 1}",
             title: "Cached Result #{i + 1} for '#{work.query}'",
             content: "This is cached content for #{work.query}",
-            relevance: rand(0.1..1.0).round(2)
+            relevance: rand(0.1..1.0).round(2),
           }
         end
 
@@ -142,9 +142,9 @@ module ScatterGather
           metadata: {
             source_type: "In-memory Cache",
             cache_hit: true,
-            age: rand(1..3600)
+            age: rand(1..3600),
           },
-          timing: rand(0.001..0.05).round(3)
+          timing: rand(0.001..0.05).round(3),
         }
       else
         # Cache miss
@@ -152,9 +152,9 @@ module ScatterGather
           hits: [],
           metadata: {
             source_type: "In-memory Cache",
-            cache_hit: false
+            cache_hit: false,
           },
-          timing: rand(0.001..0.01).round(3)
+          timing: rand(0.001..0.01).round(3),
         }
       end
     end
@@ -165,13 +165,13 @@ module ScatterGather
 
       # Generate simulated file results
       record_count = rand(1..12)
-      hits = record_count.times.map do |i|
+      hits = Array.new(record_count) do |i|
         {
           id: "file-#{i + 1}",
           title: "File Result #{i + 1} for '#{work.query}'",
           path: "/path/to/file_#{i + 1}.txt",
           content: "This is file content matching #{work.query}",
-          relevance: rand(0.1..1.0).round(2)
+          relevance: rand(0.1..1.0).round(2),
         }
       end
 
@@ -180,9 +180,9 @@ module ScatterGather
         metadata: {
           source_type: "File System",
           directories_searched: rand(5..20),
-          files_scanned: rand(50..500)
+          files_scanned: rand(50..500),
         },
-        timing: rand(0.01..0.2).round(3)
+        timing: rand(0.01..0.2).round(3),
       }
     end
   end
@@ -194,8 +194,8 @@ module ScatterGather
     def initialize(worker_count = 4)
       @supervisor = Fractor::Supervisor.new(
         worker_pools: [
-          { worker_class: SearchWorker, num_workers: worker_count }
-        ]
+          { worker_class: SearchWorker, num_workers: worker_count },
+        ],
       )
 
       @merged_results = nil
@@ -204,10 +204,11 @@ module ScatterGather
     def search(query, sources = nil)
       # Define search sources with their parameters
       sources ||= [
-        { source: :database, params: { max_results: 50, include_archived: false } },
+        { source: :database,
+          params: { max_results: 50, include_archived: false } },
         { source: :api, params: { format: "json", timeout: 5 } },
         { source: :cache, params: { max_age: 3600 } },
-        { source: :filesystem, params: { extensions: %w[txt md pdf] } }
+        { source: :filesystem, params: { extensions: %w[txt md pdf] } },
       ]
 
       start_time = Time.now
@@ -262,7 +263,7 @@ module ScatterGather
             content: hit[:content],
             source: source,
             original_relevance: hit[:relevance],
-            weighted_relevance: hit[:relevance] * source_weight
+            weighted_relevance: hit[:relevance] * source_weight,
           }
         end
       end
@@ -277,7 +278,7 @@ module ScatterGather
         execution_time: total_time,
         sources: results_by_source.keys,
         ranked_results: ranked_hits,
-        source_details: results_by_source
+        source_details: results_by_source,
       }
     end
   end
@@ -309,7 +310,7 @@ if __FILE__ == $PROGRAM_NAME
   puts "Query: #{results[:query]}"
   puts "Total hits: #{results[:total_hits]}"
   puts "Total execution time: #{results[:execution_time].round(3)} seconds"
-  puts "Sources searched: #{results[:sources].join(", ")}"
+  puts "Sources searched: #{results[:sources].join(', ')}"
   puts
 
   puts "Top 5 Results (by relevance):"

data/examples/simple/README.adoc

@@ -0,0 +1,347 @@
+= Simple Example - Getting Started with Fractor
+
+== Purpose
+
+Provides the most basic introduction to Fractor, demonstrating fundamental concepts with minimal complexity to help new users get started quickly.
+
+== Focus
+
+This example focuses on the essential building blocks:
+
+* Creating custom `Work` classes to encapsulate work items
+* Creating custom `Worker` classes to process work
+* Setting up a `Supervisor` to manage parallel processing
+* Adding work items and running the supervisor
+* Processing results and handling errors
+* Auto-detection of available processors
+
+== Architecture
+
+.Basic Fractor Architecture
+[source]
+----
+Main Program
+    │
+    ├─→ Create Work Items (MyWork)
+    │       │
+    │       └─→ MyWork { value: 1 }
+    │           MyWork { value: 2 }
+    │           ...
+    │           MyWork { value: 10 }
+    │
+    ├─→ Create Supervisor
+    │       │
+    │       └─→ Worker Pool Configuration
+    │               │
+    │               └─→ MyWorker (auto-detect CPU count)
+    │
+    ├─→ Add Work Items
+    │       │
+    │       └─→ supervisor.add_work_items(work_items)
+    │
+    ├─→ Run Supervisor
+    │       │
+    │       └─→ Parallel Processing
+    │               │
+    │               ├─→ Ractor 1 (MyWorker) ─→ Process work
+    │               ├─→ Ractor 2 (MyWorker) ─→ Process work
+    │               ├─→ Ractor 3 (MyWorker) ─→ Process work
+    │               └─→ Ractor N (MyWorker) ─→ Process work
+    │                       │
+    │                       └─→ Results Aggregator
+    │                               │
+    │                               ├─→ Successful Results
+    │                               └─→ Error Results
+    │
+    └─→ Display Results
+            │
+            ├─→ supervisor.results (all results)
+            └─→ supervisor.results.errors (failed items)
+----
+
+.Data Flow
+[source]
+----
+Work Items                Worker Processing              Results
+──────────────────────────────────────────────────────────────────
+
+MyWork(1)  ─┐
+MyWork(2)  ─┤
+MyWork(3)  ─┤
+MyWork(4)  ─┼─→ Work Queue ─→ Ractor Pool ─→ WorkResult(2)
+MyWork(5)  ─┤    (Supervisor)   (Workers)     WorkResult(4)
+MyWork(6)  ─┤                                  WorkResult(6)
+MyWork(7)  ─┤                                  WorkResult(8)
+MyWork(8)  ─┤                                  ...
+MyWork(9)  ─┤                                  WorkError(5)
+MyWork(10) ─┘                                  WorkResult(20)
+----
+
+== Key Components
+
+=== Work Class
+
+The `Work` class encapsulates input data for processing:
+
+[source,ruby]
+----
+class MyWork < Fractor::Work
+  def initialize(value)
+    super({ value: value })  # <1>
+  end
+
+  def value
+    input[:value]  # <2>
+  end
+
+  def to_s
+    "MyWork: #{value}"  # <3>
+  end
+end
+----
+<1> Store data in input hash using `super`
+<2> Access stored data via `input` hash
+<3> Provide string representation for debugging
+
+Key points:
+
+* Inherit from `Fractor::Work`
+* Store all data in the `input` hash
+* Provide accessor methods for convenience
+* Include `to_s` method for debugging
+
+=== Worker Class
+
+The `Worker` class processes work items:
+
+[source,ruby]
+----
+class MyWorker < Fractor::Worker
+  def process(work)  # <1>
+    # Check work type
+    if work.is_a?(MyWork)
+      # Handle known error case
+      if work.value == 5
+        error = StandardError.new('Cannot process value 5')
+        return Fractor::WorkResult.new(error: error, work: work)  # <2>
+      end
+
+      # Process successfully
+      calculated = work.value * 2
+      Fractor::WorkResult.new(result: calculated, work: work)  # <3>
+
+    else
+      # Handle unexpected work type
+      error = TypeError.new("Unsupported work type: #{work.class}")
+      Fractor::WorkResult.new(error: error, work: work)
+    end
+  end
+end
+----
+<1> Implement `process(work)` method - called by Ractor
+<2> Return `WorkResult` with error for failures
+<3> Return `WorkResult` with result for success
+
+Key points:
+
+* Inherit from `Fractor::Worker`
+* Implement `process(work)` method
+* Return `Fractor::WorkResult` objects
+* Handle errors gracefully (return error results, don't raise)
+* Support multiple work types if needed
+
+=== Supervisor Setup
+
+The `Supervisor` manages worker Ractors and distributes work:
+
+[source,ruby]
+----
+# Create supervisor with worker pool
+supervisor = Fractor::Supervisor.new(
+  worker_pools: [
+    { worker_class: MyWorker }  # <1>
+  ]
+)
+
+# Create and add work items
+work_items = (1..10).map { |i| MyWork.new(i) }  # <2>
+supervisor.add_work_items(work_items)  # <3>
+
+# Run the supervisor
+supervisor.run  # <4>
+
+# Access results
+supervisor.results  # <5>
+supervisor.results.errors  # <6>
+----
+<1> Define worker pool (auto-detects CPU count)
+<2> Create array of work items
+<3> Add work items to supervisor
+<4> Start processing (blocks until complete)
+<5> Access all results (successful and failed)
+<6> Access only failed results
+
+Key points:
+
+* Worker pools default to auto-detected CPU count
+* Can specify `num_workers` explicitly if needed
+* `run` blocks until all work is complete
+* Results are aggregated in `supervisor.results`
+
+== Usage
+
+Run the example from the project root:
+
+[source,shell]
+----
+ruby examples/simple/sample.rb
+
+# With debug output
+FRACTOR_DEBUG=1 ruby examples/simple/sample.rb
+----
+
+== Expected Output
+
+[example]
+====
+[source]
+----
+Processing complete.
+Final Aggregated Results:
+#<Fractor::ResultAggregator:0x... @results=[
+  #<Fractor::WorkResult @result=2, @work=#<MyWork: 1>>,
+  #<Fractor::WorkResult @result=4, @work=#<MyWork: 2>>,
+  #<Fractor::WorkResult @result=6, @work=#<MyWork: 3>>,
+  #<Fractor::WorkResult @result=8, @work=#<MyWork: 4>>,
+  #<Fractor::WorkResult @result=12, @work=#<MyWork: 6>>,
+  #<Fractor::WorkResult @result=14, @work=#<MyWork: 7>>,
+  #<Fractor::WorkResult @result=16, @work=#<MyWork: 8>>,
+  #<Fractor::WorkResult @result=18, @work=#<MyWork: 9>>,
+  #<Fractor::WorkResult @result=20, @work=#<MyWork: 10>>
+], @errors=[...]>
+
+Failed Work Items (1):
+Work: MyWork: 5
+Error: StandardError: Cannot process value 5
+----
+====
+
+== Learning Points
+
+=== Parallel Processing
+
+* Fractor automatically distributes work across multiple Ractors
+* Number of Ractors defaults to available CPU cores
+* Work is processed in parallel, improving throughput
+* Order of completion is non-deterministic
+
+=== Work Encapsulation
+
+* Each work item is a separate object with its input data
+* Work items are isolated from each other
+* Workers process one work item at a time
+* Work items can be of different types (polymorphic)
+
+=== Error Handling
+
+* Errors don't stop the entire processing
+* Failed work items are tracked separately
+* Workers return error results, not exceptions
+* System continues processing remaining work
+
+=== Auto-Detection
+
+* When `num_workers` is not specified, Fractor auto-detects CPU count
+* Uses `Etc.nprocessors` to determine available cores
+* Optimal for CPU-bound tasks
+* Can be overridden if needed:
++
+[source,ruby]
+----
+supervisor = Fractor::Supervisor.new(
+  worker_pools: [
+    { worker_class: MyWorker, num_workers: 4 }
+  ]
+)
+----
+
+=== Result Aggregation
+
+* All results are collected in `supervisor.results`
+* Successful results accessible via `results.results`
+* Failed results accessible via `results.errors`
+* Each result contains both the output and original work item
+
+== Common Patterns
+
+=== Multiple Work Types
+
+Process different types of work with the same worker:
+
+[source,ruby]
+----
+class MyWorker < Fractor::Worker
+  def process(work)
+    if work.is_a?(MyWork)
+      # Process MyWork
+      Fractor::WorkResult.new(result: work.value * 2, work: work)
+    elsif work.is_a?(OtherWork)
+      # Process OtherWork differently
+      Fractor::WorkResult.new(result: "Processed: #{work.value}", work: work)
+    else
+      # Handle unknown types
+      error = TypeError.new("Unsupported work type: #{work.class}")
+      Fractor::WorkResult.new(error: error, work: work)
+    end
+  end
+end
+----
+
+=== Conditional Processing
+
+Make decisions based on work item data:
+
+[source,ruby]
+----
+def process(work)
+  if work.value < 0
+    error = ArgumentError.new('Value must be positive')
+    return Fractor::WorkResult.new(error: error, work: work)
+  end
+
+  if work.value > 100
+    # Heavy processing for large values
+    result = complex_calculation(work.value)
+  else
+    # Simple processing for small values
+    result = work.value * 2
+  end
+
+  Fractor::WorkResult.new(result: result, work: work)
+end
+----
+
+=== Debugging
+
+Use `ENV['FRACTOR_DEBUG']` to enable debug output:
+
+[source,ruby]
+----
+def process(work)
+  puts "Working on '#{work.inspect}'" if ENV['FRACTOR_DEBUG']
+
+  # Processing logic...
+
+  Fractor::WorkResult.new(result: result, work: work)
+end
+----
+
+== Next Steps
+
+After understanding the basics, explore more advanced examples:
+
+* link:../auto_detection/README.adoc[Auto Detection] - CPU auto-detection in detail
+* link:../multi_work_type/README.adoc[Multi Work Type] - Handling multiple work types
+* link:../specialized_workers/README.adoc[Specialized Workers] - Worker pools for different tasks
+* link:../pipeline_processing/README.adoc[Pipeline Processing] - Sequential processing stages
+* link:../workflow/README.adoc[Workflow System] - GitHub Actions-style workflows

data/examples/simple/sample.rb

@@ -32,7 +32,7 @@
 #
 # =============================================================================
 
-require_relative "../../lib/fractor"
+require_relative '../../lib/fractor'
 
 # Client-specific work item implementation inheriting from Fractor::Work
 class MyWork < Fractor::Work
@@ -72,14 +72,14 @@ class MyWorker < Fractor::Worker
   # It should return a Fractor::WorkResult object
   def process(work)
     # Only print debug information if FRACTOR_DEBUG is enabled
-    puts "Working on '#{work.inspect}'" if ENV["FRACTOR_DEBUG"]
+    puts "Working on '#{work.inspect}'" if ENV['FRACTOR_DEBUG']
 
     # Check work type and handle accordingly
     if work.is_a?(MyWork)
       if work.value == 5
         # Return a Fractor::WorkResult for errors
         # Store the error object, not just the string
-        error = StandardError.new("Cannot process value 5")
+        error = StandardError.new('Cannot process value 5')
         return Fractor::WorkResult.new(error: error, work: work)
       end
 
@@ -116,8 +116,8 @@ if __FILE__ == $PROGRAM_NAME
   # Run the supervisor to start processing work
   supervisor.run
 
-  puts "Processing complete."
-  puts "Final Aggregated Results:"
+  puts 'Processing complete.'
+  puts 'Final Aggregated Results:'
   # Access the results aggregator from the supervisor
   puts supervisor.results.inspect