core-async 0.1.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f2c40406be47b9385d6252ddfc534383b817249c44aeda7e3410ea12d15afde
-  data.tar.gz: 48ee77b1bec473726d7deb3f35481c487e946c8fd00668c039d7556164bd70fc
+  metadata.gz: 5449a66653642c9fa6f96c2a968bda754e31aefdee4c207d1e3a02e18e7e7dcb
+  data.tar.gz: bc9e2ae806089f3a64cb3a3fa15d97505c5be54c0ca455577ddf3f6b1806f73b
 SHA512:
-  metadata.gz: 21f8e4bf33f14497c2080450f6ba4db0abde814ffbb86a3b0ed64f187edfd4c042830fcccd4c9044b5ff67d31bdf25904b2430bf715c02ea0334c7152cbe597d
-  data.tar.gz: b41c4e064774fc736814255aa5f92dfd160967c0370c7a5b76784418793a2550e0403beb6524e37b488ea76e9db25c7f1810b8919f699b9182a3268feaa44431
+  metadata.gz: 7fe6d3f541fd066a958453573f027a70321f0176e3db0b1e3afdb414841bcb8d7367414ccc1aa6ae06b97437ef2fc299fee761ab88661470d69bd7cffd2d9c88
+  data.tar.gz: a4786ac589bbb949c78ca6832e27b49abe79ed36b2b401529b0a56443404165e665d6f28aecdeeb9d1543e2f7e7c8ffba4ad05219fe5775e74d89fde750d2f9e

data/CHANGELOG.md

@@ -1,3 +1,44 @@
+## [v0.5.0](https://github.com/metabahn/corerb/releases/tag/2021-03-26)
+
+*released on 2021-03-26*
+
+  * `chg` [#25](https://github.com/metabahn/corerb/pull/25) Privatize async behavior ([bryanp](https://github.com/bryanp))
+  * `add` [#24](https://github.com/metabahn/corerb/pull/24) Add Is::Async#cancel ([bryanp](https://github.com/bryanp))
+  * `fix` [#23](https://github.com/metabahn/corerb/pull/23) Improve control flow during async enumeration / collection building ([bryanp](https://github.com/bryanp))
+  * `fix` [#22](https://github.com/metabahn/corerb/pull/22) Expose errors that occur when building a collection ([bryanp](https://github.com/bryanp))
+
+## [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*

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,68 @@
+# 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
+            errored, stopped = false
+
+            values = object.map { |value|
+              break if errored || stopped
+
+              async do
+                if block_given?
+                  yield value
+                else
+                  value
+                end
+              rescue LocalJumpError
+                stopped = true
+              rescue => error
+                errored = true
+                raise error
+              end
+            }
+
+            new(values) if 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,45 @@
+# 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, stopped = false
+
+          @object.each do |value|
+            break if errored || stopped
+
+            async do
+              yield value
+            rescue LocalJumpError
+              stopped = true
+            rescue => error
+              errored = true
+              raise error
+            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

@@ -33,7 +33,9 @@ module Core
           @runnable = ::Async::Reactor.new
 
           @runnable.run {
-            yield self
+            async {
+              yield self
+            }.result
           }.wait
         end
       end

data/lib/core/async/version.rb

@@ -2,7 +2,7 @@
 
 module Core
   module Async
-    VERSION = "0.1.0"
+    VERSION = "0.5.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,41 +1,69 @@
 # 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
+    private 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.
+    #
+    private 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)
+    private def sleep(seconds)
       internal_await do |task|
         task.sleep(seconds)
       end
@@ -45,7 +73,7 @@ module Is
     #
     # Raises `Core::Async::Timeout` if execution exceeds `seconds`.
     #
-    def timeout(seconds, &block)
+    private def timeout(seconds, &block)
       internal_await do |task|
         if seconds && seconds > 0
           task.with_timeout(seconds, Core::Async::Timeout) do
@@ -59,12 +87,31 @@ module Is
 
     # [public] Yields control to allow other fibers to execute.
     #
-    def defer
+    private def defer
       if (task = ::Async::Task.current?)
         task.yield
       end
     end
 
+    # [public] Cancels the current async behavior if in progress.
+    #
+    private def cancel
+      if (task = ::Async::Task.current?)
+        task.stop
+      end
+    end
+
+    # [public] Resolves a potential future to a final result.
+    #
+    private 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.5.0
 platform: ruby
 authors:
 - Bryan Powell
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-02-12 00:00:00.000000000 Z
+date: 2021-03-26 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: