core-async 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f2c40406be47b9385d6252ddfc534383b817249c44aeda7e3410ea12d15afde
-  data.tar.gz: 48ee77b1bec473726d7deb3f35481c487e946c8fd00668c039d7556164bd70fc
+  metadata.gz: 36564cdb777065399358b390e554b89b367902f9d065ed3def243a0816b17049
+  data.tar.gz: ec4cb82ad1b7a97d60af94fc4be07aca732f03f9fe5db91367d7628631d79bc7
 SHA512:
-  metadata.gz: 21f8e4bf33f14497c2080450f6ba4db0abde814ffbb86a3b0ed64f187edfd4c042830fcccd4c9044b5ff67d31bdf25904b2430bf715c02ea0334c7152cbe597d
-  data.tar.gz: b41c4e064774fc736814255aa5f92dfd160967c0370c7a5b76784418793a2550e0403beb6524e37b488ea76e9db25c7f1810b8919f699b9182a3268feaa44431
+  metadata.gz: 7cf03e8b149e9e0d5185d907025fd833c6d63074be1461970862ae138f3f3744e361422068d8bd4e8696f28fe459d65d7f3e2caa153c2b0f5b374f8d550e21da
+  data.tar.gz: 11b9a8ea0a25975bbf9f92ca7b41c1f0db6b2a7ae2ab0a16bbf6d3057d6d6add5875b30b3646e4028747f4eebb8863769fe8403a825c6e5a8a71cd25e677de22

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [v0.2.0](https://github.com/metabahn/corerb/releases/tag/2021-03-05)
+
+*released on 2021-03-05*
+
+  * `add` [#17](https://github.com/metabahn/corerb/pull/17) Add Core::Async::Collection for building async collections ([bryanp](https://github.com/bryanp))
+  * `add` [#16](https://github.com/metabahn/corerb/pull/16) Add Core::Async::Enumerator for async enumeration ([bryanp](https://github.com/bryanp))
+  * `add` [#15](https://github.com/metabahn/corerb/pull/15) Add Is::Async#resolve for resolving potential futures to final values ([bryanp](https://github.com/bryanp))
+  * `add` [#14](https://github.com/metabahn/corerb/pull/14) Add Is::Async#aware for guaranteeing an async context without nesting ([bryanp](https://github.com/bryanp))
+  * `fix` [#13](https://github.com/metabahn/corerb/pull/13) Correctly return the result from top-level await ([bryanp](https://github.com/bryanp))
+  * `fix` [#12](https://github.com/metabahn/corerb/pull/12) Resolve some edge-cases and bugs around raising top-level errors ([bryanp](https://github.com/bryanp))
+  * `chg` [#11](https://github.com/metabahn/corerb/pull/11) Raise an argument error when attempting to wrap a non-async-aware object ([bryanp](https://github.com/bryanp))
+  * `add` [#10](https://github.com/metabahn/corerb/pull/10) Add a pattern for making a call explicitly async ([bryanp](https://github.com/bryanp))
+  * `add` [#9](https://github.com/metabahn/corerb/pull/9) Introduce async futures ([bryanp](https://github.com/bryanp))
+
 ## [v0.1.0](https://github.com/metabahn/corerb/releases/tag/2021-02-11)
 
 *released on 2021-02-11*

data/lib/core/async.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
+require_relative "async/bootstrap"
+
 module Core
   module Async
+    require_relative "async/collection"
+    require_relative "async/enumerator"
+    require_relative "async/future"
     require_relative "async/reactor"
     require_relative "async/version"
   end

data/lib/core/async/bootstrap.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "async"
+Console.logger.off!

data/lib/core/async/collection.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "../../is/async"
+
+module Core
+  module Async
+    class Collection
+      class << self
+        include Is::Async
+
+        # [public] Builds a collection from an enumerable object.
+        #
+        def build(object)
+          aware do
+            values = object.map { |value|
+              async do
+                if block_given?
+                  yield value
+                else
+                  value
+                end
+              end
+            }
+
+            new(values)
+          end
+        end
+      end
+
+      include Enumerable
+      include Is::Async
+
+      def initialize(values = [])
+        unless values.respond_to?(:each)
+          raise ArgumentError, "values are not enumerable"
+        end
+
+        @values = values
+      end
+
+      # [public] Adds a value to the collection.
+      #
+      def <<(value)
+        @values << value
+      end
+      alias_method :add, :<<
+
+      # [public] Yields each resolved value.
+      #
+      def each
+        return to_enum(:each) unless block_given?
+
+        @values.each do |value|
+          yield resolve(value)
+        end
+      end
+    end
+  end
+end

data/lib/core/async/enumerator.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../../is/async"
+
+module Core
+  module Async
+    class Enumerator
+      include Enumerable
+      include Is::Async
+
+      def initialize(object)
+        unless object.respond_to?(:each)
+          raise ArgumentError, "object is not enumerable"
+        end
+
+        @object = object
+      end
+
+      # [public] Yields each value within its own async context, waiting on the enumeration to complete.
+      #
+      def each
+        unless block_given?
+          return to_enum(:each)
+        end
+
+        await do
+          errored = false
+          @object.each do |value|
+            break if errored
+
+            async {
+              begin
+                yield value
+              rescue => error
+                errored = true
+                raise error
+              ensure
+                defer
+              end
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/core/async/future.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Core
+  module Async
+    # [public] Represents a future result.
+    #
+    class Future
+      def initialize(task)
+        @task = task
+        @error = nil
+      end
+
+      # [public] Wait on the task to complete, returning self.
+      #
+      def wait
+        unless @error
+          resolve
+        end
+
+        self
+      end
+
+      # [public] Return the result, blocking until available.
+      #
+      def result
+        @error || @result ||= resolve
+      end
+
+      private def resolve
+        wait_all(@task)
+
+        resolve_value(@task.result)
+      rescue => error
+        @error = error
+
+        raise error
+      end
+
+      # [public] Return any error that occurred without re-raising, blocking until available.
+      #
+      def error
+        @error ||= get_error
+      end
+
+      private def get_error
+        result
+        nil
+      rescue => error
+        error
+      end
+
+      # [public] Return the status; one of :pending, :failed, or :complete.
+      #
+      def status
+        if defined?(@status)
+          @status
+        else
+          status = find_status
+          if terminal_status?(status)
+            @status = status
+          end
+
+          status
+        end
+      end
+
+      private def find_status
+        case @task.status
+        when :running
+          :pending
+        when :failed
+          :failed
+        when :complete
+          :complete
+        end
+      end
+
+      private def terminal_status?(status)
+        status == :failed || status == :complete
+      end
+
+      # [public] Return `true` if pending.
+      #
+      def pending?
+        status == :pending
+      end
+
+      # [public] Return `true` if failed.
+      #
+      def failed?
+        status == :failed
+      end
+
+      # [public] Return `true` if complete.
+      #
+      def complete?
+        status == :complete
+      end
+
+      # [public] Return `true` if failed or complete.
+      #
+      def resolved?
+        failed? || complete?
+      end
+
+      private def resolve_value(value)
+        if value.is_a?(self.class)
+          resolve_value(value.result)
+        else
+          value
+        end
+      end
+
+      private def wait_all(task)
+        task.children&.each do |child|
+          wait_all(child)
+        end
+
+        task.wait
+      end
+    end
+  end
+end

data/lib/core/async/version.rb

@@ -2,7 +2,7 @@
 
 module Core
   module Async
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
 
     def self.version
       VERSION

data/lib/core/async/wrapper.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Core
+  module Async
+    # [public] Wraps an object, calling all methods in an async context.
+    #
+    class Wrapper < BasicObject
+      def initialize(target)
+        unless target.respond_to?(:async)
+          ::Kernel.raise ::ArgumentError, "object is not async-aware"
+        end
+
+        @target = target
+      end
+
+      def method_missing(name, *args, &block)
+        @target.async do
+          @target.public_send(name, *args, &block)
+        end
+      end
+
+      ruby2_keywords(:method_missing) if respond_to?(:ruby2_keywords)
+
+      def respond_to_missing?(name, *)
+        true
+      end
+    end
+  end
+end

data/lib/is/async.rb

@@ -1,38 +1,66 @@
 # frozen_string_literal: true
 
-require "async"
-Console.logger.off!
-
+require_relative "../core/async/bootstrap"
+require_relative "../core/async/future"
 require_relative "../core/async/timeout"
+require_relative "../core/async/wrapper"
 
 module Is
   # [public] Makes Ruby objects async-aware.
   #
   module Async
-    # [public] Call asynchronous behavior in a proper async context.
+    # [public] Call behavior asychronously, returning a future.
     #
     def async
-      ::Async::Reactor.run do
-        yield
+      if block_given?
+        task = ::Async::Reactor.run { |current|
+          begin
+            yield
+          ensure
+            current.yield
+          end
+        }
+
+        Core::Async::Future.new(task)
+      else
+        Core::Async::Wrapper.new(self)
       end
     end
 
-    # [public] Call asynchronous behavior synchronously in a proper async context.
+    # [public] Call behavior synchronously but within an async context, waiting on the result.
     #
     def await
       if (task = ::Async::Task.current?)
-        reference = task.async {
-          yield
+        reference = task.async { |current|
+          begin
+            yield
+          ensure
+            current.yield
+          end
         }
 
         wait_all(reference)
       else
-        ::Async::Reactor.run {
-          yield
+        ::Async::Reactor.run { |task|
+          async {
+            yield
+          }.result
         }.wait
       end
     end
 
+    # [public] Call behavior within an async context without additional nesting.
+    #
+    def aware
+      if ::Async::Task.current?
+        yield
+      else
+        await do
+          yield
+        end
+      end
+    end
+
     # [public] Sleeps for `seconds` in a proper async context.
     #
     def sleep(seconds)
@@ -65,6 +93,17 @@ module Is
       end
     end
 
+    # [public] Resolves a potential future to a final result.
+    #
+    def resolve(value)
+      case value
+      when Core::Async::Future
+        value.result
+      else
+        value
+      end
+    end
+
     private def internal_async
       ::Async::Reactor.run do |task|
         yield task

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: core-async
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Bryan Powell
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-02-12 00:00:00.000000000 Z
+date: 2021-03-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -33,9 +33,14 @@ files:
 - CHANGELOG.md
 - LICENSE
 - lib/core/async.rb
+- lib/core/async/bootstrap.rb
+- lib/core/async/collection.rb
+- lib/core/async/enumerator.rb
+- lib/core/async/future.rb
 - lib/core/async/reactor.rb
 - lib/core/async/timeout.rb
 - lib/core/async/version.rb
+- lib/core/async/wrapper.rb
 - lib/is/async.rb
 homepage: https://github.com/metabahn/corerb/
 licenses: