fractor 0.1.0 → 0.1.1

data/examples/scatter_gather/scatter_gather.rb

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+
+require_relative "../../lib/fractor"
+
+module ScatterGather
+  # Specialized work for different search sources
+  class SearchWork < Fractor::Work
+    def initialize(query, source = :default, query_params = {})
+      super({ query: query, source: source, query_params: query_params })
+    end
+
+    def query
+      input[:query]
+    end
+
+    def source
+      input[:source]
+    end
+
+    def query_params
+      input[:query_params]
+    end
+
+    def to_s
+      "SearchWork: source=#{source}, params=#{query_params}, query=#{query}"
+    end
+  end
+
+  # Worker specialized for different data sources
+  class SearchWorker < Fractor::Worker
+    def process(work)
+      # Simulate database connection setup
+      setup_source(work.source)
+
+      # Process based on source type
+      result = case work.source
+               when :database then search_database(work)
+               when :api then search_api(work)
+               when :cache then search_cache(work)
+               when :filesystem then search_filesystem(work)
+               else
+                 error = ArgumentError.new("Unknown source: #{work.source}")
+                 return Fractor::WorkResult.new(
+                   error: error,
+                   work: work
+                 )
+               end
+
+      # Return result with source information for merging
+      Fractor::WorkResult.new(
+        result: {
+          source: work.source,
+          query: work.query,
+          hits: result[:hits],
+          metadata: result[:metadata],
+          timing: result[:timing]
+        },
+        work: work
+      )
+    end
+
+    private
+
+    def setup_source(_source)
+      # Simulate connection/initialization time
+      sleep(rand(0.01..0.05))
+    end
+
+    def search_database(work)
+      # Simulate database query
+      sleep(rand(0.05..0.2))
+
+      # Generate simulated records
+      record_count = rand(3..10)
+      hits = record_count.times.map 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)
+        }
+      end
+
+      {
+        hits: hits,
+        metadata: {
+          source_type: "PostgreSQL Database",
+          total_available: record_count + rand(10..50),
+          query_type: "Full-text search"
+        },
+        timing: rand(0.01..0.3).round(3)
+      }
+    end
+
+    def search_api(work)
+      # Simulate API request
+      sleep(rand(0.1..0.3))
+
+      # Generate simulated API results
+      record_count = rand(2..8)
+      hits = record_count.times.map 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)
+        }
+      end
+
+      {
+        hits: hits,
+        metadata: {
+          source_type: "External REST API",
+          provider: %w[Google Bing DuckDuckGo].sample,
+          response_code: 200
+        },
+        timing: rand(0.1..0.5).round(3)
+      }
+    end
+
+    def search_cache(work)
+      # Simulate cache lookup
+      sleep(rand(0.01..0.1))
+
+      # Simulate cache hit or miss
+      cache_hit = [true, true, false].sample
+
+      if cache_hit
+        # Cache hit - return cached results
+        record_count = rand(1..5)
+        hits = record_count.times.map 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)
+          }
+        end
+
+        {
+          hits: hits,
+          metadata: {
+            source_type: "In-memory Cache",
+            cache_hit: true,
+            age: rand(1..3600)
+          },
+          timing: rand(0.001..0.05).round(3)
+        }
+      else
+        # Cache miss
+        {
+          hits: [],
+          metadata: {
+            source_type: "In-memory Cache",
+            cache_hit: false
+          },
+          timing: rand(0.001..0.01).round(3)
+        }
+      end
+    end
+
+    def search_filesystem(work)
+      # Simulate file system search
+      sleep(rand(0.05..0.2))
+
+      # Generate simulated file results
+      record_count = rand(1..12)
+      hits = record_count.times.map 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)
+        }
+      end
+
+      {
+        hits: hits,
+        metadata: {
+          source_type: "File System",
+          directories_searched: rand(5..20),
+          files_scanned: rand(50..500)
+        },
+        timing: rand(0.01..0.2).round(3)
+      }
+    end
+  end
+
+  # Controller for the multi-source search
+  class MultiSourceSearch
+    attr_reader :merged_results
+
+    def initialize(worker_count = 4)
+      @supervisor = Fractor::Supervisor.new(
+        worker_pools: [
+          { worker_class: SearchWorker, num_workers: worker_count }
+        ]
+      )
+
+      @merged_results = nil
+    end
+
+    def search(query, sources = nil)
+      # Define search sources with their parameters
+      sources ||= [
+        { 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] } }
+      ]
+
+      start_time = Time.now
+
+      # Create work items and run the searches in parallel
+      search_work_items = sources.map do |source|
+        SearchWork.new(query, source[:source], source[:params])
+      end
+      @supervisor.add_work_items(search_work_items)
+      @supervisor.run
+
+      end_time = Time.now
+      total_time = end_time - start_time
+
+      # Merge results with source-specific relevance rules
+      @merged_results = merge_results(@supervisor.results, total_time)
+
+      @merged_results
+    end
+
+    private
+
+    def merge_results(results_aggregator, total_time)
+      # Group results by source using a standard approach
+      # This is more reliable than using Ractors for this simple aggregation
+      results_by_source = {}
+      total_hits = 0
+
+      results_aggregator.results.each do |result|
+        source = result.result[:source]
+        results_by_source[source] = result.result
+        total_hits += result.result[:hits].size
+      end
+
+      # Create combined and ranked results
+      all_hits = []
+      results_by_source.each do |source, result|
+        # Add source-specific weight
+        source_weight = case source
+                        when :database then 1.0
+                        when :api then 0.8
+                        when :cache then 1.2 # Prioritize cache
+                        when :filesystem then 0.9
+                        else 0.5
+                        end
+
+        # Add weighted hits to combined list
+        result[:hits].each do |hit|
+          all_hits << {
+            id: hit[:id],
+            title: hit[:title],
+            content: hit[:content],
+            source: source,
+            original_relevance: hit[:relevance],
+            weighted_relevance: hit[:relevance] * source_weight
+          }
+        end
+      end
+
+      # Sort by weighted relevance
+      ranked_hits = all_hits.sort_by { |hit| -hit[:weighted_relevance] }
+
+      # Return merged results
+      {
+        query: results_by_source.values.first&.dig(:query),
+        total_hits: total_hits,
+        execution_time: total_time,
+        sources: results_by_source.keys,
+        ranked_results: ranked_hits,
+        source_details: results_by_source
+      }
+    end
+  end
+end
+
+# Example usage
+if __FILE__ == $PROGRAM_NAME
+  puts "Starting Scatter-Gather Search Example"
+  puts "======================================"
+  puts "This example demonstrates searching multiple data sources concurrently:"
+  puts "1. Database - Simulates SQL database searches"
+  puts "2. API - Simulates external REST API calls"
+  puts "3. Cache - Simulates in-memory cache lookups"
+  puts "4. Filesystem - Simulates searching through files"
+  puts
+
+  # Sample query
+  query = ARGV[0] || "ruby concurrency patterns"
+  worker_count = (ARGV[1] || 4).to_i
+
+  puts "Searching for: '#{query}' using #{worker_count} workers..." if ENV["FRACTOR_DEBUG"]
+  puts if ENV["FRACTOR_DEBUG"]
+
+  search = ScatterGather::MultiSourceSearch.new(worker_count)
+  results = search.search(query)
+
+  puts "Search Results Summary:"
+  puts "----------------------"
+  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
+
+  puts "Top 5 Results (by relevance):"
+  results[:ranked_results].take(5).each_with_index do |hit, index|
+    puts "#{index + 1}. #{hit[:title]} (Source: #{hit[:source]}, Relevance: #{hit[:weighted_relevance].round(2)})"
+    puts "   #{hit[:content][0..60]}..."
+    puts
+  end
+
+  puts "Source Details:"
+  results[:source_details].each do |source, details|
+    puts "- #{source.to_s.capitalize} (#{details[:hits].size} results, #{details[:timing]} sec)"
+    puts "  Metadata: #{details[:metadata]}"
+  end
+end

data/examples/simple/sample.rb

@@ -0,0 +1,101 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "fractor"
+
+# Client-specific work item implementation inheriting from Fractor::Work
+class MyWork < Fractor::Work
+  # Constructor storing all data in the input hash
+  def initialize(value)
+    super({ value: value })
+  end
+
+  def value
+    input[:value]
+  end
+
+  def to_s
+    "MyWork: #{value}"
+  end
+end
+
+# Another work type for demonstrating multiple work types
+class OtherWork < Fractor::Work
+  # Constructor storing all data in the input hash
+  def initialize(value)
+    super({ value: value })
+  end
+
+  def value
+    input[:value]
+  end
+
+  def to_s
+    "OtherWork: #{value}"
+  end
+end
+
+# Client-specific worker implementation inheriting from Fractor::Worker
+class MyWorker < Fractor::Worker
+  # This method is called by the Ractor to process the work
+  # 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"]
+
+    # 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")
+        return Fractor::WorkResult.new(error: error, work: work)
+      end
+
+      calculated = work.value * 2
+      # Return a Fractor::WorkResult for success
+      Fractor::WorkResult.new(result: calculated, work: work)
+    elsif work.is_a?(OtherWork)
+      # Process OtherWork differently
+      Fractor::WorkResult.new(result: "Processed: #{work.value}", work: work)
+    else
+      # Handle unexpected work types - create a proper error object
+      error = TypeError.new("Unsupported work type: #{work.class}")
+      Fractor::WorkResult.new(error: error, work: work)
+    end
+  end
+end
+
+# --- Main Execution ---
+# This section demonstrates how to use the Fractor framework with custom
+# MyWorker and MyWork classes.
+if __FILE__ == $PROGRAM_NAME
+  # Create supervisor, passing the client-specific worker class in a worker pool
+  supervisor = Fractor::Supervisor.new(
+    worker_pools: [
+      { worker_class: MyWorker, num_workers: 2 } # Specify the worker class and number of worker Ractors
+    ]
+  )
+
+  # Create Work objects and add them to the supervisor
+  work_items = (1..10).map { |i| MyWork.new(i) }
+  supervisor.add_work_items(work_items)
+
+  # Run the supervisor to start processing work
+  supervisor.run
+
+  puts "Processing complete."
+  puts "Final Aggregated Results:"
+  # Access the results aggregator from the supervisor
+  puts supervisor.results.inspect
+
+  # Print failed items directly from the Fractor::ResultAggregator's errors array
+  failed_items = supervisor.results.errors # Access the errors array
+  puts "\nFailed Work Items (#{failed_items.size}):"
+
+  # Display error information properly using the error object
+  failed_items.each do |error_result|
+    puts "Work: #{error_result.work.inspect}"
+    puts "Error: #{error_result.error.class}: #{error_result.error.message}"
+  end
+end

data/examples/specialized_workers/README.adoc

@@ -0,0 +1,45 @@
+= Specialized Workers Example
+
+== Overview
+
+This example demonstrates how to create specialized worker types in Fractor, each designed to handle specific kinds of work. This pattern is useful when different work items require fundamentally different processing approaches.
+
+== Key Concepts
+
+* *Specialized Workers*: Worker classes designed for specific types of tasks
+* *Work Type Differentiation*: Each worker specializes in processing a particular category of work
+* *Resource Optimization*: Workers can be tailored to the specific resources needed by each work type
+* *Domain-Specific Processing*: Separate worker implementations for different processing domains
+
+== Example Explanation
+
+This example implements two specialized worker types:
+
+1. *ComputeWorker*: Handles compute-intensive operations like matrix multiplication, image transformations, and path finding
+2. *DatabaseWorker*: Handles database operations like queries, insertions, updates, and deletions
+
+Each worker is optimized for its specific task domain and processes only the work types it is designed to handle.
+
+== Features Demonstrated
+
+* Creating specialized worker types to handle different categories of work
+* Routing work items to the appropriate worker type
+* Resource optimization for different processing needs
+* Independent error handling for each worker type
+* Combining results from different worker types
+
+== Running the Example
+
+[source,sh]
+----
+ruby examples/specialized_workers/specialized_workers.rb
+----
+
+== Expected Output
+
+The example will show:
+* Creation of different worker types
+* Processing of specialized work items by their corresponding workers
+* Performance metrics for each work type
+* Separate results from each worker type
+* Overall processing statistics