fractor 0.1.3 → 0.1.6

data/examples/producer_subscriber/producer_subscriber.rb

@@ -8,7 +8,7 @@ module ProducerSubscriber
     def initialize(data, depth = 0)
       super({
         data: data,
-        depth: depth
+        depth: depth,
       })
     end
 
@@ -31,7 +31,7 @@ module ProducerSubscriber
       super({
         data: data,
         parent_id: parent_id,
-        depth: depth
+        depth: depth,
       })
     end
 
@@ -63,7 +63,7 @@ module ProducerSubscriber
       else
         Fractor::WorkResult.new(
           error: "Unknown work type: #{work.class}",
-          work: work
+          work: work,
         )
       end
     end
@@ -80,13 +80,13 @@ module ProducerSubscriber
       # Return the result with metadata about sub-works
       result = {
         processed_data: processed_data,
-        sub_works: [] # Will be populated by the supervisor
+        sub_works: [], # Will be populated by the supervisor
       }
 
       # Return a successful result
       Fractor::WorkResult.new(
         result: result,
-        work: work
+        work: work,
       )
     end
 
@@ -101,9 +101,9 @@ module ProducerSubscriber
       Fractor::WorkResult.new(
         result: {
           processed_data: processed_data,
-          parent_id: work.parent_id
+          parent_id: work.parent_id,
         },
-        work: work
+        work: work,
       )
     end
   end
@@ -122,8 +122,8 @@ module ProducerSubscriber
       # Create the supervisor
       supervisor = Fractor::Supervisor.new(
         worker_pools: [
-          { worker_class: MultiWorker, num_workers: @worker_count }
-        ]
+          { worker_class: MultiWorker, num_workers: @worker_count },
+        ],
       )
 
       # Create and add initial work items
@@ -144,12 +144,14 @@ module ProducerSubscriber
         # Create a new supervisor for sub-works
         sub_supervisor = Fractor::Supervisor.new(
           worker_pools: [
-            { worker_class: MultiWorker, num_workers: @worker_count }
-          ]
+            { worker_class: MultiWorker, num_workers: @worker_count },
+          ],
         )
 
         # Create and add the sub-work items
-        sub_work_items = sub_works.map { |sw| SubWork.new(sw[:data], sw[:parent_id], sw[:depth]) }
+        sub_work_items = sub_works.map do |sw|
+          SubWork.new(sw[:data], sw[:parent_id], sw[:depth])
+        end
         sub_supervisor.add_work_items(sub_work_items)
         sub_supervisor.run
 
@@ -179,12 +181,14 @@ module ProducerSubscriber
           sub_works << {
             data: sub_data,
             parent_id: work.object_id,
-            depth: work.depth + 1
+            depth: work.depth + 1,
           }
         end
 
         # Store the sub-work IDs in the result for reference
-        result.result[:sub_works] = sub_works.last(3).map { |sw| sw[:parent_id] }
+        result.result[:sub_works] = sub_works.last(3).map do |sw|
+          sw[:parent_id]
+        end
       end
 
       sub_works
@@ -195,7 +199,7 @@ module ProducerSubscriber
       initial_results.results.each do |result|
         @result_tree[result.work.object_id] = {
           data: result.result[:processed_data],
-          children: []
+          children: [],
         }
       end
 
@@ -236,7 +240,7 @@ if __FILE__ == $PROGRAM_NAME
   documents = [
     "Annual Report 2025",
     "Technical Documentation",
-    "Research Paper"
+    "Research Paper",
   ]
 
   worker_count = 4

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/sample.rb

@@ -1,7 +1,38 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require_relative "fractor"
+# =============================================================================
+# Simple Example - Getting Started with Fractor
+# =============================================================================
+#
+# This example demonstrates the basic usage of the Fractor framework.
+#
+# WHAT THIS DEMONSTRATES:
+# - How to create a Work class (MyWork) to encapsulate work items
+# - How to create a Worker class (MyWorker) to process work
+# - How to set up a Supervisor to manage parallel processing
+# - Basic error handling in workers
+# - How to access and display results after processing
+# - Auto-detection of available processors (num_workers not specified)
+#
+# KEY CONCEPTS:
+# 1. Work Class: Inherits from Fractor::Work, stores input data
+# 2. Worker Class: Inherits from Fractor::Worker, implements process() method
+# 3. Supervisor: Manages worker Ractors and distributes work
+# 4. WorkResult: Contains either successful results or errors
+#
+# HOW TO RUN:
+#   ruby examples/simple/sample.rb
+#
+# WHAT TO EXPECT:
+# - Creates work items with values 1-10
+# - Processes them in parallel using auto-detected number of workers
+# - Value 5 intentionally produces an error for demonstration
+# - Displays successful results and error information
+#
+# =============================================================================
+
+require_relative '../../lib/fractor'
 
 # Client-specific work item implementation inheriting from Fractor::Work
 class MyWork < Fractor::Work
@@ -41,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
 
@@ -71,9 +102,10 @@ end
 # MyWorker and MyWork classes.
 if __FILE__ == $PROGRAM_NAME
   # Create supervisor, passing the client-specific worker class in a worker pool
+  # Note: num_workers is not specified, so it will auto-detect the number of available processors
   supervisor = Fractor::Supervisor.new(
     worker_pools: [
-      { worker_class: MyWorker, num_workers: 2 } # Specify the worker class and number of worker Ractors
+      { worker_class: MyWorker } # Worker class without explicit num_workers uses auto-detection
     ]
   )
 
@@ -84,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
 

data/examples/specialized_workers/specialized_workers.rb

@@ -9,7 +9,7 @@ module SpecializedWorkers
       super({
         data: data,
         operation: operation,
-        parameters: parameters
+        parameters: parameters,
       })
     end
 
@@ -32,12 +32,13 @@ module SpecializedWorkers
 
   # Second work type: Database operations
   class DatabaseWork < Fractor::Work
-    def initialize(data = "", query_type = :select, table = "unknown", conditions = {})
+    def initialize(data = "", query_type = :select, table = "unknown",
+conditions = {})
       super({
         data: data,
         query_type: query_type,
         table: table,
-        conditions: conditions
+        conditions: conditions,
       })
     end
 
@@ -74,14 +75,16 @@ module SpecializedWorkers
       unless work.is_a?(ComputeWork)
         return Fractor::WorkResult.new(
           error: "ComputeWorker can only process ComputeWork, got: #{work.class}",
-          work: work
+          work: work,
         )
       end
 
       # Process based on the requested operation
       result = case work.operation
-               when :matrix_multiply then matrix_multiply(work.data, work.parameters)
-               when :image_transform then image_transform(work.data, work.parameters)
+               when :matrix_multiply then matrix_multiply(work.data,
+                                                          work.parameters)
+               when :image_transform then image_transform(work.data,
+                                                          work.parameters)
                when :path_finding then path_finding(work.data, work.parameters)
                else default_computation(work.data, work.parameters)
                end
@@ -90,9 +93,9 @@ module SpecializedWorkers
         result: {
           operation: work.operation,
           computation_result: result,
-          resources_used: @compute_resources
+          resources_used: @compute_resources,
         },
-        work: work
+        work: work,
       )
     end
 
@@ -110,7 +113,7 @@ module SpecializedWorkers
       # Simulate image transformation
       sleep(rand(0.1..0.3))
       transforms = params[:transforms] || %i[rotate scale]
-      "Image transformation applied: #{transforms.join(", ")} with parameters #{params}"
+      "Image transformation applied: #{transforms.join(', ')} with parameters #{params}"
     end
 
     def path_finding(_data, params)
@@ -140,7 +143,7 @@ module SpecializedWorkers
       unless work.is_a?(DatabaseWork)
         return Fractor::WorkResult.new(
           error: "DatabaseWorker can only process DatabaseWork, got: #{work.class}",
-          work: work
+          work: work,
         )
       end
 
@@ -148,7 +151,8 @@ module SpecializedWorkers
       result = case work.query_type
                when :select then perform_select(work.table, work.conditions)
                when :insert then perform_insert(work.table, work.data)
-               when :update then perform_update(work.table, work.data, work.conditions)
+               when :update then perform_update(work.table, work.data,
+                                                work.conditions)
                when :delete then perform_delete(work.table, work.conditions)
                else default_query(work.query_type, work.table, work.conditions)
                end
@@ -159,9 +163,9 @@ module SpecializedWorkers
           table: work.table,
           rows_affected: result[:rows_affected],
           data: result[:data],
-          execution_time: result[:time]
+          execution_time: result[:time],
         },
-        work: work
+        work: work,
       )
     end
 
@@ -174,8 +178,10 @@ module SpecializedWorkers
       record_count = rand(0..20)
       {
         rows_affected: record_count,
-        data: record_count.times.map { |i| { id: i + 1, name: "Record #{i + 1}" } },
-        time: rand(0.01..0.05)
+        data: Array.new(record_count) do |i|
+          { id: i + 1, name: "Record #{i + 1}" }
+        end,
+        time: rand(0.01..0.05),
       }
     end
 
@@ -185,7 +191,7 @@ module SpecializedWorkers
       {
         rows_affected: 1,
         data: { id: rand(1000..9999) },
-        time: rand(0.01..0.03)
+        time: rand(0.01..0.03),
       }
     end
 
@@ -196,7 +202,7 @@ module SpecializedWorkers
       {
         rows_affected: affected,
         data: nil,
-        time: rand(0.01..0.05)
+        time: rand(0.01..0.05),
       }
     end
 
@@ -207,7 +213,7 @@ module SpecializedWorkers
       {
         rows_affected: affected,
         data: nil,
-        time: rand(0.01..0.03)
+        time: rand(0.01..0.03),
       }
     end
 
@@ -217,7 +223,7 @@ module SpecializedWorkers
       {
         rows_affected: 0,
         data: nil,
-        time: rand(0.005..0.01)
+        time: rand(0.005..0.01),
       }
     end
   end
@@ -230,14 +236,14 @@ module SpecializedWorkers
       # Create separate supervisors for each worker type
       @compute_supervisor = Fractor::Supervisor.new(
         worker_pools: [
-          { worker_class: ComputeWorker, num_workers: compute_workers }
-        ]
+          { worker_class: ComputeWorker, num_workers: compute_workers },
+        ],
       )
 
       @db_supervisor = Fractor::Supervisor.new(
         worker_pools: [
-          { worker_class: DatabaseWorker, num_workers: db_workers }
-        ]
+          { worker_class: DatabaseWorker, num_workers: db_workers },
+        ],
       )
 
       @compute_results = []
@@ -253,7 +259,8 @@ module SpecializedWorkers
 
       # Create and add database work items
       db_work_items = db_tasks.map do |task|
-        DatabaseWork.new(task[:data], task[:query_type], task[:table], task[:conditions])
+        DatabaseWork.new(task[:data], task[:query_type], task[:table],
+                         task[:conditions])
       end
       @db_supervisor.add_work_items(db_work_items)
 
@@ -277,13 +284,13 @@ module SpecializedWorkers
         computation: {
           tasks: compute_tasks.size,
           completed: @compute_results.size,
-          results: @compute_results
+          results: @compute_results,
         },
         database: {
           tasks: db_tasks.size,
           completed: @db_results.size,
-          results: @db_results
-        }
+          results: @db_results,
+        },
       }
     end
 
@@ -316,18 +323,18 @@ if __FILE__ == $PROGRAM_NAME
     {
       operation: :matrix_multiply,
       data: "Matrix data...",
-      parameters: { size: [10, 10] }
+      parameters: { size: [10, 10] },
     },
     {
       operation: :image_transform,
       data: "Image data...",
-      parameters: { transforms: %i[rotate scale blur], angle: 45, scale: 1.5 }
+      parameters: { transforms: %i[rotate scale blur], angle: 45, scale: 1.5 },
     },
     {
       operation: :path_finding,
       data: "Graph data...",
-      parameters: { algorithm: :dijkstra, nodes: 20, start: 1, end: 15 }
-    }
+      parameters: { algorithm: :dijkstra, nodes: 20, start: 1, end: 15 },
+    },
   ]
 
   # Prepare database tasks
@@ -335,24 +342,24 @@ if __FILE__ == $PROGRAM_NAME
     {
       query_type: :select,
       table: "users",
-      conditions: { active: true, role: "admin" }
+      conditions: { active: true, role: "admin" },
     },
     {
       query_type: :insert,
       table: "orders",
-      data: "Order data..."
+      data: "Order data...",
     },
     {
       query_type: :update,
       table: "products",
       data: "Product data...",
-      conditions: { category: "electronics" }
+      conditions: { category: "electronics" },
     },
     {
       query_type: :delete,
       table: "sessions",
-      conditions: { expired: true }
-    }
+      conditions: { expired: true },
+    },
   ]
 
   compute_workers = 2
@@ -363,7 +370,7 @@ if __FILE__ == $PROGRAM_NAME
   start_time = Time.now
   system = SpecializedWorkers::HybridSystem.new(
     compute_workers: compute_workers,
-    db_workers: db_workers
+    db_workers: db_workers,
   )
   result = system.process_mixed_workload(compute_tasks, db_tasks)
   end_time = Time.now