opal-async 1.1.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a38a4215b9b7cdde96a1e4d00c08c5940bd829c052281b93ba7286c31bab856a
-  data.tar.gz: d329ce4369abd51128b468dc61fe26266fd96590688f55a6e2d934b631da831c
+  metadata.gz: bcf44d0cb1a3c702b3c60521a2e173b7a3824fd8a37e80cd0fb18d5c4e0ffc2c
+  data.tar.gz: 28e4364132c94e690752669a3211796ec2b3423314a0db4892348d92fb0beb46
 SHA512:
-  metadata.gz: 7d2373f2972e5402a14523f2975d544a2ba0faa4a2e68e527e4d27c3b327d279b687cccdda0b80ec34389149c0fa6d418e8faa04d9fc4b68f8f0ae96b679e1d4
-  data.tar.gz: 13b4c95d7c39c6f5d7a0497156e40f72fc01ae96f5e32707a09b230bc3c2e81d803aae4bfd94315f956b005b892855aacdf59670824b5de99e3aa15c530f36ff
+  metadata.gz: 695a85e00e549b7616d7bf120e8651d574c8d42cf58e4483fd7e0a7a36581942836457ad2bdb08a03232217f7bb92434a6fa75cbac217f5498e545186ae66430
+  data.tar.gz: e4a46e19095d1017f93574d52f40a47ff5dfd85b290ce0acb5a885e2500eec44813acdb2f3ea683ef6813711e0f8ccbb4c5beaae0969e3a908e0cb7bd51cf1ab

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Change Log
+
+## 1.4.0
+
+- Drop `Array#cycle` and `Array#each` overrides and re-implement as `Array#async_cycle` and `Array#async_each`
+- Asynchronous `Kernel#async_loop` alternative to `Kernel#loop`
+
+## 1.3.0
+
+- Asynchronous `Array#each` method that is web browser event loop friendly
+- `Thread#kill` and `Thread#stop` for partial-compatibility with Ruby `Thread`
+
+## 1.2.0
+
+- Asynchronous `Array#cycle` method that is web browser event loop friendly
+
+## 1.1.1
+
+- Added `Thread` class extension to enable using `Async::Task` as `Thread` in Opal
+
+## 1.1.0
+
+- Initial version

data/README.md

@@ -1,10 +1,11 @@
 # Opal: Async
+[![Gem Version](https://badge.fury.io/rb/opal-async.svg)](https://badge.fury.io/rb/opal-async)
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'opal-async', github: "ravenstine/opal-async
+    gem 'opal-async', '~> 1.3.0'
 
 And then execute:
 
@@ -14,12 +15,11 @@ Or install it yourself as:
 
     $ gem install opal-async
 
-Then require 'opal-async' in both your Opal code and your Opal compilation environment.
-
+Then require 'opal-async' in both your [Opal](https://opalrb.com/) code and your Opal compilation environment.
 
 ## Usage
 
-#### Enumerator
+### Enumerator
 
 The enumerator provides iteration methods for any enumerable object.  These methods are 'non-blocking', so other operations in the event loop can continue to be executed in between iterations.  Beware, this is not faster than a normal blocking iteration; it is trading off performance for not blocking other operations you may want to have continue such as UI updates & camera frame capture.  Very large arrays will take a long time to finish while the overhead may not be noticeable for smaller arrays.  It is best to do some tests and assess whether the trade-off is balanced enough for your needs.
 
@@ -43,21 +43,21 @@ enumerator.map{|x| x + 2}.each_slice(3).each{|x| puts x}
 #=> [9,10,11]
 ```
 
-##### Available enumerator methods:
+#### Available enumerator methods:
 - each
 - map
 - each_slice
 - select
 - reject
 
-#### Task
+### Task
 A task contains code that will be added to the call stack of the event loop.  The Enumerator uses tasks to run small chunks of code without blocking the event loop.  A task can do the same things that a Timeout or an Interval can do but with some added features and optimizations.
 
 With no options provided, a task will be run immediately once the event loop comes back to it(if the environment supports this).  If the environment does not support immediates, it will attempt to polyfill an immediate before falling back on a 0ms timeout.
 
-Example: 
+Example:
 
-```
+```ruby
 Async::Task.new do
   puts "hello world"
 end
@@ -67,7 +67,7 @@ end
 
 By default, a task will only run once.  To make a task repeat, set the option times to however many times you want the task to repeat.  You can also have access to countup and countdown variables.
 
-```
+```ruby
 Async::Task.new do times: 5 do |countup, countdown|
   puts countdown
 end
@@ -77,11 +77,11 @@ end
 #=> 3
 #=> 2
 #=> 1
-``` 
+```
 
 To make a task repeat infinitely, set times to ```:infinite```, or repeat to ```true```.  A countup will be provided but no countdown.  You can also use ```:i``` for short.
 
-```
+```ruby
 Async::Task.new times: :infinite do
   puts "forever"
 end
@@ -95,7 +95,7 @@ end
 
 The step option will determine how much you want your task to "step".
 
-```
+```ruby
 Async::Task.new times: 10, step: 2 do |countup, countdown|
   puts countup
 end
@@ -109,15 +109,15 @@ end
 
 To set a delay time on your task, specify the delay option with the number of milliseconds you want the duration of the delay to be.  This can also be done when you have set your task to repeat.
 
-```
+```ruby
 Async::Task.new delay: 1000 do
   puts "this took 1 second"
-end 
+end
 ```
 
 The delay and steps of a task can be modified within the execution of the task.  The following example will start out slow and increase in speed:
 
-```
+```ruby
 task = Async::Task.new times: 5, delay: 5000 do |countup, countdown|
   puts countdown
   task.delay = task.delay - 1000
@@ -128,7 +128,7 @@ Tasks also have callbacks that can be performed on certain events.
 
 Here is an example of how to execute code after a repeating task has finished:
 
-```
+```ruby
 task = Async::Task.new times: 3, delay: 1000 do |countup, countdown|
   puts countdown
 end
@@ -144,24 +144,101 @@ task.on_finish {puts "BOOM"}
 Other callbacks include ```on_start``` and ```on_stop```.
 
 
-#### Other Timers
+### Other Timers
 
-You can also timeouts and intervals specifically:
+You can also set timeouts and intervals, specifically:
 
 
-```
-Timeout.new 3000 do
+```ruby
+Async::Timeout.new 3000 do
   puts "I just waited 3 seconds."
 end
 ```
 
-```
-Interval.new 3000 do
+```ruby
+Async::Interval.new 3000 do
   puts "I'm going to do this every 3 seconds."
 end
 ```
 
+### Ruby Extensions
+
+[opal-async](https://rubygems.org/gems/opal-async) ships with some Opal Ruby extensions that enhance Ruby classes with asynchronous capabilities.
+
+You may activate all the Ruby extensions via this require statement:
+
+```ruby
+require 'async/ext'
+```
+
+#### Thread
+
+You may use the `Async::Task` class as a `Thread` class in Opal to perform asynchronous work with an extra `require` statement.
+
+```ruby
+require 'async/ext/thread' # not needed if you called `require 'async/ext'`
+
+Thread.new do
+  puts "hello world"
+end
+```
+
+#### Array
+
+The follow `Array` methods have been added to work asynchronously via `Async::Task`:
+- `Array#async_cycle`
+- `Array#async_each`
+
+This makes them not block the web browser event loop, thus allowing other tasks to update the DOM unhindered while running.
+
+Example:
+
+```ruby
+require 'async/ext/array' # not needed if you called `require 'async/ext'`
+
+Async::Task.new do
+  [1,2,3,4].async_cycle do |n|
+    puts n
+    Async::Task.new do
+      # make a DOM update that is not blocked
+    end
+    sleep(1)
+  end
+end
+```
+
+#### Kernel
+
+The follow `Kernel` method has been added to work asynchronously via `Async::Task`:
+- `Array#async_loop`
+
+This makes it not block the web browser event loop, thus allowing other tasks to update the DOM unhindered while running.
+
+Example:
+
+```ruby
+require 'async/ext/kernel' # not needed if you called `require 'async/ext'`
+
+Async::Task.new do
+  async_loop do
+    Async::Task.new do
+      # make a DOM update that is not blocked
+    end
+    sleep(1)
+  end
+end
+```
+
+## In The Wild
+
+opal-async is currently used in:
+- [Glimmer DSL for Opal](https://github.com/AndyObtiva/glimmer-dsl-opal)
+
+## Change Log
+
+[CHANGELOG.md](CHANGELOG.md)
+
 ## Contributors
 
 - [Benjamin Titcomb](https://github.com/Ravenstine) (Creator and Main Contributor)
-- [Andy Maleh](https://github.com/AndyObtiva) (Gemifier)
+- [Andy Maleh](https://github.com/AndyObtiva) (Gemifier and Maintainer)

data/VERSION

@@ -1 +1 @@
-1.1.0
+1.4.0

data/opal/async/ext.rb

@@ -0,0 +1,3 @@
+require 'async/ext/thread'
+require 'async/ext/array'
+require 'async/ext/kernel'

data/opal/async/ext/array.rb

@@ -0,0 +1,30 @@
+require 'async/task'
+
+class Array
+  def async_cycle(n=nil, &block)
+    array = self * n unless n.nil?
+    index = 0
+    looper = lambda do
+      if n.nil?
+        block.call(self[index])
+        index += 1
+        index = index % self.size
+        Async::Task.new(&looper)
+      else
+        block.call(array.shift)
+        Async::Task.new(&looper) unless array.empty?
+      end
+    end
+    Async::Task.new(&looper)
+  end
+  
+  def async_each(&block)
+    array = self
+    index = 0
+    looper = lambda do
+      block.call(array.shift)
+      Async::Task.new(&looper) unless array.empty?
+    end
+    Async::Task.new(&looper)
+  end
+end

data/opal/async/ext/kernel.rb

@@ -0,0 +1,11 @@
+require 'async/task'
+
+module Kernel
+  def async_loop(&block)
+    looper = lambda do
+      block.call
+      Async::Task.new(&looper)
+    end
+    Async::Task.new(&looper)
+  end
+end

data/opal/async/ext/thread.rb

@@ -0,0 +1,17 @@
+require 'thread' # bring the thread compatibility class from Opal first
+
+class Thread
+  def initialize(*args, &proc)
+    @async_task = Async::Task.new do
+      proc.call(*args)
+    end
+  end
+  
+  def stop
+    @async_task.stop
+  end
+  
+  def kill
+    @async_task.stop
+  end
+end

data/opal/async/task.rb

@@ -1,5 +1,23 @@
 module Async
   class Task
+    class << self
+      # returns general status of whether a task is running.
+      # Useful to code running in the task block to determine if it is running
+      # as part of a task or not and take special actions accordingly.
+      def started?
+        @@started = false unless defined? :@@started
+        @@started
+      end
+      
+      def start
+        @@started = true
+      end
+      
+      def stop
+        @@started = false
+      end
+    end
+  
     attr_accessor :delay, :times
     def initialize options={}, &block
       @options = options
@@ -15,6 +33,7 @@ module Async
       @delay = @options[:delay] || 0
       @times = @options[:times]
       @proc = Proc.new do
+        self.class.start
         if @times
           if @times.is_a?(Fixnum)
             @block.call(@countup, @countdown)
@@ -34,6 +53,7 @@ module Async
           @block.call
           @stopped = true
         end
+        self.class.stop
       end
     end
   
@@ -110,9 +130,9 @@ module Async
           };
           var mc = new MessageChannel();
   
-          mc.port1.onmessage = function(){ 
+          mc.port1.onmessage = function(){
             if (!#{stopped?}){
-              task.apply(task) 
+              task.apply(task)
             }
           };
           mc.port2.postMessage(null);

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: opal-async
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Ravenstine
 - Andy Maleh
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-06-20 00:00:00.000000000 Z
+date: 2021-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opal
@@ -101,6 +101,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake-tui
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Provides non-blocking tasks and enumerators for Opal.
 email:
 - benjamin@pixelstreetinc.com
@@ -108,9 +122,11 @@ email:
 executables: []
 extensions: []
 extra_rdoc_files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 - VERSION
@@ -119,6 +135,10 @@ files:
 - opal/async.rb
 - opal/async/countdown.rb
 - opal/async/enumerator.rb
+- opal/async/ext.rb
+- opal/async/ext/array.rb
+- opal/async/ext/kernel.rb
+- opal/async/ext/thread.rb
 - opal/async/interval.rb
 - opal/async/task.rb
 - opal/async/timeout.rb
@@ -127,7 +147,7 @@ homepage: http://github.com/AndyObtiva/opal-async
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options:
 - "--main"
 - README
@@ -147,8 +167,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.1.4
+signing_key:
 specification_version: 4
 summary: Provides non-blocking tasks and enumerators for Opal.
 test_files: []