fractor 0.1.3 → 0.1.6

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/continuous_chat_common/message_protocol.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module ContinuousChat
+  # Message packet class for handling protocol messages
+  class MessagePacket
+    attr_reader :type, :data, :timestamp
+
+    def initialize(type, data, timestamp = Time.now.to_i)
+      @type = type.to_sym
+      @data = data
+      @timestamp = timestamp
+    end
+
+    # Convert to JSON string
+    def to_json(*_args)
+      {
+        type: @type,
+        data: @data,
+        timestamp: @timestamp,
+      }.to_json
+    end
+
+    # String representation
+    def to_s
+      to_json
+    end
+  end
+
+  # Helper module for message protocol
+  module MessageProtocol
+    # Create a packet of the given type with data
+    def self.create_packet(type, data)
+      MessagePacket.new(type, data).to_json
+    end
+
+    # Parse a JSON string into a message packet
+    def self.parse_packet(json_string)
+      data = JSON.parse(json_string)
+      type = data["type"]&.to_sym
+      content = data["data"]
+      timestamp = data["timestamp"] || Time.now.to_i
+
+      MessagePacket.new(type, content, timestamp)
+    rescue JSON::ParserError => e
+      puts "Error parsing message: #{e.message}"
+      nil
+    end
+  end
+end

data/examples/continuous_chat_fractor/README.adoc

@@ -0,0 +1,217 @@
+= Continuous Chat Server Example (Fractor-based)
+
+== Overview
+
+This example demonstrates Fractor's continuous mode feature with a chat server implementation. Unlike the plain socket implementation in `examples/continuous_chat_server/`, this version uses Fractor's Worker and Supervisor classes to process chat messages concurrently.
+
+The example shows how to:
+
+* Use Fractor in continuous mode (`continuous_mode: true`)
+* Register work source callbacks with `register_work_source`
+* Process messages asynchronously using Ractor-based workers
+* Coordinate between main thread socket handling and Fractor workers
+* Implement graceful shutdown
+
+== Key Concepts
+
+* *Continuous Mode*: The Fractor supervisor runs indefinitely, processing work as it arrives
+* *Work Sources*: Callback functions that provide new work items to the supervisor on demand
+* *Asynchronous Processing*: ChatWorker processes messages concurrently in Ractors
+* *Thread Coordination*: Multiple threads working together - main thread handles I/O, Fractor workers process messages
+* *Message Logging*: All message processing is logged to demonstrate Fractor's work distribution
+
+== Architecture
+
+=== Fractor Components
+
+The server uses the following Fractor components:
+
+1. *ChatMessage (Fractor::Work)*: Represents a chat message as a unit of work
+   - Encapsulates the message packet and optional client socket reference
+   - Each message becomes a work item in the Fractor queue
+
+2. *ChatWorker (Fractor::Worker)*: Processes chat messages
+   - Runs in a Ractor for parallel processing
+   - Handles different message types (broadcast, direct_message, server_message, user_list)
+   - Returns WorkResult with processing outcome
+
+3. *Supervisor*: Orchestrates the workers
+   - Configured with `continuous_mode: true` to run indefinitely
+   - Uses 2 worker Ractors (auto-detected from system processors)
+   - Registered work source pulls from a thread-safe Queue
+
+=== Thread Architecture
+
+The server uses three concurrent components:
+
+1. *Main Thread*: Handles socket I/O with `IO.select`
+   - Accepts new client connections
+   - Reads messages from client sockets
+   - Sends responses back to clients
+   - Puts received messages into the work queue
+
+2. *Supervisor Thread*: Runs the Fractor supervisor
+   - Continuously pulls work from the queue via the work source callback
+   - Distributes work to available ChatWorker Ractors
+   - Collects results in the ResultAggregator
+
+3. *Results Thread*: Processes completed work
+   - Monitors the ResultAggregator for new results
+   - Logs processing outcomes
+   - Handles errors from workers
+
+== Example Components
+
+1. *chat_common.rb*: Shared code with Fractor classes
+   * `MessagePacket` class for message protocol
+   * `MessageProtocol` module for serialization
+   * `ChatMessage` class extending `Fractor::Work`
+   * `ChatWorker` class extending `Fractor::Worker`
+
+2. *chat_server.rb*: Fractor-based chat server
+   * Socket handling in main thread
+   * Fractor supervisor in continuous mode
+   * Work source callback pulling from Queue
+   * Results processing thread
+
+3. *chat_client.rb*: Simple chat client (reused from plain example)
+   * Connects to server via TCP socket
+   * Sends and receives JSON messages
+
+4. *simulate.rb*: Automated simulation
+   * Creates server and multiple clients as processes
+   * Runs predefined message schedule
+   * Analyzes logs after completion
+
+== Running the Example
+
+=== Running the Simulation
+
+To run the complete automated simulation:
+
+[source,sh]
+----
+ruby examples/continuous_chat_fractor/simulate.rb
+----
+
+Optional parameters:
+* `-p, --port PORT` - Specify server port (default: 3000)
+* `-d, --duration SECONDS` - Duration of simulation in seconds (default: 10)
+* `-l, --log-dir DIR` - Directory for log files (default: logs)
+* `-h, --help` - Show help message
+
+=== Running Server and Clients Separately
+
+Run the server in one terminal:
+
+[source,sh]
+----
+ruby examples/continuous_chat_fractor/chat_server.rb [PORT] [LOG_FILE]
+----
+
+Run clients in different terminals:
+
+[source,sh]
+----
+ruby examples/continuous_chat_fractor/chat_client.rb [USERNAME] [PORT] [LOG_FILE]
+----
+
+== Features Demonstrated
+
+* *Continuous Mode*: Supervisor runs indefinitely without stopping
+* *Work Source Callback*: Dynamically provides work from a Queue
+* *Concurrent Processing*: Multiple Ractor workers process messages in parallel
+* *Thread Coordination*: Main thread, supervisor thread, and results thread work together
+* *Message Logging*: All operations logged to files for verification
+* *Graceful Shutdown*: Proper cleanup of Fractor supervisor and sockets
+
+== Comparison with Plain Socket Implementation
+
+The plain socket implementation (`examples/continuous_chat_server/`) uses:
+- `IO.select` for non-blocking I/O
+- Sequential message processing in the main thread
+- Simple, straightforward architecture
+
+The Fractor-based implementation demonstrates:
+- Parallel message processing using Ractors
+- Work queue pattern with work source callbacks
+- Separation of concerns (I/O vs processing)
+- Continuous mode supervisor pattern
+
+Both implementations are functional. The Fractor version shows how to structure a long-running server using Fractor's continuous mode, which is useful for:
+- CPU-intensive message processing
+- Scaling message handling across cores
+- Separating I/O from computation
+- Learning Fractor's continuous mode patterns
+
+== Expected Output
+
+The simulation will show:
+* Fractor supervisor starting with workers
+* Clients connecting to the server
+* Messages being sent between clients
+* Messages being added to Fractor work queue (logged as "Received from...")
+* Graceful shutdown of all components
+
+NOTE: In this implementation, Fractor workers process messages in parallel for demonstration purposes (analyzing message types, logging processing), while the main thread handles actual message delivery to ensure real-time responsiveness. The work items are successfully queued and processed by workers - you can verify this by seeing that all messages are correctly broadcast/delivered to clients.
+
+== Log Files
+
+After running the simulation, check the `logs/` directory:
+
+* `server_messages.log` - Server activity and Fractor processing
+* `client_<username>_messages.log` - Client activity
+* `client_<username>_send_messages.json` - Messages sent by client
+
+== Implementation Notes
+
+=== Why Thread-safe Queue?
+
+The implementation uses Ruby's `Queue` class (thread-safe) to coordinate between:
+- Main thread (producing work from socket I/O)
+- Supervisor thread (consuming work via work source callback)
+
+This is necessary because Ractors cannot directly share mutable objects with threads.
+
+=== Work Source Callback
+
+The work source callback pulls up to 5 messages from the queue at once:
+
+[source,ruby]
+----
+supervisor.register_work_source do
+  messages = []
+  5.times do
+    break if message_queue.empty?
+    msg = message_queue.pop(true) rescue nil
+    messages << msg if msg
+  end
+  messages.empty? ? nil : messages
+end
+----
+
+This batching improves efficiency by reducing callback overhead.
+
+=== Results Processing
+
+A separate thread monitors the ResultAggregator because:
+- The main thread is busy with socket I/O
+- The supervisor thread is running `supervisor.run`
+- We want to log results as they complete
+
+In a production system, you might process results differently (e.g., send notifications, update databases, etc.).
+
+== Continuous Mode Benefits
+
+This example demonstrates key benefits of Fractor's continuous mode:
+
+1. *Non-stopping Execution*: Server runs indefinitely, processing messages as they arrive
+2. *Dynamic Work Addition*: Work source callback provides new work on demand
+3. *Resource Efficiency*: Workers idle when no work available
+4. *Parallel Processing*: Multiple messages processed concurrently
+5. *Graceful Shutdown*: `supervisor.stop` cleanly terminates workers
+
+== See Also
+
+* link:../continuous_chat_server/[Plain Socket Implementation] - Simpler approach without Fractor
+* link:../../README.adoc#continuous-mode[Main README Continuous Mode Section]