fractor 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b51bfbe1d8aac8575dcd85deb88b286b8f3b26e391a228e01d43f3a466d91f26
-  data.tar.gz: '08198a0b664d2ddfa9cbef0a173f1672f9584dba1700f82374b0b9916cad91a6'
+  metadata.gz: 842123f96e07a7da2fd523396b9c3caa74e39ff3bda280fa8473c306a26d809c
+  data.tar.gz: 6bb92bd2ad43a2a7a3fac8f50056c2a0a7e16d1b79e914dc390c458d3ee3ea97
 SHA512:
-  metadata.gz: af7c2e42e19b28ced53b9e3aecf37409b9aff3c92d8829a0835312a4a5852069530b36f57c01c84727d09ad9de3b308ecfa05a5a812454402a300219938bce19
-  data.tar.gz: e08de69150ff8d528d481fcb1e872cd2d274e6b332f6d2ad3ad3b879e13328d50af3fae3294aecd81851dc7d6f3f6cc317570a7978b0f1a8adcd142d4b18a8f5
+  metadata.gz: 3f0613742f3e736514ef88cafde83a35d68e02178a034565b3c36aad00f7f6463fec3f4aad37bdc5dc65dd2c12c7c033b29009db97704e8c9cf4c67607f8f58a
+  data.tar.gz: d8e466f3244f0a88456f9c42388590a6c67e3e552b4b3e7d769217b32ddf12b2595264944241590e4c4f0ec098a79ac02bfe39622ba3d4f95cd037bd3d23e064

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-05-08 09:25:37 UTC using RuboCop version 1.75.5.
+# on 2025-10-09 11:44:45 UTC using RuboCop version 1.75.4.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -14,11 +14,6 @@ Lint/ConstantDefinitionInBlock:
     - 'spec/fractor/integration_spec.rb'
     - 'spec/fractor/work_spec.rb'
 
-# Offense count: 1
-Lint/DuplicateMethods:
-  Exclude:
-    - 'lib/fractor/supervisor.rb'
-
 # Offense count: 1
 Lint/HashCompareByIdentity:
   Exclude:
@@ -30,43 +25,44 @@ Lint/MissingSuper:
   Exclude:
     - 'examples/specialized_workers/specialized_workers.rb'
 
-# Offense count: 3
+# Offense count: 4
 Lint/RescueException:
   Exclude:
+    - 'lib/fractor/supervisor.rb'
     - 'lib/fractor/wrapped_ractor.rb'
 
-# Offense count: 18
+# Offense count: 24
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
 Metrics/AbcSize:
   Max: 98
 
-# Offense count: 9
+# Offense count: 15
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 101
+  Max: 142
 
-# Offense count: 2
+# Offense count: 4
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 159
+  Max: 171
 
-# Offense count: 3
+# Offense count: 9
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/CyclomaticComplexity:
   Max: 37
 
-# Offense count: 33
+# Offense count: 46
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 67
+  Max: 78
 
 # Offense count: 1
 # Configuration parameters: Max, CountKeywordArgs.
 Metrics/ParameterLists:
   MaxOptionalParameters: 4
 
-# Offense count: 2
+# Offense count: 6
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/PerceivedComplexity:
   Max: 37
@@ -84,13 +80,7 @@ Style/Documentation:
     - 'test/**/*'
     - 'examples/hierarchical_hasher/hierarchical_hasher.rb'
 
-# Offense count: 13
-# This cop supports safe autocorrection (--autocorrect).
-Style/IfUnlessModifier:
-  Exclude:
-    - 'lib/fractor/supervisor.rb'
-
-# Offense count: 6
+# Offense count: 12
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https

data/README.adoc

@@ -267,16 +267,25 @@ 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 the number of workers to create. 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.
+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
+# Create the supervisor with auto-detected number of workers
 supervisor = Fractor::Supervisor.new(
   worker_pools: [
-    { worker_class: MyWorker, num_workers: 4 }  # One pool with 4 workers
+    { worker_class: MyWorker }  # Number of workers auto-detected
+  ]
+)
+
+# Or explicitly specify the number of workers
+supervisor = Fractor::Supervisor.new(
+  worker_pools: [
+    { worker_class: MyWorker, num_workers: 4 }  # Explicitly use 4 workers
   ]
 )
 
@@ -619,6 +628,47 @@ supervisor = Fractor::Supervisor.new(
 )
 ----
 
+==== Worker auto-detection
+
+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.
+
+[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
+  ]
+)
+----
+
+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:
@@ -897,8 +947,24 @@ Key features:
 * 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.
+
+Key features:
+
+* 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
+
 === Hierarchical hasher
 
 The Hierarchical Hasher example

data/examples/auto_detection/README.adoc

@@ -0,0 +1,52 @@
+= Auto-Detection Example
+
+This example demonstrates Fractor's automatic worker detection feature.
+
+== Purpose
+
+Shows how Fractor can automatically detect the number of available processors on your system and create the optimal number of workers without manual configuration.
+
+== What This Demonstrates
+
+* How Fractor automatically detects the number of available processors
+* Comparison between auto-detection and explicit worker configuration
+* Mixed configuration (some pools with auto-detection, some explicit)
+* How to verify the number of workers being used
+
+== When to Use Auto-Detection
+
+* For portable code that adapts to different environments
+* When you want optimal resource utilization without manual tuning
+* For development where the number of cores varies across machines
+
+== When to Set Explicit Values
+
+* When you need precise control over resource usage
+* For production environments with specific requirements
+* When limiting workers due to memory or other constraints
+
+== Running the Example
+
+[source,shell]
+----
+ruby examples/auto_detection/auto_detection.rb
+----
+
+== Expected Output
+
+The script will:
+
+1. Display the number of processors detected on your system
+2. Run three examples:
+   * Example 1: Auto-detection (uses all available processors)
+   * Example 2: Explicit configuration (uses exactly 4 workers)
+   * Example 3: Mixed configuration (combines both approaches)
+3. Show results from processing work items in parallel
+4. Provide a summary of benefits for each approach
+
+== Key Takeaways
+
+* Auto-detection provides automatic adaptation to different environments
+* Explicit configuration provides precise control when needed
+* You can mix both approaches in the same supervisor
+* Best practice: use auto-detection for development, tune for production if needed

data/examples/auto_detection/auto_detection.rb

@@ -0,0 +1,170 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# =============================================================================
+# Auto-Detection Example
+# =============================================================================
+#
+# This example demonstrates Fractor's automatic worker detection feature.
+#
+# WHAT THIS DEMONSTRATES:
+# - How Fractor automatically detects the number of available processors
+# - Comparison between auto-detection and explicit worker configuration
+# - Mixed configuration (some pools with auto-detection, some explicit)
+# - How to verify the number of workers being used
+#
+# WHEN TO USE AUTO-DETECTION:
+# - For portable code that adapts to different environments
+# - When you want optimal resource utilization without manual tuning
+# - For development where the number of cores varies across machines
+#
+# WHEN TO SET EXPLICIT VALUES:
+# - When you need precise control over resource usage
+# - For production environments with specific requirements
+# - When limiting workers due to memory or other constraints
+#
+# HOW TO RUN:
+#   ruby examples/auto_detection/auto_detection.rb
+#
+# WHAT TO EXPECT:
+# - The script will show how many processors were auto-detected
+# - It will create workers based on detection vs explicit configuration
+# - Results will be processed in parallel across all workers
+#
+# =============================================================================
+
+require_relative "../../lib/fractor"
+require "etc"
+
+# Simple work class for demonstration
+class ComputeWork < Fractor::Work
+  def initialize(value)
+    super({ value: value })
+  end
+
+  def value
+    input[:value]
+  end
+
+  def to_s
+    "ComputeWork: #{value}"
+  end
+end
+
+# Simple worker that squares numbers
+class ComputeWorker < Fractor::Worker
+  def process(work)
+    result = work.value * work.value
+    Fractor::WorkResult.new(result: result, work: work)
+  rescue StandardError => e
+    Fractor::WorkResult.new(error: e, work: work)
+  end
+end
+
+# =============================================================================
+# DEMONSTRATION
+# =============================================================================
+
+puts "=" * 80
+puts "Fractor Auto-Detection Example"
+puts "=" * 80
+puts
+
+# Show system information
+num_processors = Etc.nprocessors
+puts "System Information:"
+puts "  Available processors: #{num_processors}"
+puts
+
+# Example 1: Auto-detection (recommended for most cases)
+puts "-" * 80
+puts "Example 1: Auto-Detection"
+puts "-" * 80
+puts "Creating supervisor WITHOUT specifying num_workers..."
+puts "Fractor will automatically detect and use #{num_processors} workers"
+puts
+
+supervisor1 = Fractor::Supervisor.new(
+  worker_pools: [
+    { worker_class: ComputeWorker } # No num_workers specified
+  ]
+)
+
+# Add work items
+work_items = (1..10).map { |i| ComputeWork.new(i) }
+supervisor1.add_work_items(work_items)
+
+puts "Processing 10 work items with auto-detected workers..."
+supervisor1.run
+
+puts "Results: #{supervisor1.results.results.map(&:result).sort.join(", ")}"
+puts "✓ Auto-detection successful!"
+puts
+
+# Example 2: Explicit configuration
+puts "-" * 80
+puts "Example 2: Explicit Configuration"
+puts "-" * 80
+puts "Creating supervisor WITH explicit num_workers=4..."
+puts
+
+supervisor2 = Fractor::Supervisor.new(
+  worker_pools: [
+    { worker_class: ComputeWorker, num_workers: 4 }
+  ]
+)
+
+supervisor2.add_work_items((11..20).map { |i| ComputeWork.new(i) })
+
+puts "Processing 10 work items with 4 explicitly configured workers..."
+supervisor2.run
+
+puts "Results: #{supervisor2.results.results.map(&:result).sort.join(", ")}"
+puts "✓ Explicit configuration successful!"
+puts
+
+# Example 3: Mixed configuration
+puts "-" * 80
+puts "Example 3: Mixed Auto-Detection and Explicit Configuration"
+puts "-" * 80
+puts "Creating supervisor with multiple worker pools:"
+puts "  - Pool 1: Auto-detected workers"
+puts "  - Pool 2: 2 explicitly configured workers"
+puts
+
+supervisor3 = Fractor::Supervisor.new(
+  worker_pools: [
+    { worker_class: ComputeWorker }, # Auto-detected
+    { worker_class: ComputeWorker, num_workers: 2 } # Explicit
+  ]
+)
+
+supervisor3.add_work_items((21..30).map { |i| ComputeWork.new(i) })
+
+puts "Processing 10 work items with mixed configuration..."
+supervisor3.run
+
+puts "Results: #{supervisor3.results.results.map(&:result).sort.join(", ")}"
+puts "✓ Mixed configuration successful!"
+puts
+
+# Summary
+puts "=" * 80
+puts "Summary"
+puts "=" * 80
+puts
+puts "Auto-detection provides:"
+puts "  ✓ Automatic adaptation to different environments"
+puts "  ✓ Optimal resource utilization by default"
+puts "  ✓ Less configuration needed"
+puts "  ✓ Portability across machines with different CPU counts"
+puts
+puts "Explicit configuration provides:"
+puts "  ✓ Precise control over worker count"
+puts "  ✓ Ability to limit resource usage"
+puts "  ✓ Predictable behavior in production"
+puts
+puts "Best practice: Use auto-detection for development and testing,"
+puts "               then tune explicitly for production if needed."
+puts
+puts "=" * 80

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
@@ -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
     ]
   )
 

data/lib/fractor/supervisor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "etc"
+
 module Fractor
   # Supervises multiple WrappedRactors, distributes work, and aggregates results.
   class Supervisor
@@ -13,7 +15,7 @@ module Fractor
     def initialize(worker_pools: [], continuous_mode: false)
       @worker_pools = worker_pools.map do |pool_config|
         worker_class = pool_config[:worker_class]
-        num_workers = pool_config[:num_workers] || 2
+        num_workers = pool_config[:num_workers] || detect_num_workers
 
         raise ArgumentError, "#{worker_class} must inherit from Fractor::Worker" unless worker_class < Fractor::Worker
 
@@ -46,9 +48,6 @@ module Fractor
       puts "Work item added. Initial work count: #{@total_work_count}, Queue size: #{@work_queue.size}"
     end
 
-    # Alias for better naming
-    alias add_work_item add_work_item
-
     # Adds multiple work items to the queue.
     # Each item must be an instance of Fractor::Work or a subclass.
     def add_work_items(works)
@@ -226,6 +225,17 @@ module Fractor
 
     private
 
+    # Detects the number of available processors on the system.
+    # Returns the number of processors, or 2 as a fallback if detection fails.
+    def detect_num_workers
+      num_processors = Etc.nprocessors
+      puts "Auto-detected #{num_processors} available processors" if ENV["FRACTOR_DEBUG"]
+      num_processors
+    rescue StandardError => e
+      puts "Failed to detect processors: #{e.message}. Using default of 2 workers." if ENV["FRACTOR_DEBUG"]
+      2
+    end
+
     # Helper method to send the next available work item to a specific Ractor.
     def send_next_work_if_available(wrapped_ractor)
       # Ensure the wrapped_ractor instance is valid and its underlying ractor is not closed

data/lib/fractor/version.rb

@@ -2,5 +2,5 @@
 
 module Fractor
   # Fractor version
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fractor
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Ronald Tse
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-08 00:00:00.000000000 Z
+date: 2025-10-09 00:00:00.000000000 Z
 dependencies: []
 description: Fractor is a lightweight Ruby framework designed to simplify the process
   of distributing computational work across multiple Ractors.
@@ -24,6 +24,8 @@ files:
 - CODE_OF_CONDUCT.md
 - README.adoc
 - Rakefile
+- examples/auto_detection/README.adoc
+- examples/auto_detection/auto_detection.rb
 - examples/hierarchical_hasher/README.adoc
 - examples/hierarchical_hasher/hierarchical_hasher.rb
 - examples/multi_work_type/README.adoc