fractor 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3fc9be0fb1d8993186e56bbef30b33396314e878f8a9ea3d31d79efd3c46f06
-  data.tar.gz: 8edb3ff38f5c054d9c1e477bfb799605fd4827eb679dc10db224ad1eb45e8d64
+  metadata.gz: 842123f96e07a7da2fd523396b9c3caa74e39ff3bda280fa8473c306a26d809c
+  data.tar.gz: 6bb92bd2ad43a2a7a3fac8f50056c2a0a7e16d1b79e914dc390c458d3ee3ea97
 SHA512:
-  metadata.gz: 17fbad9c566525c9b01ccd8f613a6fe2eb2be62298894fc4ae636736ad678f3d1c46fbf49cce5e84d6e3584cc0a5e31ce06f92a994f2a3b92e58cceedabafcbc
-  data.tar.gz: a33d27eb70ffbd8769c6db1f5484788d0b187b5c1feb33ba65602579a2ecc17c3c14be6654ad74c414a63cf9b5d19a818bd462293eca0ca13bfd1f92272760f1
+  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/result_aggregator.rb

@@ -13,10 +13,10 @@ module Fractor
 
     def add_result(result)
       if result.success?
-        puts "Work completed successfully: Result: #{result.result}"
+        puts "Work completed successfully: Result: #{result.result}" if ENV["FRACTOR_DEBUG"]
         @results << result
       else
-        puts "Error processing work: #{result}"
+        puts "Error processing work: #{result}" if ENV["FRACTOR_DEBUG"]
         @errors << result
       end
 

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)
@@ -88,19 +87,32 @@ module Fractor
 
     # Sets up a signal handler for graceful shutdown (Ctrl+C).
     def setup_signal_handler
-      # Need access to @workers within the trap block
+      # Store instance variables in local variables for the signal handler
       workers_ref = @workers
+
+      # Trap INT signal (Ctrl+C)
       Signal.trap("INT") do
-        puts "\nCtrl+C received. Initiating immediate shutdown..."
-        puts "Attempting to close worker Ractors..."
+        puts "\nCtrl+C received. Initiating immediate shutdown..." if ENV["FRACTOR_DEBUG"]
+
+        # Set running to false to break the main loop
+        @running = false
+
+        puts "Sending shutdown message to all Ractors..." if ENV["FRACTOR_DEBUG"]
+
+        # Send shutdown message to each worker Ractor
         workers_ref.each do |w|
-          w.close # Use the close method of WrappedRactor
-          puts "Closed Ractor: #{w.name}"
+          w.send(:shutdown)
+          puts "Sent shutdown to Ractor: #{w.name}" if ENV["FRACTOR_DEBUG"]
         rescue StandardError => e
-          puts "Error closing Ractor #{w.name}: #{e.message}"
+          puts "Error sending shutdown to Ractor #{w.name}: #{e.message}" if ENV["FRACTOR_DEBUG"]
         end
-        puts "Exiting now."
-        exit(1) # Exit immediately
+
+        puts "Exiting now." if ENV["FRACTOR_DEBUG"]
+        exit!(1) # Use exit! to exit immediately without running at_exit handlers
+      rescue Exception => e
+        puts "Error in signal handler: #{e.class}: #{e.message}" if ENV["FRACTOR_DEBUG"]
+        puts e.backtrace.join("\n") if ENV["FRACTOR_DEBUG"]
+        exit!(1)
       end
     end
 
@@ -208,11 +220,22 @@ module Fractor
     # Stop the supervisor (for continuous mode)
     def stop
       @running = false
-      puts "Stopping supervisor..."
+      puts "Stopping supervisor..." if ENV["FRACTOR_DEBUG"]
     end
 
     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.2"
+  VERSION = "0.1.4"
 end

data/lib/fractor/wrapped_ractor.rb

@@ -9,7 +9,7 @@ module Fractor
     # Initializes the WrappedRactor with a name and the Worker class to instantiate.
     # The worker_class parameter allows flexibility in specifying the worker type.
     def initialize(name, worker_class)
-      puts "Creating Ractor #{name} with worker #{worker_class}"
+      puts "Creating Ractor #{name} with worker #{worker_class}" if ENV["FRACTOR_DEBUG"]
       @name = name
       @worker_class = worker_class # Store the worker class
       @ractor = nil # Initialize ractor as nil
@@ -17,10 +17,10 @@ module Fractor
 
     # Starts the underlying Ractor.
     def start
-      puts "Starting Ractor #{@name}"
+      puts "Starting Ractor #{@name}" if ENV["FRACTOR_DEBUG"]
       # Pass worker_class to the Ractor block
       @ractor = Ractor.new(@name, @worker_class) do |name, worker_cls|
-        puts "Ractor #{name} started with worker class #{worker_cls}"
+        puts "Ractor #{name} started with worker class #{worker_cls}" if ENV["FRACTOR_DEBUG"]
         # Yield an initialization message
         Ractor.yield({ type: :initialize, processor: name })
 
@@ -29,19 +29,26 @@ module Fractor
 
         loop do
           # Ractor.receive will block until a message is received
-          puts "Waiting for work in #{name}"
+          puts "Waiting for work in #{name}" if ENV["FRACTOR_DEBUG"]
           work = Ractor.receive
-          puts "Received work #{work.inspect} in #{name}"
+
+          # Handle shutdown message
+          if work == :shutdown
+            puts "Received shutdown message in Ractor #{name}, terminating..." if ENV["FRACTOR_DEBUG"]
+            break
+          end
+
+          puts "Received work #{work.inspect} in #{name}" if ENV["FRACTOR_DEBUG"]
 
           begin
             # Process the work using the instantiated worker
             result = worker.process(work)
-            puts "Sending result #{result.inspect} from Ractor #{name}"
+            puts "Sending result #{result.inspect} from Ractor #{name}" if ENV["FRACTOR_DEBUG"]
             # Yield the result back
             Ractor.yield({ type: :result, result: result, processor: name })
           rescue StandardError => e
             # Handle errors during processing
-            puts "Error processing work #{work.inspect} in Ractor #{name}: #{e.message}\n#{e.backtrace.join("\n")}"
+            puts "Error processing work #{work.inspect} in Ractor #{name}: #{e.message}\n#{e.backtrace.join("\n")}" if ENV["FRACTOR_DEBUG"]
             # Yield an error message back
             # Ensure the original work object is included in the error result
             error_result = Fractor::WorkResult.new(error: e.message, work: work)
@@ -49,14 +56,14 @@ module Fractor
           end
         end
       rescue Ractor::ClosedError
-        puts "Ractor #{name} closed."
+        puts "Ractor #{name} closed." if ENV["FRACTOR_DEBUG"]
       rescue StandardError => e
-        puts "Unexpected error in Ractor #{name}: #{e.message}\n#{e.backtrace.join("\n")}"
+        puts "Unexpected error in Ractor #{name}: #{e.message}\n#{e.backtrace.join("\n")}" if ENV["FRACTOR_DEBUG"]
         # Optionally yield a critical error message if needed
       ensure
-        puts "Ractor #{name} shutting down."
+        puts "Ractor #{name} shutting down." if ENV["FRACTOR_DEBUG"]
       end
-      puts "Ractor #{@name} instance created: #{@ractor}"
+      puts "Ractor #{@name} instance created: #{@ractor}" if ENV["FRACTOR_DEBUG"]
     end
 
     # Sends work to the Ractor if it's active.
@@ -66,11 +73,11 @@ module Fractor
           @ractor.send(work)
           true
         rescue Exception => e
-          puts "Warning: Error sending work to Ractor #{@name}: #{e.message}"
+          puts "Warning: Error sending work to Ractor #{@name}: #{e.message}" if ENV["FRACTOR_DEBUG"]
           false
         end
       else
-        puts "Warning: Attempted to send work to nil Ractor #{@name}"
+        puts "Warning: Attempted to send work to nil Ractor #{@name}" if ENV["FRACTOR_DEBUG"]
         false
       end
     end
@@ -108,7 +115,7 @@ module Fractor
 
         true
       rescue Exception => e
-        puts "Warning: Error closing Ractor #{@name}: #{e.message}"
+        puts "Warning: Error closing Ractor #{@name}: #{e.message}" if ENV["FRACTOR_DEBUG"]
         # Consider it closed even if there was an error
         @ractor = nil
         true
@@ -131,7 +138,7 @@ module Fractor
         false
       rescue Exception => e
         # If we get an exception, the Ractor is likely terminated
-        puts "Ractor #{@name} appears to be terminated: #{e.message}"
+        puts "Ractor #{@name} appears to be terminated: #{e.message}" if ENV["FRACTOR_DEBUG"]
         @ractor = nil
         true
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fractor
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  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