async-enumerable 0.1.0

data/Rakefile

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]
+
+desc "Run quick benchmark overview"
+task :benchmark_quick do
+  require "benchmark"
+  require_relative "lib/async/enumerable"
+
+  # Simulate IO operations with random delays
+  def io_operation(n)
+    sleep(rand / 1000.0) # Sleep 0-1ms to simulate IO
+    n * 2
+  end
+
+  def expensive_check(n)
+    sleep(rand / 1000.0) # Sleep 0-1ms to simulate IO
+    n % 10 == 0
+  end
+
+  puts "Async::Enumerable Benchmark Comparison"
+  puts "=" * 50
+  puts "Simulating IO operations with 0-1ms delays"
+  puts
+
+  # Test different array sizes
+  [10, 100, 1000, 10000].each do |size|
+    array = (1..size).to_a
+
+    puts "\nArray size: #{size} elements"
+    puts "-" * 30
+
+    Benchmark.bm(20) do |x|
+      # Map benchmark
+      x.report("sync map:") do
+        array.map { |n| io_operation(n) }
+      end
+
+      x.report("async map:") do
+        array.async.map { |n| io_operation(n) }
+      end
+
+      # For very large collections, also test with custom max_fibers
+      if size >= 1000
+        x.report("async map (100f):") do
+          array.async(max_fibers: 100).map { |n| io_operation(n) }
+        end
+      end
+
+      # Select benchmark
+      x.report("sync select:") do
+        array.select { |n| expensive_check(n) }
+      end
+
+      x.report("async select:") do
+        array.async.select { |n| expensive_check(n) }
+      end
+
+      # Any? benchmark (with early termination)
+      x.report("sync any?:") do
+        array.any? { |n| expensive_check(n) }
+      end
+
+      x.report("async any?:") do
+        array.async.any? { |n| expensive_check(n) }
+      end
+
+      # Find benchmark (with early termination)
+      target = size / 2
+      x.report("sync find:") do
+        array.find { |n| n == target }
+      end
+
+      x.report("async find:") do
+        array.async.find { |n|
+          sleep(rand / 1000.0)
+          n == target
+        }
+      end
+    end
+  end
+
+  puts "\n" + "=" * 50
+  puts "Note: Async methods show performance benefits when:"
+  puts "  - Operations involve IO (network, disk, etc.)"
+  puts "  - Collection size is large enough to offset async overhead"
+end
+
+desc "Run detailed benchmarks with clear comparisons"
+task :benchmark do
+  puts "=" * 80
+  puts "Async::Enumerable Benchmarks"
+  puts "=" * 80
+  puts
+
+  # Size comparison benchmarks
+  puts "📊 varying collection sizes"
+  puts "-" * 40
+  puts "\nThese benchmarks compare sync vs async performance across different collection sizes."
+  puts "IO operations are simulated with sleep delays.\n\n"
+
+  Dir.glob("benchmark/size_comparison/*.yaml").sort.each do |file|
+    size = File.basename(file, ".yaml").split("_").last
+    puts "\nCollection Size: #{size} items"
+    system("bundle exec benchmark-driver #{file} 2>/dev/null")
+  end
+
+  # Early termination benchmarks
+  puts "\n\n" + "=" * 80
+  puts "⚡ early termination benchmarks"
+  puts "-" * 40
+  puts "\nThese benchmarks test methods that can terminate early (any?, find, etc.)."
+  puts "They demonstrate async performance benefits even with early termination.\n\n"
+
+  Dir.glob("benchmark/early_termination/*.yaml").sort.each do |file|
+    name = File.basename(file, ".yaml").tr("_", " ")
+    puts "\n#{name}"
+    system("bundle exec benchmark-driver #{file} 2>/dev/null")
+  end
+end

data/benchmark/async_all.yaml

@@ -0,0 +1,38 @@
+prelude: |
+  require 'async/enumerable'
+  
+  # Simulate IO operation for validation
+  def valid_item?(n, max_value = 1000)
+    sleep(rand / 1000.0) # Sleep 0-1ms to simulate IO
+    n < max_value
+  end
+  
+  all_valid = (1..50).to_a
+  early_invalid = [1, 2, 1001, 4, 5] + (6..50).to_a  # Invalid at position 3
+  mid_invalid = (1..25).to_a + [1001] + (27..50).to_a  # Invalid at middle
+  late_invalid = (1..49).to_a + [1001]  # Invalid at end
+
+benchmark:
+  sync_all_valid: |
+    all_valid.all? { |n| valid_item?(n) }
+  
+  async_all_valid: |
+    all_valid.async.all? { |n| valid_item?(n) }
+  
+  sync_early_fail: |
+    early_invalid.all? { |n| valid_item?(n) }
+  
+  async_early_fail: |
+    early_invalid.async.all? { |n| valid_item?(n) }
+  
+  sync_mid_fail: |
+    mid_invalid.all? { |n| valid_item?(n) }
+  
+  async_mid_fail: |
+    mid_invalid.async.all? { |n| valid_item?(n) }
+  
+  sync_late_fail: |
+    late_invalid.all? { |n| valid_item?(n) }
+  
+  async_late_fail: |
+    late_invalid.async.all? { |n| valid_item?(n) }

data/benchmark/async_any.yaml

@@ -0,0 +1,39 @@
+prelude: |
+  require 'async/enumerable'
+  
+  # Simulate IO operation with early termination potential
+  def expensive_check(n, target)
+    sleep(rand / 1000.0) # Sleep 0-1ms to simulate IO
+    n == target
+  end
+  
+  # Arrays with target at different positions
+  early_match = (1..100).to_a  # Target at position 10
+  mid_match = (1..100).to_a    # Target at position 50
+  late_match = (1..100).to_a   # Target at position 90
+  no_match = (1..100).to_a     # No target
+
+benchmark:
+  sync_early: |
+    early_match.any? { |n| expensive_check(n, 10) }
+  
+  async_early: |
+    early_match.async.any? { |n| expensive_check(n, 10) }
+  
+  sync_mid: |
+    mid_match.any? { |n| expensive_check(n, 50) }
+  
+  async_mid: |
+    mid_match.async.any? { |n| expensive_check(n, 50) }
+  
+  sync_late: |
+    late_match.any? { |n| expensive_check(n, 90) }
+  
+  async_late: |
+    late_match.async.any? { |n| expensive_check(n, 90) }
+  
+  sync_no_match: |
+    no_match.any? { |n| expensive_check(n, 200) }
+  
+  async_no_match: |
+    no_match.async.any? { |n| expensive_check(n, 200) }

data/benchmark/async_each.yaml

@@ -0,0 +1,51 @@
+prelude: |
+  require 'async/enumerable'
+  
+  # Simulate IO side effect operation
+  # Scale down delay for larger collections to avoid timeouts
+  def process_item(n, size = 100)
+    delay = case size
+            when 1..100 then rand / 1000.0      # 0-1ms
+            when 101..1000 then rand / 5000.0   # 0-0.2ms
+            else rand / 50000.0                 # 0-0.02ms for 10000
+            end
+    sleep(delay)
+    # Side effect: would normally write to file, database, etc.
+    n * 2
+  end
+  
+  array_10 = (1..10).to_a
+  array_100 = (1..100).to_a
+  array_1000 = (1..1000).to_a
+  array_10000 = (1..10000).to_a
+
+benchmark:
+  sync_10: |
+    array_10.each { |n| process_item(n, 10) }
+  
+  async_10: |
+    array_10.async.each { |n| process_item(n, 10) }
+  
+  sync_100: |
+    array_100.each { |n| process_item(n, 100) }
+  
+  async_100: |
+    array_100.async.each { |n| process_item(n, 100) }
+  
+  sync_1000: |
+    array_1000.each { |n| process_item(n, 1000) }
+  
+  async_1000: |
+    array_1000.async.each { |n| process_item(n, 1000) }
+  
+  async_1000_limited: |
+    array_1000.async(max_fibers: 100).each { |n| process_item(n, 1000) }
+  
+  sync_10000: |
+    array_10000.each { |n| process_item(n, 10000) }
+  
+  async_10000: |
+    array_10000.async.each { |n| process_item(n, 10000) }
+  
+  async_10000_limited: |
+    array_10000.async(max_fibers: 100).each { |n| process_item(n, 10000) }

data/benchmark/async_find.yaml

@@ -0,0 +1,37 @@
+prelude: |
+  require 'async/enumerable'
+  
+  # Simulate IO operation for finding an item
+  def matches_criteria(n, target)
+    sleep(rand / 1000.0) # Sleep 0-1ms to simulate IO
+    n == target
+  end
+  
+  small_array = (1..20).to_a
+  medium_array = (1..100).to_a
+  large_array = (1..500).to_a
+
+benchmark:
+  sync_small_early: |
+    small_array.find { |n| matches_criteria(n, 5) }
+  
+  async_small_early: |
+    small_array.async.find { |n| matches_criteria(n, 5) }
+  
+  sync_medium_mid: |
+    medium_array.find { |n| matches_criteria(n, 50) }
+  
+  async_medium_mid: |
+    medium_array.async.find { |n| matches_criteria(n, 50) }
+  
+  sync_large_late: |
+    large_array.find { |n| matches_criteria(n, 450) }
+  
+  async_large_late: |
+    large_array.async.find { |n| matches_criteria(n, 450) }
+  
+  sync_not_found: |
+    medium_array.find { |n| matches_criteria(n, 1000) }
+  
+  async_not_found: |
+    medium_array.async.find { |n| matches_criteria(n, 1000) }

data/benchmark/async_map.yaml

@@ -0,0 +1,50 @@
+prelude: |
+  require 'async/enumerable'
+  
+  # Simulate IO operations with varying delays
+  # Scale down delay for larger collections to avoid timeouts
+  def io_operation(n, size = 100)
+    delay = case size
+            when 1..100 then rand / 1000.0      # 0-1ms
+            when 101..1000 then rand / 5000.0   # 0-0.2ms
+            else rand / 50000.0                 # 0-0.02ms for 10000
+            end
+    sleep(delay)
+    n * 2
+  end
+  
+  array_10 = (1..10).to_a
+  array_100 = (1..100).to_a
+  array_1000 = (1..1000).to_a
+  array_10000 = (1..10000).to_a
+
+benchmark:
+  sync_10: |
+    array_10.map { |n| io_operation(n, 10) }
+  
+  async_10: |
+    array_10.async.map { |n| io_operation(n, 10) }
+  
+  sync_100: |
+    array_100.map { |n| io_operation(n, 100) }
+  
+  async_100: |
+    array_100.async.map { |n| io_operation(n, 100) }
+  
+  sync_1000: |
+    array_1000.map { |n| io_operation(n, 1000) }
+  
+  async_1000: |
+    array_1000.async.map { |n| io_operation(n, 1000) }
+  
+  async_1000_limited: |
+    array_1000.async(max_fibers: 100).map { |n| io_operation(n, 1000) }
+  
+  sync_10000: |
+    array_10000.map { |n| io_operation(n, 10000) }
+  
+  async_10000: |
+    array_10000.async.map { |n| io_operation(n, 10000) }
+  
+  async_10000_limited: |
+    array_10000.async(max_fibers: 100).map { |n| io_operation(n, 10000) }

data/benchmark/async_select.yaml

@@ -0,0 +1,31 @@
+prelude: |
+  require 'async/enumerable'
+  
+  # Simulate IO operation that checks a condition
+  def check_condition(n)
+    sleep(rand / 1000.0) # Sleep 0-1ms to simulate IO
+    n % 3 == 0
+  end
+  
+  small_array = (1..20).to_a
+  medium_array = (1..100).to_a
+  large_array = (1..500).to_a
+
+benchmark:
+  sync_small: |
+    small_array.select { |n| check_condition(n) }
+  
+  async_small: |
+    small_array.async.select { |n| check_condition(n) }
+  
+  sync_medium: |
+    medium_array.select { |n| check_condition(n) }
+  
+  async_medium: |
+    medium_array.async.select { |n| check_condition(n) }
+  
+  sync_large: |
+    large_array.select { |n| check_condition(n) }
+  
+  async_large: |
+    large_array.async.select { |n| check_condition(n) }

data/benchmark/early_termination/any_early.yaml

@@ -0,0 +1,17 @@
+prelude: |
+  require 'async/enumerable'
+  
+  # Simulate IO operation for checking
+  def expensive_check(n)
+    sleep(rand / 1000.0)  # 0-1ms delay
+    n > 5  # Will match early in the array
+  end
+  
+  array = (1..100).to_a
+
+benchmark:
+  "Sync any? (early match)": |
+    array.any? { |n| expensive_check(n) }
+  
+  "Async any? (early match)": |
+    array.async.any? { |n| expensive_check(n) }

data/benchmark/early_termination/any_late.yaml

@@ -0,0 +1,17 @@
+prelude: |
+  require 'async/enumerable'
+  
+  # Simulate IO operation for checking
+  def expensive_check(n)
+    sleep(rand / 1000.0)  # 0-1ms delay
+    n > 95  # Will match late in the array
+  end
+  
+  array = (1..100).to_a
+
+benchmark:
+  "Sync any? (late match)": |
+    array.any? { |n| expensive_check(n) }
+  
+  "Async any? (late match)": |
+    array.async.any? { |n| expensive_check(n) }

data/benchmark/early_termination/find_middle.yaml

@@ -0,0 +1,17 @@
+prelude: |
+  require 'async/enumerable'
+  
+  # Simulate IO operation for searching
+  def matches_criteria?(n)
+    sleep(rand / 1000.0)  # 0-1ms delay
+    n == 50  # Will find in the middle
+  end
+  
+  array = (1..100).to_a
+
+benchmark:
+  "Sync find (middle)": |
+    array.find { |n| matches_criteria?(n) }
+  
+  "Async find (middle)": |
+    array.async.find { |n| matches_criteria?(n) }

data/benchmark/size_comparison/map_10.yaml

@@ -0,0 +1,17 @@
+prelude: |
+  require 'async/enumerable'
+  
+  # Simulate IO operations with 0-1ms delay
+  def io_operation(n)
+    sleep(rand / 1000.0)
+    n * 2
+  end
+  
+  array = (1..10).to_a
+
+benchmark:
+  "Sync (10 items)": |
+    array.map { |n| io_operation(n) }
+  
+  "Async (10 items)": |
+    array.async.map { |n| io_operation(n) }

data/benchmark/size_comparison/map_100.yaml

@@ -0,0 +1,17 @@
+prelude: |
+  require 'async/enumerable'
+  
+  # Simulate IO operations with 0-1ms delay
+  def io_operation(n)
+    sleep(rand / 1000.0)
+    n * 2
+  end
+  
+  array = (1..100).to_a
+
+benchmark:
+  "Sync (100 items)": |
+    array.map { |n| io_operation(n) }
+  
+  "Async (100 items)": |
+    array.async.map { |n| io_operation(n) }

data/benchmark/size_comparison/map_1000.yaml

@@ -0,0 +1,20 @@
+prelude: |
+  require 'async/enumerable'
+  
+  # Simulate IO operations with reduced delay for large collections
+  def io_operation(n)
+    sleep(rand / 5000.0)  # 0-0.2ms
+    n * 2
+  end
+  
+  array = (1..1000).to_a
+
+benchmark:
+  "Sync (1000 items)": |
+    array.map { |n| io_operation(n) }
+  
+  "Async (1000 items)": |
+    array.async.map { |n| io_operation(n) }
+  
+  "Async(100f) (1000 items)": |
+    array.async(max_fibers: 100).map { |n| io_operation(n) }

data/benchmark/size_comparison/map_10000.yaml

@@ -0,0 +1,23 @@
+prelude: |
+  require 'async/enumerable'
+  
+  # Simulate IO operations with minimal delay for very large collections
+  def io_operation(n)
+    sleep(rand / 50000.0)  # 0-0.02ms
+    n * 2
+  end
+  
+  array = (1..10000).to_a
+
+benchmark:
+  "Sync (10000 items)": |
+    array.map { |n| io_operation(n) }
+  
+  "Async (10000 items)": |
+    array.async.map { |n| io_operation(n) }
+  
+  "Async(100f) (10000 items)": |
+    array.async(max_fibers: 100).map { |n| io_operation(n) }
+  
+  "Async(500f) (10000 items)": |
+    array.async(max_fibers: 500).map { |n| io_operation(n) }

data/docs/reference/README.md

@@ -0,0 +1,43 @@
+# Async::Enumerable Reference Documentation
+
+This directory contains detailed reference documentation for the async-enumerable gem.
+
+## Core Components
+
+- [Async::Enumerable Module](enumerable.md) - Main module for adding async capabilities to enumerables
+- [Async::Enumerator Class](enumerator.md) - Wrapper class providing async enumerable methods
+- [ConcurrencyBounder Module](concurrency_bounder.md) - Bounded concurrency control
+
+## Method Categories
+
+### [Predicate Methods](methods/predicates.md)
+- `all?`, `any?`, `none?`, `one?`
+- `find`, `find_index`
+- `include?`, `member?`
+
+### [Transformer Methods](methods/transformers.md)
+- `map`, `select`, `reject`
+- `filter_map`, `flat_map`
+- `compact`, `uniq`, `sort`, `sort_by`
+
+### [Converter Methods](methods/converters.md)
+- `to_a` - Convert to array
+- `sync` - Materialize async chain results
+
+## Quick Start
+
+For basic usage, see the main [README](../../README.md). For detailed API documentation, explore the files linked above.
+
+## Note on Documentation Style
+
+The source code contains terse YARD documentation (2-3 lines) for quick reference. These detailed markdown files provide comprehensive documentation including:
+
+- Detailed method descriptions
+- Parameter explanations
+- Return value documentation
+- Usage examples
+- Implementation notes
+- Performance considerations
+- Common patterns
+
+This separation keeps the source code clean and readable while maintaining thorough documentation.