fractor 0.1.7 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1116370e6ae5e6a855fd9fc3fdb934d99c974e49757a42d6a43f8197da7edc71
-  data.tar.gz: 26b38206c9ec5c5bf966ebaf1f5c13c4f1b67d580ae5e37f069bc176cff56797
+  metadata.gz: 9b4ea06ce5fb4dc056cd294dcadeac07cca24610a0b995e5f910b3ef0075e0ea
+  data.tar.gz: 1adc8b962143e4713259b18c5545ab39ee0a62b11db5880b0389ff64449a27b8
 SHA512:
-  metadata.gz: d8c1c4295d25825980334809306eb9749d3e49649a87fbdc736d0310a406d8f4df87cb2f603e6298981b3c3bfcb0ba5a53b5679868c26752dc3fdeefb2f093d1
-  data.tar.gz: d37b73bcb9826d0c5ae00ff9a27c502b43e67a8cff8883b1a9c4e8cab86c6bb997e85c65b40e22515cb4b65e29b68b14c46a28bb122c8b227cf9786fc5bf0e13
+  metadata.gz: 31800cb4767762f1bdd1fec315cda164fd5effb3fd72bb327b4a30788ac41b2b2cd0ec3bcf2548e82fe69ccf97150007222e81c875bcb5f78c01d4e28162ef03
+  data.tar.gz: 728316725154c5fde32f2bb8fb6ab584b26814ad463af43c4928a333083ed34e6d66dc781c6edad82128644f0f6b6197c31303aa6353ec586aeaa81212dd911d

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-01-22 06:39:26 UTC using RuboCop version 1.82.1.
+# on 2026-01-22 09:15:54 UTC using RuboCop version 1.82.1.
 # 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
@@ -11,47 +11,86 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'fractor.gemspec'
 
-# Offense count: 4
+# Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, IndentationWidth.
 # SupportedStyles: with_first_argument, with_fixed_indentation
 Layout/ArgumentAlignment:
   Exclude:
-    - 'spec/fractor/main_loop_handler3_spec.rb'
-    - 'spec/fractor/main_loop_handler4_spec.rb'
-    - 'spec/fractor/supervisor_shutdown_spec.rb'
+    - 'lib/fractor/queue_persister.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_element, with_fixed_indentation
+Layout/ArrayAlignment:
+  Exclude:
+    - 'lib/fractor/queue_persister.rb'
 
 # Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyleAlignWith.
-# SupportedStylesAlignWith: either, start_of_block, start_of_line
-Layout/BlockAlignment:
+# Configuration parameters: IndentationWidth.
+Layout/AssignmentIndentation:
   Exclude:
-    - 'spec/fractor/main_loop_handler3_spec.rb'
-    - 'spec/fractor/main_loop_handler4_spec.rb'
+    - 'lib/fractor/queue_persister.rb'
+    - 'lib/fractor/result_cache.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Layout/ClosingParenthesisIndentation:
+  Exclude:
+    - 'spec/fractor/persistent_work_queue_spec.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: consistent, consistent_relative_to_receiver, special_for_inner_method_call, special_for_inner_method_call_in_parentheses
+Layout/FirstArgumentIndentation:
+  Exclude:
+    - 'spec/fractor/persistent_work_queue_spec.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
+# SupportedHashRocketStyles: key, separator, table
+# SupportedColonStyles: key, separator, table
+# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
+Layout/HashAlignment:
+  Exclude:
+    - 'spec/fractor/persistent_work_queue_spec.rb'
+    - 'spec/fractor/work_timeout_spec.rb'
 
-# Offense count: 455
+# Offense count: 470
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 4
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: symmetrical, new_line, same_line
+Layout/MultilineMethodCallBraceLayout:
+  Exclude:
+    - 'spec/fractor/persistent_work_queue_spec.rb'
+
+# Offense count: 6
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowInHeredoc.
 Layout/TrailingWhitespace:
   Exclude:
-    - 'spec/fractor/main_loop_handler3_spec.rb'
-    - 'spec/fractor/main_loop_handler4_spec.rb'
-    - 'spec/fractor/supervisor_shutdown_spec.rb'
+    - 'lib/fractor/queue_persister.rb'
+    - 'lib/fractor/result_cache.rb'
+    - 'spec/fractor/persistent_work_queue_spec.rb'
+    - 'spec/fractor/work_timeout_spec.rb'
 
 # Offense count: 1
 Lint/BinaryOperatorWithIdenticalOperands:
   Exclude:
     - 'spec/fractor/priority_work_spec.rb'
 
-# Offense count: 14
+# Offense count: 20
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: enums
 Lint/ConstantDefinitionInBlock:
@@ -60,7 +99,10 @@ Lint/ConstantDefinitionInBlock:
     - 'spec/examples/performance_monitoring_spec.rb'
     - 'spec/examples/priority_work_example_spec.rb'
     - 'spec/fractor/integration_spec.rb'
+    - 'spec/fractor/persistent_work_queue_spec.rb'
+    - 'spec/fractor/result_cache_spec.rb'
     - 'spec/fractor/work_spec.rb'
+    - 'spec/fractor/work_timeout_spec.rb'
     - 'spec/fractor/worker_timeout_spec.rb'
     - 'spec/fractor/workflow/execution_strategy_spec.rb'
 
@@ -77,10 +119,11 @@ Lint/HashCompareByIdentity:
     - 'lib/fractor/work_distribution_manager.rb'
     - 'spec/fractor/work_distribution_manager_spec.rb'
 
-# Offense count: 1
+# Offense count: 4
 # Configuration parameters: AllowedParentClasses.
 Lint/MissingSuper:
   Exclude:
+    - 'lib/fractor/queue_persister.rb'
     - 'spec/fractor/wrapped_ractor3_spec.rb'
 
 # Offense count: 5
@@ -91,7 +134,7 @@ Lint/RescueException:
     - 'lib/fractor/wrapped_ractor3.rb'
     - 'lib/fractor/wrapped_ractor4.rb'
 
-# Offense count: 4
+# Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
 # NotImplementedExceptions: NotImplementedError
@@ -99,9 +142,8 @@ Lint/UnusedMethodArgument:
   Exclude:
     - 'lib/fractor/workflow.rb'
     - 'lib/fractor/wrapped_ractor3.rb'
-    - 'spec/fractor/wrapped_ractor3_spec.rb'
 
-# Offense count: 88
+# Offense count: 89
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -110,24 +152,24 @@ Metrics/AbcSize:
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 105
+  Max: 110
 
-# Offense count: 61
+# Offense count: 64
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 142
+# Offense count: 149
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 117
+  Max: 122
 
 # Offense count: 9
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 9
 
-# Offense count: 46
+# Offense count: 49
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
@@ -185,21 +227,12 @@ RSpec/ContextWording:
     - 'spec/fractor/supervisor_spec.rb'
     - 'spec/fractor_spec.rb'
 
-# Offense count: 27
+# Offense count: 28
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
 
-# Offense count: 3
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: SkipBlocks, EnforcedStyle, OnlyStaticConstants.
-# SupportedStyles: described_class, explicit
-RSpec/DescribedClass:
-  Exclude:
-    - 'spec/fractor/worker_spec.rb'
-    - 'spec/fractor/worker_timeout_spec.rb'
-
-# Offense count: 510
+# Offense count: 542
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 47
@@ -246,14 +279,17 @@ RSpec/InstanceVariable:
     - 'spec/examples/workflow/dead_letter_queue_workflow_spec.rb'
     - 'spec/fractor/integration_spec.rb'
 
-# Offense count: 16
+# Offense count: 22
 RSpec/LeakyConstantDeclaration:
   Exclude:
     - 'spec/examples/error_reporting_spec.rb'
     - 'spec/examples/performance_monitoring_spec.rb'
     - 'spec/examples/priority_work_example_spec.rb'
     - 'spec/fractor/integration_spec.rb'
+    - 'spec/fractor/persistent_work_queue_spec.rb'
+    - 'spec/fractor/result_cache_spec.rb'
     - 'spec/fractor/work_spec.rb'
+    - 'spec/fractor/work_timeout_spec.rb'
     - 'spec/fractor/worker_timeout_spec.rb'
     - 'spec/fractor/workflow/execution_strategy_spec.rb'
 
@@ -265,17 +301,19 @@ RSpec/MessageSpies:
     - 'spec/fractor/main_loop_handler_spec.rb'
     - 'spec/fractor/shutdown_handler_spec.rb'
 
-# Offense count: 6
+# Offense count: 8
 RSpec/MultipleDescribes:
   Exclude:
     - 'spec/examples/workflow/simplified_workflow_spec.rb'
+    - 'spec/fractor/persistent_work_queue_spec.rb'
+    - 'spec/fractor/work_timeout_spec.rb'
     - 'spec/fractor/worker_timeout_spec.rb'
     - 'spec/fractor/workflow/dead_letter_queue_spec.rb'
     - 'spec/fractor/workflow/execution_strategy_spec.rb'
     - 'spec/fractor/workflow/retry_config_spec.rb'
     - 'spec/fractor/workflow/retry_strategy_spec.rb'
 
-# Offense count: 605
+# Offense count: 635
 RSpec/MultipleExpectations:
   Max: 12
 
@@ -321,9 +359,29 @@ Security/Eval:
   Exclude:
     - 'lib/fractor/cli.rb'
 
+# Offense count: 1
+Security/MarshalLoad:
+  Exclude:
+    - 'lib/fractor/queue_persister.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+Style/MultilineIfModifier:
+  Exclude:
+    - 'lib/fractor/queue_persister.rb'
+    - 'lib/fractor/result_cache.rb'
+
 # Offense count: 1
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: respond_to_missing?
 Style/OptionalBooleanParameter:
   Exclude:
     - 'lib/fractor/workflow/job.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleForMultiline.
+# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
+Style/TrailingCommaInArguments:
+  Exclude:
+    - 'spec/examples/workflow/retry_workflow_spec.rb'

data/README.adoc

@@ -82,6 +82,143 @@ puts "Results: #{supervisor.results.results.map(&:result)}"
 # => Results: [2, 4, 6]
 ----
 
+=== Timeout Configuration
+
+Fractor supports flexible timeout configuration at three levels:
+
+[cols="1,2,4"]
+|===
+|Level |Syntax |Description
+
+|Global
+|`Fractor.configure`
+|Sets default timeout for all workers
+
+|Worker
+|`Worker.timeout` class method
+|Sets timeout for all work processed by a worker
+
+|Work item
+|`Work.new(input, timeout: N)`
+|Overrides worker timeout for specific work item
+|===
+
+[source,ruby]
+----
+# 1. Global default (optional)
+Fractor.configure do |config|
+  config.default_worker_timeout = 60  # 60 seconds
+end
+
+# 2. Worker-level timeout
+class FastWorker < Fractor::Worker
+  timeout 10  # 10 second timeout for this worker
+
+  def process(work)
+    Fractor::WorkResult.new(result: work.input * 2, work: work)
+  end
+end
+
+# 3. Per-work-item timeout (overrides worker timeout)
+class MyWork < Fractor::Work
+  def initialize(value, timeout: nil)
+    super({ value: value }, timeout: timeout)
+  end
+end
+
+supervisor = Fractor::Supervisor.new(
+  worker_pools: [{ worker_class: FastWorker }]
+)
+
+# Mix work items with different timeouts
+fast_work = MyWork.new(1, timeout: 5)      # 5 seconds
+normal_work = MyWork.new(2)                 # uses worker's 10s timeout
+slow_work = MyWork.new(3, timeout: 30)     # 30 seconds
+
+supervisor.add_work_items([fast_work, normal_work, slow_work])
+supervisor.run
+----
+
+When a timeout occurs, the work item is marked as failed with `error_category: :timeout` and can be retried if using the workflow system.
+
+=== Queue Persistence
+
+For critical applications, work queues can be persisted to disk for crash recovery:
+
+[source,ruby]
+----
+# Create a persistent queue with automatic saving
+queue = Fractor::PersistentWorkQueue.new("data/queue.json")
+
+# Add work items - automatically saved
+queue << MyWork.new(data1)
+queue << MyWork.new(data2)
+
+# Use with ContinuousServer for crash recovery
+server = Fractor::ContinuousServer.new(
+  worker_pools: [{ worker_class: MyWorker }],
+  work_queue: queue
+)
+
+# Load any previous work items on startup
+queue.load
+
+server.run
+----
+
+Supported persistence formats:
+* **JSON** (default) - Human-readable, widely compatible
+* **YAML** - More readable than JSON
+* **Marshal** - Binary format, faster but Ruby-specific
+
+=== Result Caching
+
+For expensive, deterministic operations, Fractor provides a result cache to avoid redundant processing of identical work items:
+
+[source,ruby]
+----
+# Create a cache with TTL (time-to-live)
+cache = Fractor::ResultCache.new(ttl: 300)  # 5 minutes
+
+# Or with size limit
+cache = Fractor::ResultCache.new(max_size: 1000)
+
+# Or with memory limit
+cache = Fractor::ResultCache.new(max_memory: 1024 * 1024)  # 1MB
+
+# Use the cache
+result = cache.get(work) do
+  # This block only runs if work is not cached
+  expensive_operation(work)
+end
+
+# Check if work is cached
+if cache.has?(work)
+  puts "Result is cached!"
+end
+
+# Manual cache operations
+cache.set(work, result)           # Store a result
+cache.invalidate(work)            # Remove a cached result
+cache.clear                       # Remove all cached results
+
+# Get cache statistics
+stats = cache.stats
+puts "Cache hit rate: #{stats[:hit_rate]}%"
+----
+
+The cache generates consistent keys based on:
+* Work class name
+* Work input data
+* Work timeout (if set)
+
+This means identical work items with the same input and timeout will share cached results.
+
+Cache eviction policies:
+* **TTL** - Entries expire after a configured time
+* **LRU** - Least-recently-used entries are evicted when max_size is reached
+* **Memory-based** - Entries are evicted when max_memory is reached
+
 == Key features
 
 * *Function-driven*: Define processing logic by subclassing `Fractor::Worker`

data/lib/fractor/persistent_work_queue.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require_relative "work_queue"
+require_relative "queue_persister"
+require "json"
+
+module Fractor
+  # A work queue with persistence support.
+  # Automatically saves queue state to disk for crash recovery.
+  #
+  # @example Basic usage
+  #   queue = PersistentWorkQueue.new("data/queue.json")
+  #   queue << work_item  # Automatically saved
+  #
+  # @example With custom persister
+  #   persister = QueuePersister::YAMLPersister.new("data/queue.yml")
+  #   queue = PersistentWorkQueue.new(persister: persister)
+  class PersistentWorkQueue < WorkQueue
+    attr_reader :persister
+
+    # Initialize a persistent work queue.
+    #
+    # @param path_or_persister [String, QueuePersister::Base] File path or persister instance
+    # @param auto_save [Boolean] Automatically save after each enqueue
+    # @param save_interval [Integer, nil] Seconds between auto-saves (nil = disabled)
+    def initialize(path_or_persister = nil, auto_save: true, save_interval: nil)
+      super()
+
+      @persister = case path_or_persister
+                   when String
+                     QueuePersister::JSONPersister.new(path_or_persister)
+                   when QueuePersister::Base, nil
+                     path_or_persister
+                   else
+                     raise ArgumentError,
+                           "path_or_persister must be a String or QueuePersister::Base"
+                   end
+
+      @auto_save = @persister ? auto_save : false
+      @save_interval = save_interval
+      @dirty = false
+      @save_thread = nil
+
+      # Start auto-save thread if interval is specified
+      start_save_thread if @save_interval
+    end
+
+    # Add a work item to the queue with automatic persistence.
+    #
+    # @param work_item [Fractor::Work] The work item to add
+    # @return [void]
+    def enqueue(work_item)
+      super
+      @dirty = true
+      save if @auto_save
+    end
+
+    # Alias for enqueue
+    #
+    # @param work_item [Fractor::Work] The work item to add
+    # @return [void]
+    def <<(work_item)
+      enqueue(work_item)
+    end
+
+    # Retrieve multiple work items from the queue.
+    # Marks queue as dirty for persistence.
+    #
+    # @param max_items [Integer] Maximum number of items to retrieve
+    # @return [Array<Fractor::Work>] Array of work items
+    def dequeue_batch(max_items = 10)
+      items = super
+      @dirty = true if items.any?
+      items
+    end
+
+    # Save the current queue state to disk.
+    #
+    # @return [Boolean] true if saved successfully
+    def save
+      return false unless @persister
+
+      # Get all items from the queue without removing them
+      items = peek_all
+      @persister.save(items)
+      @dirty = false
+      true
+    rescue StandardError => e
+      warn "Failed to save queue: #{e.message}"
+      false
+    end
+
+    # Load queue state from disk, restoring previous work items.
+    #
+    # @return [Integer] Number of items restored
+    def load
+      return 0 unless @persister
+
+      items = @persister.load
+      return 0 unless items
+
+      count = 0
+      items.each do |item|
+        # Convert hash back to Work object if needed
+        work = if item.is_a?(Hash)
+                 deserialize_work(item)
+               else
+                 item
+               end
+
+        @queue << work if work.is_a?(Fractor::Work)
+        count += 1
+      end
+
+      @dirty = false
+      count
+    rescue StandardError => e
+      warn "Failed to load queue: #{e.message}"
+      0
+    end
+
+    # Clear the queue and remove persisted data.
+    #
+    # @return [Boolean] true if cleared successfully
+    def clear
+      @queue.clear
+      @persister&.clear
+      @dirty = false
+      true
+    rescue StandardError => e
+      warn "Failed to clear queue: #{e.message}"
+      false
+    end
+
+    # Check if the queue has unsaved changes.
+    #
+    # @return [Boolean] true if there are unsaved changes
+    def dirty?
+      @dirty
+    end
+
+    # Save and close the queue, cleaning up resources.
+    #
+    # @return [void]
+    def close
+      save if @dirty
+      stop_save_thread if @save_thread
+    end
+
+    private
+
+    # Peek at all items in the queue without removing them.
+    #
+    # @return [Array<Fractor::Work>] All work items in the queue
+    def peek_all
+      items = []
+      # Thread::Queue doesn't have a peek method, so we need to
+      # temporarily remove items, collect them, and put them back
+      temp = []
+      until @queue.empty?
+        item = @queue.pop(true)
+        temp << item
+        items << item
+      end
+      # Put items back
+      temp.each { |item| @queue << item }
+      items
+    rescue ThreadError
+      # Queue became empty during iteration
+      items
+    end
+
+    # Deserialize a work item from a hash.
+    #
+    # @param hash [Hash] The serialized work item
+    # @return [Fractor::Work, nil] The deserialized work item
+    def deserialize_work(hash)
+      return nil unless hash.is_a?(Hash)
+
+      # Extract class name and data (handle both string and symbol keys for JSON compatibility)
+      hash.delete(:_class) || hash.delete("_class")
+      input_data = hash.delete(:_input) || hash.delete("_input")
+      timeout = hash.delete(:_timeout) || hash.delete("_timeout")
+
+      # For simplicity, always use the base Work class with stored input
+      # This ensures correct deserialization without complex reflection
+      if timeout
+        Fractor::Work.new(input_data, timeout: timeout)
+      else
+        Fractor::Work.new(input_data)
+      end
+    rescue StandardError => e
+      warn "Failed to deserialize work item: #{e.message}"
+      nil
+    end
+
+    # Start the auto-save thread.
+    #
+    # @return [void]
+    def start_save_thread
+      @save_thread = Thread.new do
+        loop do
+          sleep @save_interval
+          save if @dirty
+        end
+      end
+      @save_thread.name = "PersistentWorkQueue-auto-save" if @save_thread.respond_to?(:name=)
+    end
+
+    # Stop the auto-save thread.
+    #
+    # @return [void]
+    def stop_save_thread
+      @save_thread&.kill
+      @save_thread = nil
+    end
+  end
+end

data/lib/fractor/queue_persister.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+
+module Fractor
+  # Persistence strategies for work queues.
+  # Provides different backends for saving and loading queue state.
+  module QueuePersister
+    # Base class for queue persisters.
+    #
+    # @abstract Subclasses must implement {#save} and {#load}
+    class Base
+      # Save work items to persistent storage.
+      #
+      # @abstract
+      # @param items [Array<Fractor::Work>] Work items to save
+      # @return [Boolean] true if saved successfully
+      def save(_items)
+        raise NotImplementedError, "Subclasses must implement #save"
+      end
+
+      # Load work items from persistent storage.
+      #
+      # @abstract
+      # @return [Array<Hash>, nil] Serialized work items, or nil if no data
+      def load
+        raise NotImplementedError, "Subclasses must implement #load"
+      end
+
+      # Clear persisted data.
+      #
+      # @abstract
+      # @return [Boolean] true if cleared successfully
+      def clear
+        raise NotImplementedError, "Subclasses must implement #clear"
+      end
+
+      protected
+
+      # Serialize a work item to a hash.
+      #
+      # @param work [Fractor::Work] The work item to serialize
+      # @return [Hash] Serialized work item
+      def serialize_work(work)
+        hash = {
+          _class: work.class.name,
+          _input: work.input,
+        }
+        if work.respond_to?(:timeout) && !work.timeout.nil?
+          hash[:_timeout] =
+            work.timeout
+        end
+        hash
+      end
+    end
+
+    # JSON file persister.
+    # Stores queue state as a JSON array.
+    class JSONPersister < Base
+      # Initialize a JSON persister.
+      #
+      # @param path [String] Path to the JSON file
+      # @param pretty [Boolean] Format JSON with indentation
+      def initialize(path, pretty: true)
+        @path = path
+        @pretty = pretty
+      end
+
+      # Save work items to JSON file.
+      #
+      # @param items [Array<Fractor::Work>] Work items to save
+      # @return [Boolean] true if saved successfully
+      def save(items)
+        ensure_directory_exists
+
+        serialized = items.map { |work| serialize_work(work) }
+        json = @pretty ? JSON.pretty_generate(serialized) : JSON.generate(serialized)
+
+        File.write(@path, json)
+        true
+      rescue StandardError => e
+        warn "Failed to save to #{@path}: #{e.message}"
+        false
+      end
+
+      # Load work items from JSON file.
+      #
+      # @return [Array<Hash>, nil] Serialized work items, or nil if file doesn't exist
+      def load
+        return nil unless File.exist?(@path)
+
+        json = File.read(@path)
+        return nil if json.strip.empty?
+
+        JSON.parse(json)
+      rescue StandardError => e
+        warn "Failed to load from #{@path}: #{e.message}"
+        nil
+      end
+
+      # Clear the JSON file.
+      #
+      # @return [Boolean] true if cleared successfully
+      def clear
+        File.delete(@path) if File.exist?(@path)
+        true
+      rescue StandardError => e
+        warn "Failed to clear #{@path}: #{e.message}"
+        false
+      end
+
+      private
+
+      # Ensure the directory for the file exists.
+      #
+      # @return [void]
+      def ensure_directory_exists
+        dir = File.dirname(@path)
+        FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
+      end
+    end
+
+    # YAML file persister.
+    # Stores queue state as a YAML document.
+    class YAMLPersister < Base
+      # Initialize a YAML persister.
+      #
+      # @param path [String] Path to the YAML file
+      def initialize(path)
+        @path = path
+      end
+
+      # Save work items to YAML file.
+      #
+      # @param items [Array<Fractor::Work>] Work items to save
+      # @return [Boolean] true if saved successfully
+      def save(items)
+        ensure_directory_exists
+
+        serialized = items.map { |work| serialize_work(work) }
+        yaml = YAML.dump(serialized)
+
+        File.write(@path, yaml)
+        true
+      rescue StandardError => e
+        warn "Failed to save to #{@path}: #{e.message}"
+        false
+      end
+
+      # Load work items from YAML file.
+      #
+      # @return [Array<Hash>, nil] Serialized work items, or nil if file doesn't exist
+      def load
+        return nil unless File.exist?(@path)
+
+        yaml = File.read(@path)
+        return nil if yaml.strip.empty?
+
+        YAML.safe_load(yaml,
+                       permitted_classes: [Symbol, Hash, String, Integer, Float, TrueClass,
+                                           FalseClass, NilClass])
+      rescue StandardError => e
+        warn "Failed to load from #{@path}: #{e.message}"
+        nil
+      end
+
+      # Clear the YAML file.
+      #
+      # @return [Boolean] true if cleared successfully
+      def clear
+        File.delete(@path) if File.exist?(@path)
+        true
+      rescue StandardError => e
+        warn "Failed to clear #{@path}: #{e.message}"
+        false
+      end
+
+      private
+
+      # Ensure the directory for the file exists.
+      #
+      # @return [void]
+      def ensure_directory_exists
+        dir = File.dirname(@path)
+        FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
+      end
+    end
+
+    # Marshal file persister.
+    # Uses Ruby's Marshal for binary serialization.
+    # Note: Marshal is not secure and should not be used with untrusted data.
+    class MarshalPersister < Base
+      # Initialize a Marshal persister.
+      #
+      # @param path [String] Path to the Marshal file
+      def initialize(path)
+        @path = path
+      end
+
+      # Save work items using Marshal.
+      #
+      # @param items [Array<Fractor::Work>] Work items to save
+      # @return [Boolean] true if saved successfully
+      def save(items)
+        ensure_directory_exists
+
+        serialized = items.map { |work| serialize_work(work) }
+        data = Marshal.dump(serialized)
+
+        File.binwrite(@path, data)
+        true
+      rescue StandardError => e
+        warn "Failed to save to #{@path}: #{e.message}"
+        false
+      end
+
+      # Load work items using Marshal.
+      #
+      # @return [Array<Hash>, nil] Serialized work items, or nil if file doesn't exist
+      def load
+        return nil unless File.exist?(@path)
+
+        data = File.binread(@path)
+        Marshal.load(data)
+      rescue StandardError => e
+        warn "Failed to load from #{@path}: #{e.message}"
+        nil
+      end
+
+      # Clear the Marshal file.
+      #
+      # @return [Boolean] true if cleared successfully
+      def clear
+        File.delete(@path) if File.exist?(@path)
+        true
+      rescue StandardError => e
+        warn "Failed to clear #{@path}: #{e.message}"
+        false
+      end
+
+      private
+
+      # Ensure the directory for the file exists.
+      #
+      # @return [void]
+      def ensure_directory_exists
+        dir = File.dirname(@path)
+        FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
+      end
+    end
+  end
+end

data/lib/fractor/result_cache.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Fractor
+  # Caches work results to avoid redundant processing of identical work items.
+  # Useful for expensive, deterministic operations.
+  #
+  # @example Basic usage
+  #   cache = Fractor::ResultCache.new
+  #   cached = cache.get(work) { work.process }
+  #
+  # @example With TTL
+  #   cache = Fractor::ResultCache.new(ttl: 300)  # 5 minutes
+  class ResultCache
+    attr_reader :hits, :misses
+
+    # Initialize a new result cache.
+    #
+    # @param ttl [Integer, nil] Time-to-live for cache entries in seconds (nil = no expiration)
+    # @param max_size [Integer, nil] Maximum number of entries (nil = unlimited)
+    # @param max_memory [Integer, nil] Maximum memory usage in bytes (nil = unlimited)
+    def initialize(ttl: nil, max_size: nil, max_memory: nil)
+      @cache = {}
+      @timestamps = {}
+      @access_times = {}
+      @ttl = ttl
+      @max_size = max_size
+      @max_memory = max_memory
+      @current_memory = 0
+      @mutex = Mutex.new
+      @hits = 0
+      @misses = 0
+    end
+
+    # Get the current cache size.
+    #
+    # @return [Integer] Number of entries in the cache
+    def size
+      @mutex.synchronize { @cache.size }
+    end
+
+    # Get a cached result or compute and cache it.
+    #
+    # @param work [Fractor::Work] The work item to process
+    # @yield Block to compute the result if not cached
+    # @return [WorkResult, Object] The cached or computed result
+    def get(work)
+      key = generate_key(work)
+
+      @mutex.synchronize do
+        # Check if we have a valid cached result
+        if @cache.key?(key) && !expired?(key)
+          @hits += 1
+          @access_times[key] = Time.now
+          return @cache[key]
+        end
+
+        @misses += 1
+
+        # Compute the result
+        result = yield
+
+        # Cache the result
+        cache_entry(key, result)
+
+        result
+      end
+    end
+
+    # Check if a work item has a cached result.
+    #
+    # @param work [Fractor::Work] The work item to check
+    # @return [Boolean] true if a valid cached result exists
+    def has?(work)
+      key = generate_key(work)
+
+      @mutex.synchronize do
+        @cache.key?(key) && !expired?(key)
+      end
+    end
+
+    # Store a result in the cache.
+    #
+    # @param work [Fractor::Work] The work item
+    # @param result [WorkResult, Object] The result to cache
+    # @return [void]
+    def set(work, result)
+      key = generate_key(work)
+
+      @mutex.synchronize do
+        cache_entry(key, result)
+      end
+    end
+
+    # Invalidate a cached result.
+    #
+    # @param work [Fractor::Work] The work item to invalidate
+    # @return [Boolean] true if a cached result was removed
+    def invalidate(work)
+      key = generate_key(work)
+
+      @mutex.synchronize do
+        if @cache.key?(key)
+          remove_entry(key)
+          true
+        else
+          false
+        end
+      end
+    end
+
+    # Clear all cached results.
+    #
+    # @return [void]
+    def clear
+      @mutex.synchronize do
+        @cache.clear
+        @timestamps.clear
+        @access_times.clear
+        @current_memory = 0
+      end
+    end
+
+    # Get cache statistics.
+    #
+    # @return [Hash] Cache statistics
+    def stats
+      @mutex.synchronize do
+        total = @hits + @misses
+        hit_rate = total.positive? ? (@hits.to_f / total * 100).round(2) : 0
+
+        {
+          size: @cache.size,
+          hits: @hits,
+          misses: @misses,
+          hit_rate: hit_rate,
+          current_memory: @current_memory,
+        }
+      end
+    end
+
+    # Remove expired entries from the cache.
+    #
+    # @return [Integer] Number of entries removed
+    def cleanup_expired
+      @mutex.synchronize do
+        expired_keys = @cache.keys.select { |key| expired?(key) }
+        expired_keys.each { |key| remove_entry(key) }
+        expired_keys.size
+      end
+    end
+
+    private
+
+    # Generate a cache key for a work item.
+    #
+    # @param work [Fractor::Work] The work item
+    # @return [String] The cache key
+    def generate_key(work)
+      # Create a deterministic key from the work item
+      data = {
+        class: work.class.name,
+        input: work.input,
+      }
+      if work.respond_to?(:timeout) && !work.timeout.nil?
+        data[:timeout] =
+          work.timeout
+      end
+
+      # Use SHA256 hash for consistent, collision-resistant keys
+      Digest::SHA256.hexdigest(JSON.dump(data))
+    end
+
+    # Check if a cache entry is expired.
+    #
+    # @param key [String] The cache key
+    # @return [Boolean] true if the entry is expired
+    def expired?(key)
+      return false unless @ttl
+
+      timestamp = @timestamps[key]
+      return true unless timestamp
+
+      Time.now - timestamp > @ttl
+    end
+
+    # Cache a result entry.
+    #
+    # @param key [String] The cache key
+    # @param result [Object] The result to cache
+    # @return [void]
+    def cache_entry(key, result)
+      # Evict oldest entry if max_size reached
+      evict_lru if @max_size && @cache.size >= @max_size
+
+      # Estimate memory usage
+      estimated_size = estimate_size(result)
+
+      # Evict entries if max_memory reached
+      evict_by_memory(estimated_size) if @max_memory
+
+      @cache[key] = result
+      @timestamps[key] = Time.now
+      @access_times[key] = Time.now
+      @current_memory += estimated_size
+    end
+
+    # Remove an entry from the cache.
+    #
+    # @param key [String] The cache key
+    # @return [void]
+    def remove_entry(key)
+      result = @cache.delete(key)
+      @timestamps.delete(key)
+      @access_times.delete(key)
+
+      if result
+        @current_memory -= estimate_size(result)
+        @current_memory = 0 if @current_memory.negative?
+      end
+    end
+
+    # Evict the least-recently-used entry.
+    #
+    # @return [void]
+    def evict_lru
+      return if @cache.empty?
+
+      # Find the entry with the oldest access time
+      lru_key = @access_times.min_by { |_, time| time }&.first
+      remove_entry(lru_key) if lru_key
+    end
+
+    # Evict entries to free memory.
+    #
+    # @param required_size [Integer] The size needed
+    # @return [void]
+    def evict_by_memory(required_size)
+      return unless @max_memory
+
+      while @current_memory + required_size > @max_memory && @cache.any?
+        evict_lru
+      end
+    end
+
+    # Estimate the memory size of an object.
+    #
+    # @param obj [Object] The object to measure
+    # @return [Integer] Estimated size in bytes
+    def estimate_size(obj)
+      # Rough estimation based on object inspection
+      case obj
+      when String
+        obj.bytesize
+      when Hash
+        obj.sum { |k, v| estimate_size(k.to_s) + estimate_size(v) }
+      when Array
+        obj.sum { |v| estimate_size(v) }
+      when Fractor::WorkResult
+        # Base size + result + error
+        size = 100 # Base object overhead
+        size += estimate_size(obj.result) if obj.result
+        size += estimate_size(obj.error) if obj.error
+        size
+      else
+        100 # Default estimate for unknown objects
+      end
+    rescue StandardError
+      100 # Fallback estimate
+    end
+  end
+end

data/lib/fractor/supervisor.rb

@@ -318,7 +318,7 @@ module Fractor
       # This is critical for Ruby 4.0 where workers need explicit work distribution
       if @work_distribution_manager
         distributed = @work_distribution_manager.distribute_to_idle_workers
-        puts "Distributed initial work to #{distributed} idle workers (work_queue.size: #{@work_queue.size})" if @debug || true
+        puts "Distributed initial work to #{distributed} idle workers (work_queue.size: #{@work_queue.size})" if @debug
       end
 
       # Start timer thread for continuous mode to periodically check work sources

data/lib/fractor/version.rb

@@ -2,5 +2,5 @@
 
 module Fractor
   # Fractor version
-  VERSION = "0.1.7"
+  VERSION = "0.1.9"
 end

data/lib/fractor/work.rb

@@ -4,10 +4,16 @@ module Fractor
   # Base class for defining work items.
   # Contains the input data for a worker.
   class Work
-    attr_reader :input
+    attr_reader :input, :timeout
 
-    def initialize(input)
+    # Initializes a new work item.
+    #
+    # @param input [Object] The input data for the worker
+    # @param timeout [Numeric, nil] Optional per-work-item timeout in seconds.
+    #   If nil, uses the worker's default timeout.
+    def initialize(input, timeout: nil)
       @input = input
+      @timeout = timeout
     end
 
     def to_s
@@ -23,6 +29,7 @@ module Fractor
         "@input=#{@input.inspect}",
         "@type=#{input.class.name}",
       ]
+      details << "@timeout=#{@timeout.inspect}" if @timeout
       details.join(" ")
     end
   end

data/lib/fractor/wrapped_ractor3.rb

@@ -63,21 +63,26 @@ module Fractor
           RactorLogger.debug("Received work #{work.inspect}", ractor_name: name)
 
           begin
-            # Get the timeout for this worker (nil means no timeout)
-            worker_timeout = worker.timeout
+            # Get the timeout for this specific work item
+            # Priority: work.timeout > worker.timeout (nil means no timeout)
+            work_timeout = if work.respond_to?(:timeout) && !work.timeout.nil?
+                             work.timeout
+                           else
+                             worker.timeout
+                           end
 
             # Process the work with timeout if configured
             # Note: Ruby's Timeout.timeout uses threads which don't work with Ractors.
             # We measure execution time and raise timeout error afterward if exceeded.
-            result = if worker_timeout
+            result = if work_timeout
                        start_time = Time.now
                        process_result = worker.process(work)
                        elapsed = Time.now - start_time
-                       if elapsed > worker_timeout
+                       if elapsed > work_timeout
                          # Raise a timeout error after the fact
                          # Note: This is a post-facto timeout check - the work has already completed
                          raise Timeout::Error,
-                               "execution timed out after #{elapsed}s (limit: #{worker_timeout}s)"
+                               "execution timed out after #{elapsed}s (limit: #{work_timeout}s)"
                        end
 
                        process_result
@@ -99,7 +104,7 @@ module Fractor
           rescue Timeout::Error => e
             # Handle timeout errors as retriable errors
             RactorLogger.warn(
-              "Timed out after #{worker.timeout}s processing work #{work.inspect}", ractor_name: name
+              "Timed out after #{work_timeout}s processing work #{work.inspect}", ractor_name: name
             )
             error_result = Fractor::WorkResult.new(
               error: "Worker timeout: #{e.message}",

data/lib/fractor/wrapped_ractor4.rb

@@ -89,21 +89,26 @@ module Fractor
           end
 
           begin
-            # Get the timeout for this worker (nil means no timeout)
-            worker_timeout = worker.timeout
+            # Get the timeout for this specific work item
+            # Priority: work.timeout > worker.timeout (nil means no timeout)
+            work_timeout = if work.respond_to?(:timeout) && !work.timeout.nil?
+                             work.timeout
+                           else
+                             worker.timeout
+                           end
 
             # Process the work with timeout if configured
             # Note: Ruby's Timeout.timeout uses threads which don't work with Ractors.
             # We measure execution time and raise timeout error afterward if exceeded.
-            result = if worker_timeout
+            result = if work_timeout
                        start_time = Time.now
                        process_result = worker.process(work)
                        elapsed = Time.now - start_time
-                       if elapsed > worker_timeout
+                       if elapsed > work_timeout
                          # Raise a timeout error after the fact
                          # Note: This is a post-facto timeout check - the work has already completed
                          raise Timeout::Error,
-                               "execution timed out after #{elapsed}s (limit: #{worker_timeout}s)"
+                               "execution timed out after #{elapsed}s (limit: #{work_timeout}s)"
                        end
 
                        process_result
@@ -132,7 +137,7 @@ module Fractor
           rescue Timeout::Error => e
             # Handle timeout errors as retriable errors
             RactorLogger.warn(
-              "Timed out after #{worker.timeout}s processing work #{work.inspect}", ractor_name: name
+              "Timed out after #{work_timeout}s processing work #{work.inspect}", ractor_name: name
             )
             error_result = Fractor::WorkResult.new(
               error: "Worker timeout: #{e.message}",

data/lib/fractor.rb

@@ -7,6 +7,8 @@ require_relative "fractor/logger"
 require_relative "fractor/work"
 require_relative "fractor/work_result"
 require_relative "fractor/work_queue"
+require_relative "fractor/queue_persister"
+require_relative "fractor/persistent_work_queue"
 require_relative "fractor/priority_work"
 require_relative "fractor/priority_work_queue"
 require_relative "fractor/wrapped_ractor"
@@ -32,6 +34,7 @@ require_relative "fractor/error_statistics"
 require_relative "fractor/error_report_generator"
 require_relative "fractor/error_formatter"
 require_relative "fractor/execution_tracer"
+require_relative "fractor/result_cache"
 
 # Optional: CLI (only load if Thor is available)
 begin

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fractor
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.9
 platform: ruby
 authors:
 - Ronald Tse
@@ -194,9 +194,12 @@ files:
 - lib/fractor/performance_metrics_collector.rb
 - lib/fractor/performance_monitor.rb
 - lib/fractor/performance_report_generator.rb
+- lib/fractor/persistent_work_queue.rb
 - lib/fractor/priority_work.rb
 - lib/fractor/priority_work_queue.rb
+- lib/fractor/queue_persister.rb
 - lib/fractor/result_aggregator.rb
+- lib/fractor/result_cache.rb
 - lib/fractor/shutdown_handler.rb
 - lib/fractor/signal_handler.rb
 - lib/fractor/supervisor.rb