fractor 0.1.4 → 0.1.6

data/examples/auto_detection/auto_detection.rb

@@ -86,8 +86,8 @@ puts
 
 supervisor1 = Fractor::Supervisor.new(
   worker_pools: [
-    { worker_class: ComputeWorker } # No num_workers specified
-  ]
+    { worker_class: ComputeWorker }, # No num_workers specified
+  ],
 )
 
 # Add work items
@@ -97,7 +97,7 @@ 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 "Results: #{supervisor1.results.results.map(&:result).sort.join(', ')}"
 puts "✓ Auto-detection successful!"
 puts
 
@@ -110,8 +110,8 @@ puts
 
 supervisor2 = Fractor::Supervisor.new(
   worker_pools: [
-    { worker_class: ComputeWorker, num_workers: 4 }
-  ]
+    { worker_class: ComputeWorker, num_workers: 4 },
+  ],
 )
 
 supervisor2.add_work_items((11..20).map { |i| ComputeWork.new(i) })
@@ -119,7 +119,7 @@ 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 "Results: #{supervisor2.results.results.map(&:result).sort.join(', ')}"
 puts "✓ Explicit configuration successful!"
 puts
 
@@ -135,8 +135,8 @@ puts
 supervisor3 = Fractor::Supervisor.new(
   worker_pools: [
     { worker_class: ComputeWorker }, # Auto-detected
-    { worker_class: ComputeWorker, num_workers: 2 } # Explicit
-  ]
+    { worker_class: ComputeWorker, num_workers: 2 }, # Explicit
+  ],
 )
 
 supervisor3.add_work_items((21..30).map { |i| ComputeWork.new(i) })
@@ -144,7 +144,7 @@ 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 "Results: #{supervisor3.results.results.map(&:result).sort.join(', ')}"
 puts "✓ Mixed configuration successful!"
 puts
 

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]

data/examples/continuous_chat_fractor/chat_client.rb

@@ -0,0 +1,303 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'socket'
+require 'json'
+require 'fileutils'
+
+module ContinuousChat
+  # Simple Chat Client using Ruby's standard socket library
+  class ChatClient
+    def initialize(username, server_host = 'localhost', server_port = 3000,
+                   log_file_path = nil)
+      @username = username
+      @server_host = server_host
+      @server_port = server_port
+      @running = true
+
+      # Set up logging
+      @log_file_path = log_file_path || "logs/client_#{username}_messages.log"
+      FileUtils.mkdir_p(File.dirname(@log_file_path))
+      @log_file = File.open(@log_file_path, 'w')
+
+      log_message("Client initialized for #{username}, connecting to #{server_host}:#{server_port}")
+    end
+
+    def connect
+      puts "Connecting to server at #{@server_host}:#{@server_port}..."
+      log_message("Connecting to server at #{@server_host}:#{@server_port}")
+
+      begin
+        @socket = TCPSocket.new(@server_host, @server_port)
+
+        # Send join message
+        join_data = {
+          type: 'join',
+          data: {
+            username: @username
+          },
+          timestamp: Time.now.to_i
+        }
+        @socket.puts(JSON.generate(join_data))
+        log_message("Sent join message: #{join_data}")
+
+        puts 'Connected to chat server!'
+        log_message('Connected to chat server')
+
+        true
+      rescue StandardError => e
+        puts "Failed to connect: #{e.message}"
+        log_message("Failed to connect: #{e.message}")
+        false
+      end
+    end
+
+    def start
+      return false unless @socket
+
+      # Main event loop that handles both sending and receiving messages
+      # without creating separate threads
+      main_event_loop
+
+      true
+    end
+
+    # Main event loop that handles both user input and server messages
+    def main_event_loop
+      log_message('Starting main event loop')
+
+      # Print initial prompt
+      print "(#{@username})> "
+      $stdout.flush
+
+      while @running
+        # Use IO.select to wait for input from either STDIN or the socket
+        # This is non-blocking and allows us to handle both in a single loop
+        readable, = IO.select([@socket, $stdin], nil, nil, 0.1)
+
+        next unless readable # Nothing to process this iteration
+
+        readable.each do |io|
+          if io == $stdin
+            # Handle user input
+            handle_user_input
+          elsif io == @socket
+            # Handle server message
+            handle_server_message
+          end
+        end
+      end
+    rescue Interrupt
+      log_message('Client interrupted')
+      @running = false
+    rescue StandardError => e
+      log_message("Error in main event loop: #{e.message}")
+      @running = false
+    ensure
+      disconnect
+    end
+
+    # Handle user input (non-blocking)
+    def handle_user_input
+      text = $stdin.gets&.chomp
+      return unless text
+
+      # Check if client wants to quit
+      if text == '/quit' || text.nil?
+        @running = false
+        return
+      end
+
+      # Create message packet
+      message_data = {
+        type: 'message',
+        data: {
+          content: text,
+          recipient: 'all' # Default to broadcast
+        },
+        timestamp: Time.now.to_i
+      }
+
+      # Send to server
+      @socket.puts(JSON.generate(message_data))
+      log_message("Sent message: #{text}")
+
+      # Print prompt for next input
+      print "(#{@username})> "
+      $stdout.flush
+    rescue StandardError => e
+      log_message("Error handling user input: #{e.message}")
+      @running = false
+    end
+
+    # Handle server message (non-blocking)
+    def handle_server_message
+      line = @socket.gets&.chomp
+
+      if line.nil?
+        # Server closed the connection
+        log_message('Connection to server lost')
+        @running = false
+        return
+      end
+
+      # Parse and handle the message
+      message = JSON.parse(line)
+      log_message("Received: #{line}")
+
+      # Display formatted message based on type
+      case message['type']
+      when 'broadcast'
+        puts "\r#{message['data']['from']}: #{message['data']['content']}"
+      when 'direct_message'
+        puts "\r[DM] #{message['data']['from']}: #{message['data']['content']}"
+      when 'server_message'
+        puts "\r[Server] #{message['data']['message']}"
+      when 'user_list'
+        puts "\r[Server] Users online: #{message['data']['users'].join(', ')}"
+      when 'error'
+        puts "\r[Error] #{message['data']['message']}"
+      end
+
+      # Reprint the prompt
+      print "(#{@username})> "
+      $stdout.flush
+    rescue StandardError => e
+      log_message("Error handling server message: #{e.message}")
+      # Don't immediately break for connection errors, may be temporary
+      # Just log and continue, IO.select will catch closed connections
+    end
+
+    def run_with_messages(messages, _delay_between_messages = 1)
+      return false unless @socket && @running
+
+      log_message("Running with #{messages.size} predefined messages")
+      puts "Sending #{messages.size} predefined messages"
+
+      # Send all messages in a non-blocking way
+      batch_send_messages(messages)
+
+      log_message('Finished sending all predefined messages')
+
+      # Start the event loop to receive responses
+      main_event_loop
+
+      true
+    end
+
+    # Helper to send a batch of messages without blocking
+    def batch_send_messages(messages)
+      messages.each_with_index do |msg, index|
+        content = msg[:content]
+        recipient = msg[:recipient] || 'all'
+
+        log_message("Sending message #{index + 1}: '#{content}' to #{recipient}")
+
+        message_data = {
+          type: 'message',
+          data: {
+            content: content,
+            recipient: recipient
+          },
+          timestamp: Time.now.to_i
+        }
+
+        @socket.puts(JSON.generate(message_data))
+        log_message("Sent message to #{recipient}: #{content}")
+
+        # Small delay between messages for stability
+        sleep(0.1)
+      end
+    end
+
+    def disconnect
+      return unless @running
+
+      @running = false
+      log_message('Disconnecting from server')
+
+      if @socket && !@socket.closed?
+        # Send leave message
+        leave_data = {
+          type: 'leave',
+          data: {
+            username: @username
+          },
+          timestamp: Time.now.to_i
+        }
+        @socket.puts(JSON.generate(leave_data))
+        log_message('Sent leave message')
+
+        @socket.close
+      end
+
+      @log_file&.close
+
+      puts 'Disconnected from server.'
+      true
+    end
+
+    private
+
+    def log_message(message)
+      timestamp = Time.now.strftime('%Y-%m-%d %H:%M:%S.%L')
+      log_entry = "[#{timestamp}] #{message}"
+
+      @log_file.puts(log_entry)
+      @log_file.flush # Ensure it's written immediately
+    end
+  end
+end
+
+# When run directly, start the client
+if __FILE__ == $PROGRAM_NAME
+  require 'fileutils'
+  require 'json'
+
+  puts 'Chat Client'
+  puts '==========='
+  puts 'This is the chat client that connects to the chat server.'
+  puts 'All messages are logged to a file for later analysis.'
+  puts
+
+  # Get username from command line or prompt
+  username = ARGV[0]
+
+  unless username
+    print 'Enter your username: '
+    username = gets.chomp
+  end
+
+  # Get port from command line or use default
+  port = ARGV[1]&.to_i || 3000
+  log_file = ARGV[2] || "logs/client_#{username}_messages.log"
+
+  # Check for messages file
+  messages_file = "logs/client_#{username}_send_messages.json"
+
+  # Create and run the client
+  client = ContinuousChat::ChatClient.new(username, 'localhost', port, log_file)
+
+  if client.connect
+    begin
+      # Load and send messages if the file exists
+      if File.exist?(messages_file)
+        puts "Loading messages from #{messages_file}"
+        messages = JSON.parse(File.read(messages_file), symbolize_names: true)
+        puts "Loaded #{messages.size} messages"
+
+        # Send the messages
+        client.run_with_messages(messages)
+      end
+
+      # Start the client
+      client.start
+    rescue Interrupt
+      puts "\nClient interrupted."
+    ensure
+      client.disconnect
+    end
+  end
+
+  puts 'Chat client exited.'
+end