async-enumerable 0.1.0

data/lib/async/enumerable/methods.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "async/enumerable/methods/each"
+
+require "async/enumerable/methods/aggregators"
+require "async/enumerable/methods/converters"
+require "async/enumerable/methods/iterators"
+require "async/enumerable/methods/predicates"
+require "async/enumerable/methods/slicers"
+require "async/enumerable/methods/transformers"
+
+module Async
+  module Enumerable
+    # Methods contains all async implementations of Enumerable methods
+    module Methods
+      include Each
+
+      include Aggregators
+      include Converters
+      include Iterators
+      include Predicates
+      include Slicers
+      include Transformers
+    end
+  end
+end

data/lib/async/enumerable/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    # This constant follows semantic versioning (https://semver.org/):
+    #
+    # @return [String] The current version of the gem
+    VERSION = "0.1.0"
+  end
+end

data/lib/async/enumerable.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/barrier"
+require "async/semaphore"
+
+require "concurrent/array"
+require "concurrent/atomic/atomic_boolean"
+require "concurrent/atomic/atomic_fixnum"
+require "concurrent/atomic/atomic_reference"
+
+require "forwardable"
+
+module Async
+  module Enumerable
+  end
+end
+
+require "async/enumerable/configurable"
+require "async/enumerable/concurrency_bounder"
+require "async/enumerable/comparable"
+require "async/enumerable/methods"
+require "async/enumerable/version"
+
+module Async
+  # Provides async parallel execution for Enumerable.
+  # See docs/reference/enumerable.md for detailed documentation.
+  module Enumerable
+    @__async_enumerable_config_ref = Concurrent::AtomicReference.new(Configurable::Config.new)
+    extend Configurable
+    include Configurable
+
+    class << self
+      alias_method :config, :__async_enumerable_config
+      alias_method :configure, :__async_enumerable_config
+
+      # Configures modules when included in a class.
+      # @param base [Class] The including class
+      def included(base)
+        base.extend(Configurable)
+        base.extend(Configurable::ClassMethods)
+        base.include(Configurable)
+        base.include(Comparable)
+        base.include(Methods)
+        base.include(AsyncMethod)
+      end
+
+      # Gets the module-level config reference.
+      # @return [AtomicReference] Config reference
+      def config_ref
+        @__async_enumerable_config_ref
+      end
+    end
+
+    # Async method module - included last to override Enumerable's version.
+    module AsyncMethod
+      # Returns async enumerator (idempotent - returns self if already async).
+      # @param kwargs [Hash] Configuration options (max_fibers, etc.)
+      # @return [Async::Enumerator] Async wrapper
+      def async(**kwargs)
+        return self if kwargs.empty? && self.class.include?(Async::Enumerable)
+
+        source = __async_enumerable_collection || self
+        config = __async_enumerable_config
+        Async::Enumerator.new(source, config, **kwargs)
+      end
+    end
+  end
+end
+
+require "async/enumerator"
+require "enumerable/async"

data/lib/async/enumerator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Async
+  # Wrapper providing async enumerable methods for parallel execution.
+  # See docs/reference/enumerator.md for detailed documentation.
+  class Enumerator
+    include Async::Enumerable
+    def_async_enumerable :@enumerable
+
+    # Creates async wrapper for enumerable.
+    # @param enumerable [Enumerable] Object to wrap
+    # @param config [Config, nil] Configuration object
+    # @param kwargs [Hash] Configuration options (max_fibers, etc.)
+    def initialize(enumerable = [], config = nil, **kwargs)
+      @enumerable = enumerable
+
+      # Only configure if config or kwargs are provided
+      if config || !kwargs.empty?
+        __async_enumerable_configure do |cfg|
+          # Merge config if provided
+          config&.to_h&.each do |key, val|
+            cfg[key] = val if val
+          end
+
+          # Merge kwargs if provided
+          kwargs.each do |key, val|
+            cfg[key] = val if val
+          end
+        end
+      end
+    end
+  end
+end

data/lib/enumerable/async.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Extension to Ruby's Enumerable module that adds asynchronous capabilities.
+module Enumerable
+  # Returns an AsyncEnumerator wrapper that provides asynchronous versions of
+  # Enumerable methods for parallel execution.
+  #
+  # This method enables concurrent processing of Enumerable operations using
+  # the `socketry/async` library, allowing for significant performance
+  # improvements when dealing with I/O-bound operations or large collections.
+  #
+  # @param kwargs [Hash] Configuration options (max_fibers, etc.)
+  #
+  # @example Basic usage with async map
+  #   [1, 2, 3].async.map { |n| n * 2 }  # => [2, 4, 6] (executed in parallel)
+  #
+  # @example Using with I/O operations
+  #   urls.async.map { |url| fetch_data(url) }  # Fetches all URLs concurrently
+  #
+  # @example With custom fiber limit
+  #   huge_dataset.async(max_fibers: 100).map { |item| process(item) }
+  #   # Processes with max 100 concurrent fibers
+  #
+  # @example Chaining async operations
+  #   data.async
+  #       .select { |item| item.valid? }
+  #       .map { |item| process(item) }
+  #       .to_a
+  #
+  # @return [Async::Enumerator] An async wrapper around this
+  #   enumerable that provides parallel execution capabilities for enumerable
+  #   methods
+  #
+  # @see Async::Enumerator
+  def async(**kwargs)
+    Async::Enumerator.new(self, **kwargs)
+  end
+end

data/scripts/debug_config.rb

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+require_relative "../lib/async/enumerable"
+
+# Test 1: Module config
+puts "=== Test 1: Module config ==="
+puts "Before configure: #{Async::Enumerable.config.max_fibers}"
+Async::Enumerable.configure { |c| c.max_fibers = 50 }
+puts "After configure: #{Async::Enumerable.config.max_fibers}"
+
+# Test 2: Create enumerator with no config
+puts "\n=== Test 2: Enumerator with no config ==="
+enum = Async::Enumerator.new([1, 2, 3])
+puts "Enumerator config: #{enum.__async_enumerable_config.max_fibers}"
+puts "Module config: #{Async::Enumerable.config.max_fibers}"
+
+# Test 3: Check config_ref
+puts "\n=== Test 3: Config ref details ==="
+puts "Enumerator config_ref: #{enum.__async_enumerable_config_ref}"
+puts "Enumerator config_ref.get: #{enum.__async_enumerable_config_ref.get}"
+puts "Module config_ref: #{Async::Enumerable.config_ref}"
+puts "Module config_ref.get: #{Async::Enumerable.config_ref.get}"
+
+# Test 4: Check merge_all_config
+puts "\n=== Test 4: Merge all config ==="
+merged = enum.__async_enumerable_merge_all_config
+puts "Merged config: #{merged}"

data/scripts/debug_config2.rb

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+require_relative "../lib/async/enumerable"
+
+# Check initial state
+puts "=== Initial state ==="
+puts "Module config: #{Async::Enumerable.config.max_fibers}"
+puts "Enumerator class config: #{Async::Enumerator.__async_enumerable_config.max_fibers if Async::Enumerator.respond_to?(:__async_enumerable_config)}"
+
+# Now configure module
+puts "\n=== After configuring module ==="
+Async::Enumerable.configure { |c| c.max_fibers = 50 }
+puts "Module config: #{Async::Enumerable.config.max_fibers}"
+puts "Enumerator class config: #{Async::Enumerator.__async_enumerable_config.max_fibers if Async::Enumerator.respond_to?(:__async_enumerable_config)}"
+
+# Create a fresh class that includes Async::Enumerable
+puts "\n=== Creating fresh class after module config ==="
+class TestClass
+  include Async::Enumerable
+  def_async_enumerable :@data
+  
+  def initialize
+    @data = [1, 2, 3]
+  end
+end
+
+puts "TestClass config: #{TestClass.__async_enumerable_config.max_fibers}"
+
+# Create instance
+puts "\n=== Creating instances ==="
+enum = Async::Enumerator.new([1, 2, 3])
+puts "Enumerator instance config: #{enum.__async_enumerable_config.max_fibers}"
+
+test = TestClass.new
+puts "TestClass instance config: #{test.__async_enumerable_config.max_fibers}"

data/scripts/sketch.rb

@@ -0,0 +1,30 @@
+# i'm flailing a little bit here. what am i going for?
+
+class Foo
+  include Async::Enumerable
+  def_async_enumerable :@bar, max_fibers: 100, pipeline: true
+
+  def initialize
+    @bar = []
+  end
+
+  def perform
+    Sync do |parent|
+      # @bar = [1, 2, 3, 4]
+      async(parent:) # update the instance config to use this parent
+        .map { |x| x + 1 } # async map over @bar, returning a task that adds 1 for each
+        # => Task{1 + 1}, Task{2 + 1}, Task{3 + 1}, Task{4 + 1} # unordered, individual
+        .accumulate(2, timeout_ms: 200) # gather batches up to 2 waiting up to 200ms before sending
+        # => [Task{1 + 1}, Task{2 + 1}], [Task{3 + 1}, Task{4 + 1}] # unordered
+        .map { |x| x.wait.sum }
+        # x is an accumulated Async::Enumerator<Task>
+        # wait blocks until all included tasks are resolved, then returns self
+        # sum is an Enumerable method called on the Async::Enumerator
+        # => [???]
+        .flatten
+        # => [Task...]
+        .sync # resolve the entire pipeline and all tasks in it
+        # => [2, 3, 4, 5]
+    end
+  end
+end

data/scripts/test_aggregators.rb

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "async"
+require "async/enumerable"
+
+# Create a class that tracks when #each is called
+class TrackedArray
+  include Async::Enumerable
+  def_enumerator :items
+
+  attr_reader :items, :each_called
+
+  def initialize(items)
+    @items = items
+    @each_called = false
+  end
+end
+
+Sync do
+  puts "Testing aggregator methods to verify they use async #each:"
+  puts
+
+  # Test reduce
+  tracked = TrackedArray.new([1, 2, 3, 4, 5])
+  result = tracked.async.reduce(0) do |sum, n|
+    puts "  reduce: processing #{n} in fiber"
+    sum + n
+  end
+  puts "reduce result: #{result}"
+  puts
+
+  # Test sum with block
+  tracked = TrackedArray.new([1, 2, 3, 4, 5])
+  result = tracked.async.sum do |n|
+    puts "  sum: processing #{n} in fiber"
+    n * 2
+  end
+  puts "sum result: #{result}"
+  puts
+
+  # Test count with block
+  tracked = TrackedArray.new([1, 2, 3, 4, 5])
+  result = tracked.async.count do |n|
+    puts "  count: checking #{n} in fiber"
+    n.even?
+  end
+  puts "count result: #{result}"
+  puts
+
+  # Test tally
+  tracked = TrackedArray.new(%w[a b a c b a])
+  result = tracked.async.tally
+  puts "tally result: #{result}"
+  puts
+
+  # Test min/max with expensive comparison
+  tracked = TrackedArray.new([5, 2, 8, 1, 9])
+  result = tracked.async.min_by do |n|
+    puts "  min_by: evaluating #{n} in fiber"
+    sleep(0.1) # Simulate expensive computation
+    n * -1 # Find the max by negating
+  end
+  puts "min_by result: #{result}"
+end

data/scripts/test_ancestors.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/async/enumerable"
+
+e = [1, 2, 3].async
+puts "Async::Enumerator ancestors:"
+puts e.class.ancestors.take(10).map(&:to_s).join("\n  ")
+
+puts "\nMethod resolution for async:"
+puts "Method owner: #{e.method(:async).owner}"
+puts "Source: #{e.method(:async).source_location.inspect}"

data/scripts/test_async_chaining.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/async/enumerable"
+
+puts "Testing async chaining..."
+e = [1, 2, 3].async
+puts "First async: #{e.class}"
+puts "Is Async::Enumerator? #{e.is_a?(Async::Enumerator)}"
+
+# Add debug to the async method temporarily
+class Async::Enumerator
+  def async_debug(max_fibers: nil)
+    puts "  In async method"
+    puts "  self.class: #{self.class}"
+    puts "  is_a?(::Async::Enumerator): #{is_a?(::Async::Enumerator)}"
+
+    if is_a?(::Async::Enumerator)
+      puts "  Returning self!"
+      return self
+    end
+
+    puts "  Creating new enumerator..."
+    super
+  end
+end
+
+e2 = e.async_debug
+puts "Second async: #{e2.class}"
+puts "Same object? #{e.equal?(e2)}"

data/scripts/test_direct_method_calls.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# Test script to demonstrate issue #7 - methods referencing @enumerable directly
+
+require_relative "../lib/async/enumerable"
+
+class MyCollection
+  include Async::Enumerable
+  def_enumerator :items
+
+  def initialize
+    @items = [1, 2, 3, 4, 5]
+  end
+
+  attr_reader :items
+end
+
+collection = MyCollection.new
+puts "Collection responds to any?: #{collection.respond_to?(:any?)}"
+puts "Collection.async responds to any?: #{collection.async.respond_to?(:any?)}"
+
+# Try calling any? directly on the collection (not through async)
+begin
+  result = collection.any? { |x| x > 3 }
+  puts "Direct any? result: #{result}"
+rescue => e
+  puts "Direct any? error: #{e.message}"
+  puts "  Backtrace: #{e.backtrace.first(3).join("\n  ")}"
+end
+
+# Try calling through async (should work)
+begin
+  result = collection.async.any? { |x| x > 3 }
+  puts "Async any? result: #{result}"
+rescue => e
+  puts "Async any? error: #{e.message}"
+end
+
+puts "\n--- Testing all? method ---"
+# Try all? directly
+begin
+  result = collection.all? { |x| x > 0 }
+  puts "Direct all? result: #{result}"
+rescue => e
+  puts "Direct all? error: #{e.message}"
+end
+
+# Try all? through async
+begin
+  result = collection.async.all? { |x| x > 0 }
+  puts "Async all? result: #{result}"
+rescue => e
+  puts "Async all? error: #{e.message}"
+end

data/scripts/test_example.rb

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "lib/async/enumerable"
+
+# Example class that includes Async::Enumerable
+class TodoList
+  include Async::Enumerable
+  def_enumerator :todos
+
+  def initialize
+    @todos = []
+  end
+
+  attr_reader :todos
+
+  def add(todo)
+    @todos << todo
+  end
+end
+
+# Test the new functionality
+list = TodoList.new
+list.add("Buy milk")
+list.add("Write code")
+list.add("Review PR")
+
+puts "Testing def_enumerator with TodoList:"
+results = list.async.map { |todo| "✓ #{todo}" }.sync
+puts results.inspect
+
+# Test that regular arrays still work
+puts "\nTesting regular array async:"
+array_results = [1, 2, 3].async.map { |n| n * 2 }.sync
+puts array_results.inspect
+
+puts "\nAll tests passed!"

data/scripts/test_issue_7.rb

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test script to verify issue #7 is resolved
+# Issue: Methods should use enumerable source from def_enumerator, not @enumerable directly
+
+require_relative "../lib/async/enumerable"
+
+# Test 1: Includable pattern with def_enumerator
+class MyCollection
+  include Async::Enumerable
+  def_enumerator :items  # Specifies that 'items' method returns the enumerable
+
+  def initialize(data)
+    @items = data
+  end
+
+  attr_reader :items
+end
+
+puts "Test 1: Includable pattern with def_enumerator"
+collection = MyCollection.new([1, 2, 3, 4, 5])
+
+# Test async operations work with the specified source
+result = collection.async.map { |x| x * 2 }.to_a
+puts "  map result: #{result.inspect}"
+puts "  ✓ map works" if result == [2, 4, 6, 8, 10]
+
+# Test predicate methods work
+all_positive = collection.all? { |x| x > 0 }
+puts "  all? result: #{all_positive}"
+puts "  ✓ all? works" if all_positive == true
+
+any_large = collection.any? { |x| x > 3 }
+puts "  any? result: #{any_large}"
+puts "  ✓ any? works" if any_large == true
+
+# Test 2: Async::Enumerator with @enumerable instance variable
+puts "\nTest 2: Async::Enumerator wrapper pattern"
+async_enum = [1, 2, 3, 4, 5].async
+
+# Verify it uses @enumerable correctly
+result = async_enum.map { |x| x * 2 }.to_a
+puts "  map result: #{result.inspect}"
+puts "  ✓ Async::Enumerator map works" if result == [2, 4, 6, 8, 10]
+
+# Test 3: Class without def_enumerator (uses self)
+class DirectCollection
+  include Async::Enumerable
+  include Enumerable
+
+  def initialize(data)
+    @data = data
+  end
+
+  def each(&block)
+    @data.each(&block)
+  end
+end
+
+puts "\nTest 3: Without def_enumerator (uses self)"
+direct = DirectCollection.new([1, 2, 3, 4, 5])
+
+# Should use self as the enumerable source
+result = direct.async.map { |x| x * 2 }.to_a
+puts "  map result: #{result.inspect}"
+puts "  ✓ Direct collection works" if result == [2, 4, 6, 8, 10]
+
+puts "\n✅ Issue #7 is RESOLVED! All methods properly use the enumerable source."

data/scripts/test_method_source.rb

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/async/enumerable"
+
+e = [1, 2, 3].async
+puts "First async: #{e.class}"
+
+# Check which async method is defined
+puts "\nMethod owner: #{e.method(:async).owner}"
+puts "Method source location: #{e.method(:async).source_location.inspect}"
+
+# Check class methods
+puts "\nClass responds to enumerable_source? #{e.class.respond_to?(:enumerable_source)}"
+puts "Enumerable source: #{e.class.enumerable_source.inspect}" if e.class.respond_to?(:enumerable_source)