omnizip 0.3.1

data/lib/omnizip/models/split_options.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module Models
+    # Configuration for split archive (multi-volume) creation
+    # Defines how archives should be split into volumes
+    class SplitOptions
+      attr_accessor :volume_size, :naming_pattern, :span_strategy
+
+      # Naming pattern types
+      NAMING_NUMERIC = :numeric  # .001, .002, .003
+      NAMING_ALPHA = :alpha      # .aa, .ab, .ac
+
+      # Span strategies
+      STRATEGY_FIRST_FIT = :first_fit  # Fill volumes sequentially
+      STRATEGY_BALANCED = :balanced    # Balance files across volumes
+
+      # Default volume size (100 MB)
+      DEFAULT_VOLUME_SIZE = 100 * 1024 * 1024
+
+      # Initialize with default options
+      def initialize
+        @volume_size = DEFAULT_VOLUME_SIZE
+        @naming_pattern = NAMING_NUMERIC
+        @span_strategy = STRATEGY_FIRST_FIT
+      end
+
+      # Parse volume size from string (e.g., "100M", "4.7G")
+      #
+      # @param size_str [String] Size string with unit
+      # @return [Integer] Size in bytes
+      def self.parse_volume_size(size_str)
+        return size_str if size_str.is_a?(Integer)
+
+        size_str = size_str.to_s.strip.upcase
+        multiplier = case size_str
+                     when /(\d+(?:\.\d+)?)\s*K(?:B)?$/
+                       1024
+                     when /(\d+(?:\.\d+)?)\s*M(?:B)?$/
+                       1024 * 1024
+                     when /(\d+(?:\.\d+)?)\s*G(?:B)?$/
+                       1024 * 1024 * 1024
+                     when /(\d+(?:\.\d+)?)\s*T(?:B)?$/
+                       1024 * 1024 * 1024 * 1024
+                     else
+                       return size_str.to_i
+                     end
+
+        (Regexp.last_match(1).to_f * multiplier).to_i
+      end
+
+      # Generate volume filename
+      #
+      # @param base_path [String] Base archive path (e.g., "backup.7z.001")
+      # @param volume_number [Integer] Volume number (1-based)
+      # @return [String] Volume filename
+      def volume_filename(base_path, volume_number)
+        # Extract base and extension
+        base = base_path.sub(/\.\d{3}$/, "")
+        base = base.sub(/\.[a-z]{2,}$/, "") if @naming_pattern == NAMING_ALPHA
+
+        case @naming_pattern
+        when NAMING_NUMERIC
+          format("%s.%03d", base, volume_number)
+        when NAMING_ALPHA
+          format("%s.%s", base, alpha_suffix(volume_number))
+        else
+          format("%s.%03d", base, volume_number)
+        end
+      end
+
+      # Validate options
+      #
+      # @raise [ArgumentError] if options are invalid
+      def validate!
+        raise ArgumentError, "volume_size must be positive" unless
+          @volume_size.positive?
+
+        valid_patterns = [NAMING_NUMERIC, NAMING_ALPHA]
+        unless valid_patterns.include?(@naming_pattern)
+          raise ArgumentError,
+                "naming_pattern must be one of #{valid_patterns.inspect}"
+        end
+
+        valid_strategies = [STRATEGY_FIRST_FIT, STRATEGY_BALANCED]
+        unless valid_strategies.include?(@span_strategy)
+          raise ArgumentError,
+                "span_strategy must be one of #{valid_strategies.inspect}"
+        end
+
+        true
+      end
+
+      private
+
+      # Generate alpha suffix for volume number
+      #
+      # @param volume_number [Integer] Volume number (1-based)
+      # @return [String] Alpha suffix (aa, ab, ..., az, ba, ..., zz, aaa, ...)
+      def alpha_suffix(volume_number)
+        # Convert 1 -> aa, 2 -> ab, ..., 26 -> az, 27 -> ba, etc.
+        num = volume_number - 1 # Convert to 0-based
+
+        # For two-character format (minimum):
+        # Second character cycles through a-z (rightmost, least significant)
+        second = ("a".ord + (num % 26)).chr
+
+        # First character represents which group of 26 we're in
+        first_index = num / 26
+        first = ("a".ord + first_index).chr
+
+        first + second
+      end
+    end
+  end
+end

data/lib/omnizip/optimization_registry.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Omnizip
+  # Registry for performance optimization strategies using the Registry pattern
+  class OptimizationRegistry
+    class << self
+      # Register an optimization strategy
+      def register(name, strategy_class)
+        strategies[name] = strategy_class
+      end
+
+      # Get an optimization strategy by name
+      def get(name)
+        strategies[name] || raise(
+          Omnizip::OptimizationNotFound,
+          "Optimization strategy not found: #{name}",
+        )
+      end
+
+      # Check if an optimization strategy is registered
+      def registered?(name)
+        strategies.key?(name)
+      end
+
+      # List all registered optimization strategies
+      def all
+        strategies.keys
+      end
+
+      # Get all optimization strategies as a hash
+      def strategies
+        @strategies ||= {}
+      end
+
+      # Clear all registered strategies (useful for testing)
+      def clear!
+        @strategies = {}
+      end
+
+      # Apply an optimization strategy to a target
+      def apply(name, target, **options)
+        strategy_class = get(name)
+        strategy = strategy_class.new(**options)
+        strategy.optimize(target)
+      end
+
+      # Get optimization metadata
+      def metadata(name)
+        strategy_class = get(name)
+        return {} unless strategy_class.respond_to?(:metadata)
+
+        strategy_class.metadata
+      end
+    end
+
+    # Base class for optimization strategies
+    class Strategy
+      attr_reader :options
+
+      def initialize(**options)
+        @options = options
+      end
+
+      # Override in subclasses to implement optimization logic
+      def optimize(target)
+        raise NotImplementedError,
+              "#{self.class} must implement #optimize"
+      end
+
+      # Override in subclasses to provide strategy metadata
+      def self.metadata
+        {
+          name: name,
+          description: "No description provided",
+          category: :general,
+          impact: :unknown,
+        }
+      end
+    end
+  end
+end

data/lib/omnizip/parallel/job_queue.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module Parallel
+    # Thread-safe job queue for parallel compression/extraction
+    #
+    # Manages a queue of compression or extraction jobs with priority support.
+    # Jobs are ordered by priority (large files first for better load balancing).
+    #
+    # @example Create and use job queue
+    #   queue = Omnizip::Parallel::JobQueue.new(max_size: 100)
+    #   queue.push(file: 'large.dat', size: 1_000_000, priority: :high)
+    #   job = queue.pop
+    #
+    # @example Size-based priority
+    #   queue.push_with_size(file: 'file.txt', size: 1024)
+    class JobQueue
+      # Job structure for queue items
+      Job = Struct.new(:file, :data, :size, :priority, :metadata,
+                       keyword_init: true) do
+        def <=>(other)
+          # Higher priority first, then larger files first
+          priority_order = { high: 0, normal: 1, low: 2 }
+          priority_cmp = (priority_order[priority] || 1) <=> (priority_order[other.priority] || 1)
+          return priority_cmp unless priority_cmp.zero?
+
+          # If same priority, larger files first
+          -(size <=> other.size)
+        end
+      end
+
+      # @return [Integer] maximum queue size
+      attr_reader :max_size
+
+      # @return [Integer] current queue size
+      attr_reader :size
+
+      # Initialize job queue
+      #
+      # @param max_size [Integer] maximum number of jobs in queue
+      def initialize(max_size: 1000)
+        @max_size = max_size
+        @queue = []
+        @mutex = Mutex.new
+        @cond = ConditionVariable.new
+        @closed = false
+        @size = 0
+      end
+
+      # Push a job onto the queue
+      #
+      # @param file [String] file path
+      # @param data [Object] job data
+      # @param size [Integer] file size in bytes
+      # @param priority [Symbol] job priority (:high, :normal, :low)
+      # @param metadata [Hash] additional metadata
+      # @raise [ClosedQueueError] if queue is closed
+      # @return [Job] the created job
+      def push(file:, data: nil, size: 0, priority: :normal, metadata: {})
+        @mutex.synchronize do
+          raise ClosedQueueError, "Queue is closed" if @closed
+
+          # Wait if queue is full
+          @cond.wait(@mutex) while @size >= @max_size && !@closed
+
+          raise ClosedQueueError, "Queue is closed" if @closed
+
+          job = Job.new(
+            file: file,
+            data: data,
+            size: size,
+            priority: priority,
+            metadata: metadata,
+          )
+
+          @queue << job
+          @size += 1
+
+          # Keep queue sorted by priority
+          @queue.sort!
+
+          @cond.signal
+          job
+        end
+      end
+
+      # Push a job with automatic priority based on file size
+      #
+      # @param file [String] file path
+      # @param size [Integer] file size in bytes
+      # @param data [Object] job data
+      # @param metadata [Hash] additional metadata
+      # @return [Job] the created job
+      def push_with_size(file:, size:, data: nil, metadata: {})
+        # Determine priority based on size
+        # Large files (>10MB) get high priority for better load balancing
+        priority = if size > 10 * 1024 * 1024
+                     :high
+                   elsif size > 1024 * 1024
+                     :normal
+                   else
+                     :low
+                   end
+
+        push(file: file, data: data, size: size, priority: priority,
+             metadata: metadata)
+      end
+
+      # Pop a job from the queue
+      #
+      # @param timeout [Numeric, nil] timeout in seconds, nil for no timeout
+      # @return [Job, nil] job or nil if timeout or closed
+      def pop(timeout: nil)
+        @mutex.synchronize do
+          if timeout
+            deadline = Time.now + timeout
+            while @queue.empty? && !@closed
+              remaining = deadline - Time.now
+              return nil if remaining <= 0
+
+              @cond.wait(@mutex, remaining)
+            end
+          else
+            @cond.wait(@mutex) while @queue.empty? && !@closed
+          end
+
+          return nil if @queue.empty?
+
+          job = @queue.shift
+          @size -= 1
+          @cond.signal # Signal waiting pushers
+          job
+        end
+      end
+
+      # Pop multiple jobs in batch
+      #
+      # @param count [Integer] maximum number of jobs to pop
+      # @param timeout [Numeric, nil] timeout in seconds
+      # @return [Array<Job>] array of jobs (may be empty)
+      def pop_batch(count, timeout: nil)
+        jobs = []
+        count.times do
+          job = pop(timeout: timeout)
+          break unless job
+
+          jobs << job
+        end
+        jobs
+      end
+
+      # Check if queue is empty
+      #
+      # @return [Boolean] true if empty
+      def empty?
+        @mutex.synchronize { @queue.empty? }
+      end
+
+      # Check if queue is closed
+      #
+      # @return [Boolean] true if closed
+      def closed?
+        @mutex.synchronize { @closed }
+      end
+
+      # Close the queue
+      #
+      # No more jobs can be pushed after closing.
+      # Pending pops will return nil.
+      def close
+        @mutex.synchronize do
+          @closed = true
+          @cond.broadcast # Wake up all waiting threads
+        end
+      end
+
+      # Clear all jobs from queue
+      #
+      # @return [Integer] number of jobs cleared
+      def clear
+        @mutex.synchronize do
+          count = @queue.size
+          @queue.clear
+          @size = 0
+          @cond.broadcast
+          count
+        end
+      end
+
+      # Get queue statistics
+      #
+      # @return [Hash] statistics hash
+      def stats
+        @mutex.synchronize do
+          {
+            size: @size,
+            max_size: @max_size,
+            closed: @closed,
+            utilization: @max_size.zero? ? 0.0 : @size.to_f / @max_size,
+            priority_counts: @queue.group_by(&:priority).transform_values(&:count),
+          }
+        end
+      end
+    end
+
+    # Exception raised when trying to push to a closed queue
+    class ClosedQueueError < StandardError; end
+  end
+end

data/lib/omnizip/parallel/job_scheduler.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module Parallel
+    # Job scheduler for load balancing and work distribution
+    #
+    # Manages job assignment to workers using different strategies:
+    # - Dynamic: Workers pull jobs as they become available (default)
+    # - Static: Pre-assign equal chunks to each worker
+    #
+    # @example Create scheduler with dynamic strategy
+    #   scheduler = Omnizip::Parallel::JobScheduler.new(strategy: :dynamic)
+    #   scheduler.schedule_jobs(jobs, worker_count: 4)
+    #
+    # @example Create scheduler with static strategy
+    #   scheduler = Omnizip::Parallel::JobScheduler.new(strategy: :static)
+    #   assignments = scheduler.schedule_jobs(jobs, worker_count: 4)
+    class JobScheduler
+      # @return [Symbol] scheduling strategy
+      attr_reader :strategy
+
+      # Initialize job scheduler
+      #
+      # @param strategy [Symbol] :dynamic or :static
+      def initialize(strategy: :dynamic)
+        @strategy = strategy
+        validate_strategy!
+      end
+
+      # Schedule jobs for workers
+      #
+      # @param jobs [Array] array of jobs to schedule
+      # @param worker_count [Integer] number of workers
+      # @return [Hash, Array] assignments (strategy-dependent)
+      def schedule_jobs(jobs, worker_count:)
+        case @strategy
+        when :dynamic
+          schedule_dynamic(jobs, worker_count)
+        when :static
+          schedule_static(jobs, worker_count)
+        end
+      end
+
+      # Estimate completion time based on job sizes and worker count
+      #
+      # @param jobs [Array] array of jobs with :size attribute
+      # @param worker_count [Integer] number of workers
+      # @param bytes_per_second [Float] processing rate
+      # @return [Float] estimated seconds to completion
+      def estimate_completion_time(jobs, worker_count:,
+bytes_per_second: 10_000_000)
+        total_bytes = jobs.sum { |job| job.respond_to?(:size) ? job.size : 0 }
+        return 0.0 if total_bytes.zero? || worker_count.zero?
+
+        # Simple estimate: total bytes / (workers * rate)
+        total_bytes.to_f / (worker_count * bytes_per_second)
+      end
+
+      # Calculate load balance quality metric
+      #
+      # @param assignments [Hash] worker_id => [jobs] mapping
+      # @return [Float] balance score (0.0 = perfect, 1.0 = worst)
+      def calculate_load_balance(assignments)
+        return 0.0 if assignments.empty?
+
+        # Calculate total size per worker
+        worker_sizes = assignments.transform_values do |jobs|
+          jobs.sum { |job| job.respond_to?(:size) ? job.size : 1 }
+        end
+
+        sizes = worker_sizes.values
+        return 0.0 if sizes.empty? || sizes.max.zero?
+
+        # Balance = (max - min) / max
+        (sizes.max - sizes.min).to_f / sizes.max
+      end
+
+      private
+
+      # Validate scheduling strategy
+      #
+      # @raise [ArgumentError] if strategy is invalid
+      def validate_strategy!
+        valid_strategies = %i[dynamic static]
+        return if valid_strategies.include?(@strategy)
+
+        raise ArgumentError,
+              "Invalid strategy: #{@strategy}. Must be one of: #{valid_strategies.join(', ')}"
+      end
+
+      # Dynamic scheduling: jobs pulled from queue as workers become available
+      #
+      # @param jobs [Array] jobs to schedule
+      # @param worker_count [Integer] number of workers
+      # @return [Hash] scheduling metadata
+      def schedule_dynamic(jobs, worker_count)
+        # In dynamic mode, we don't pre-assign jobs
+        # Workers pull from shared queue as they complete work
+        # Return metadata about the scheduling
+        {
+          strategy: :dynamic,
+          total_jobs: jobs.size,
+          worker_count: worker_count,
+          estimated_jobs_per_worker: (jobs.size.to_f / worker_count).ceil,
+          queue: jobs, # Jobs will be consumed from this queue
+        }
+      end
+
+      # Static scheduling: pre-assign jobs to workers in balanced chunks
+      #
+      # @param jobs [Array] jobs to schedule
+      # @param worker_count [Integer] number of workers
+      # @return [Hash] worker_id => [jobs] mapping
+      def schedule_static(jobs, worker_count)
+        return {} if jobs.empty? || worker_count.zero?
+
+        # Sort jobs by size (largest first) for better balance
+        sorted_jobs = jobs.sort_by do |job|
+          -(job.respond_to?(:size) ? job.size : 0)
+        end
+
+        # Initialize worker assignments
+        assignments = (0...worker_count).to_h { |i| [i, []] }
+        worker_loads = Array.new(worker_count, 0)
+
+        # Assign each job to worker with smallest current load
+        sorted_jobs.each do |job|
+          job_size = job.respond_to?(:size) ? job.size : 1
+
+          # Find worker with minimum load
+          min_worker = worker_loads.each_with_index.min_by { |load, _| load }[1]
+
+          # Assign job to this worker
+          assignments[min_worker] << job
+          worker_loads[min_worker] += job_size
+        end
+
+        # Add metadata
+        assignments[:metadata] = {
+          strategy: :static,
+          total_jobs: jobs.size,
+          worker_count: worker_count,
+          balance_score: calculate_load_balance(assignments.except(:metadata)),
+          worker_loads: worker_loads,
+        }
+
+        assignments
+      end
+
+      # Round-robin assignment (alternative simple strategy)
+      #
+      # @param jobs [Array] jobs to schedule
+      # @param worker_count [Integer] number of workers
+      # @return [Hash] worker_id => [jobs] mapping
+      def schedule_round_robin(jobs, worker_count)
+        return {} if jobs.empty? || worker_count.zero?
+
+        assignments = (0...worker_count).to_h { |i| [i, []] }
+
+        jobs.each_with_index do |job, index|
+          worker_id = index % worker_count
+          assignments[worker_id] << job
+        end
+
+        assignments
+      end
+
+      # Size-aware assignment with bin packing
+      #
+      # @param jobs [Array] jobs to schedule
+      # @param worker_count [Integer] number of workers
+      # @return [Hash] worker_id => [jobs] mapping
+      def schedule_bin_packing(jobs, worker_count)
+        return {} if jobs.empty? || worker_count.zero?
+
+        # Sort jobs by size (largest first)
+        sorted_jobs = jobs.sort_by do |job|
+          -(job.respond_to?(:size) ? job.size : 0)
+        end
+
+        # First-fit decreasing bin packing
+        bins = Array.new(worker_count) { { jobs: [], total_size: 0 } }
+
+        sorted_jobs.each do |job|
+          job_size = job.respond_to?(:size) ? job.size : 1
+
+          # Find bin with minimum total size
+          min_bin = bins.min_by { |bin| bin[:total_size] }
+          min_bin[:jobs] << job
+          min_bin[:total_size] += job_size
+        end
+
+        # Convert to standard format
+        assignments = {}
+        bins.each_with_index do |bin, index|
+          assignments[index] = bin[:jobs]
+        end
+
+        assignments
+      end
+    end
+  end
+end