core-async 0.0.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d07ba2a96ea37afd1f5abe0bb7a24182ef1b94e055b39cd2b4ad6cf08c420a5a
-  data.tar.gz: 893d9b5b72309cea17f9ca5cba0c840f9bfbacfb8d56e1db2b8df34c9cfd58ff
+  metadata.gz: c39a859a0ccc9ae393153098708feda94d76e34cf9c9ce07ce60833a1e94bc10
+  data.tar.gz: c9739940a35af9a076fbdd89742a698b7cf15d34670d44d2dcb0462820c85485
 SHA512:
-  metadata.gz: 04e6ebb9c4684fa2501d9b069fdcc4368d8c9cbdfa9294e5a379b423a9a1894ab8d05854a7bd8137cf2da061fdecaac859d7cc0466e631a704244c02a514763b
-  data.tar.gz: ed03928b876cd32a5df6f37f787400c2e4ef2db581b5e5de3c8c111734e5f53518675c35303ceb2a45e26af8f7b65cba4554ebfdd5d724e90d65ea15fdb0ef1f
+  metadata.gz: dfc642aeff2aaa6c38c9ac96615ca1fa6e1dc064557e230802accb58c4703c3d3785e9a39718833fd50b9fca8b2025c1410252108be2a794834531bda2956031
+  data.tar.gz: fdf13769d60a5a60c04c854a7c571f115f3434ec48b4706a218bc0a4b1b6cbd86bd8ee2e70a2fedf9fe54d3f4a39e1c16926ec08163c4054cea28e94315f4b7e

data/CHANGELOG.md

@@ -1,3 +1,43 @@
+## [v0.4.0](https://github.com/metabahn/corerb/releases/tag/2021-03-17.1)
+
+*released on 2021-03-17*
+
+  * `chg` [#21](https://github.com/metabahn/corerb/pull/21) Cancel async futures without waiting ([bryanp](https://github.com/bryanp))
+
+## [v0.3.0](https://github.com/metabahn/corerb/releases/tag/2021-03-17)
+
+*released on 2021-03-17*
+
+  * `add` [#20](https://github.com/metabahn/corerb/pull/20) Allow futures to be canceled ([bryanp](https://github.com/bryanp))
+
+## [v0.2.1](https://github.com/metabahn/corerb/releases/tag/2021-03-05)
+
+*released on 2021-03-05*
+
+  * `fix` [#18](https://github.com/metabahn/corerb/pull/18) Surface errors that occur in tasks running within an async reactor ([bryanp](https://github.com/bryanp))
+
+## [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*
+
+  * `chg` [#8](https://github.com/metabahn/corerb/pull/8) Wait for all async work to complete ([bryanp](https://github.com/bryanp))
+  * `add` [#7](https://github.com/metabahn/corerb/pull/7) Add Core::Async::Reactor ([bryanp](https://github.com/bryanp))
+  * `chg` [#6](https://github.com/metabahn/corerb/pull/6) Don't yield tasks from async and await ([bryanp](https://github.com/bryanp))
+
 ## [v0.0.0](https://github.com/metabahn/corerb/releases/tag/2020-12-17)
 
 *released on 2020-12-17*

data/lib/core/async.rb

@@ -1,7 +1,13 @@
 # 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
 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,141 @@
+# 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 future to resolve, returning self.
+      #
+      def wait
+        unless @error
+          resolve
+        end
+
+        self
+      end
+
+      # [public] Attempt to cancel the future, returns true if successful.
+      #
+      def cancel
+        if pending?
+          @task.stop
+        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 :stopped
+          :canceled
+        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 canceled.
+      #
+      def canceled?
+        status == :canceled
+      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/reactor.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "../../is/async"
+
+module Core
+  module Async
+    # [public] The top-level async context. Runs until all scheduled work is complete.
+    #
+    class Reactor
+      include Is::Async
+
+      class << self
+        # [public] Create a new reactor and immediately run it.
+        #
+        def run(&block)
+          instance = new
+          instance.run(&block)
+        end
+      end
+
+      # [public] Run the reactor, yielding within the async context.
+      #
+      def run
+        if (task = ::Async::Task.current?)
+          reference = task.async { |child|
+            @runnable = child
+
+            yield self
+          }
+
+          wait_all(reference)
+        else
+          @runnable = ::Async::Reactor.new
+
+          @runnable.run {
+            async {
+              yield self
+            }.result
+          }.wait
+        end
+      end
+
+      # [public] Stop the reactor.
+      #
+      def stop
+        @runnable&.stop
+      end
+    end
+  end
+end

data/lib/core/async/version.rb

@@ -2,7 +2,7 @@
 
 module Core
   module Async
-    VERSION = "0.0.0"
+    VERSION = "0.4.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,70 @@
 # 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 |task|
-        yield task
+      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?)
-        yield task
+        reference = task.async { |current|
+          begin
+            yield
+          ensure
+            current.yield
+          end
+        }
+
+        wait_all(reference)
       else
         ::Async::Reactor.run { |task|
-          yield 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)
-      await do |task|
+      internal_await do |task|
         task.sleep(seconds)
       end
     end
@@ -42,13 +74,13 @@ module Is
     # Raises `Core::Async::Timeout` if execution exceeds `seconds`.
     #
     def timeout(seconds, &block)
-      await do |task|
+      internal_await do |task|
         if seconds && seconds > 0
           task.with_timeout(seconds, Core::Async::Timeout) do
-            yield task
+            yield
           end
         else
-          yield task
+          yield
         end
       end
     end
@@ -60,5 +92,44 @@ module Is
         task.yield
       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
+      end
+    end
+
+    private def internal_await
+      if (task = ::Async::Task.current?)
+        reference = task.async {
+          yield task
+        }
+
+        wait_all(reference)
+      else
+        ::Async::Reactor.run { |task|
+          yield task
+        }.wait
+      end
+    end
+
+    private def wait_all(task)
+      task.children&.each do |child|
+        wait_all(child)
+      end
+
+      task.wait
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: core-async
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Bryan Powell
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-12-17 00:00:00.000000000 Z
+date: 2021-03-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.27'
+        version: '1.28'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.27'
+        version: '1.28'
 description: Makes Ruby objects async-aware.
 email: bryan@metabahn.com
 executables: []
@@ -33,8 +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:
@@ -55,7 +61,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.2.4
 signing_key:
 specification_version: 4
 summary: Makes Ruby objects async-aware.