libuv 2.0.12 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3392e84572469e65fb1505dc8ca99782acca89af
-  data.tar.gz: bf6311317ca08be77c06a503b4e23b5b574c83e9
+  metadata.gz: 328790a2659803772fb2ca5891889bda349b47fd
+  data.tar.gz: 0b534aaeeb7fd1fbfd11c35090e8f048be6db411
 SHA512:
-  metadata.gz: 64e492f11ddcac4a87cb3460459fc64bcbfa5484b8732346c18d03071d693c7a04281298edd32f851e3787fb3cccef87bc4af08ac06a55182f8f8eaef6e03e81
-  data.tar.gz: 7a4372cce3b02f884a29cb90a03b3a83bfde40d5b9487a1650185d52df53fb93668898e9a89954dc4c360b9b343f8371df121442d5a8523ad131eee2bc2e1714
+  metadata.gz: 00f0aed38c13defc6a2e310a67e81f576fad3d90308d00575982794e4bad6d0f95204b20d5f66db130984e22223c616bc02f78b3ffbefcc2d623c8efec9b1516
+  data.tar.gz: da08a1d126e8d25dd0bb8fa8d0deb3a25d05a369725362d2aa5a4fbf5254aa2d5db7f6ec7f10c8b70ad2f24f2f6924018c59259276e83fa4d22eae58554a4599

data/.gitignore

@@ -17,3 +17,5 @@ Gemfile-custom
 ext/*
 
 *.gem
+
+*.rdb

data/README.md

@@ -4,60 +4,93 @@
 
 [Libuv](https://github.com/libuv/libuv) is a cross platform asynchronous IO implementation that powers NodeJS. It supports sockets, both UDP and TCP, filesystem watch, TTY, Pipes and other asynchronous primitives like timer, check, prepare and idle.
 
-The Libuv gem contains Libuv and a Ruby wrapper that implements [pipelined promises](http://en.wikipedia.org/wiki/Futures_and_promises#Promise_pipelining) for asynchronous flow control and [coroutines](http://en.wikipedia.org/wiki/Coroutine) for untangling evented code
+The Libuv gem contains Libuv and a Ruby wrapper that implements [pipelined promises](http://en.wikipedia.org/wiki/Futures_and_promises#Promise_pipelining) for asynchronous flow control and [coroutines](http://en.wikipedia.org/wiki/Coroutine) / [futures](https://en.wikipedia.org/wiki/Futures_and_promises) for untangling evented code
 
 ## Usage
 
-using promises
+Libuv supports multiple reactors that can run on different threads.
+
+For convenience the thread local or default reactor can be accessed via the `reactor` method
+You can pass a block to be executed on the reactor and the reactor will run until there is nothing left to do.
 
 ```ruby
   require 'libuv'
 
-  loop = Libuv::Loop.default
-  # or
-  # loop = Libuv::Loop.new
-
-  loop.run do
-    timer = loop.timer do
+  reactor do |reactor|
+    reactor.timer {
       puts "5 seconds passed"
-      timer.close
-    end
-    timer.catch do |error|
-      puts "error with timer: #{error}"
-    end
-    timer.finally do
-      puts "timer handle was closed"
-    end
-    timer.start(5000)
+    }.start(5000)
   end
+
+  puts "reactor stopped. No more IO to process"
 ```
 
-using coroutines (if a somewhat abstract example)
+Promises are used to simplify code flow.
 
 ```ruby
   require 'libuv'
-  require 'libuv/coroutines'
 
-  loop = Libuv::Loop.default
-  loop.run do
-    begin
-      timer = loop.timer do
-        puts "5 seconds passed"
-        timer.close
-      end
-      timer.start(5000)
+  reactor do |reactor|
+    reactor.tcp { |data, socket|
+      puts "received: #{data}"
+      socket.close
+    }
+    .connect('127.0.0.1', 3000) { |socket|
+      socket.start_read
+            .write("GET / HTTP/1.1\r\n\r\n")
+    }
+    .catch { |error|
+      puts "error: #{error}"
+    }
+    .finally {
+      puts "socket closed"
+    }
+  end
+```
 
-      # co-routine waits for timer to close
-      co timer
+Continuations are used if callbacks are not defined
 
-      puts "timer handle was closed"
+```ruby
+  require 'libuv'
+
+  reactor do |reactor|
+    begin
+      reactor.tcp { |data, socket|
+        puts "received: #{data}"
+        socket.close
+      }
+      .connect('127.0.0.1', 3000)
+      .start_read
+      .write("GET / HTTP/1.1\r\n\r\n")
     rescue => error
-      puts "error with timer: #{error}"
+      puts "error: #{error}"
     end
   end
 ```
 
-Check out the [yard documentation](http://rubydoc.info/gems/libuv/Libuv/Loop)
+Any promise can be converted into a continuation
+
+```ruby
+  require 'libuv'
+
+  reactor do |reactor|
+    # Perform work on the thread pool with promises
+    reactor.work {
+      10 * 2
+    }.then { |result|
+      puts "result using a promise #{result}"
+    }
+
+    # Use the coroutine helper to obtain the result without a callback
+    result = reactor.work {
+      10 * 3
+    }.value
+    puts "no additional callbacks here #{result}"
+  end
+```
+
+
+Check out the [yard documentation](http://rubydoc.info/gems/libuv/Libuv/Reactor)
 
 
 ## Installation
@@ -107,6 +140,6 @@ Windows users will additionally require:
 * Filesystem Events
 * Filesystem manipulation
 * File manipulation
-* Errors (with a catch-all fallback for anything unhandled on the event loop)
+* Errors (with a catch-all fallback for anything unhandled on the event reactor)
 * Work queue (thread pool)
-* Coroutines (optional - makes use of Fibers)
+* Coroutines / futures (makes use of Fibers)

data/lib/libuv.rb

@@ -1,21 +1,28 @@
+# frozen_string_literal: true
+
 require 'forwardable'
+require 'thread'
 require 'ffi'
 
 module Libuv
+    DefaultThread = Thread.current
+
     require 'libuv/ext/ext'     # The libuv ffi ext
     require 'libuv/error'       # List of errors (matching those in uv.h)
     require 'libuv/q'           # The promise library
 
-    # -- The classes required for a loop instance --
+    # -- The classes required for a reactor instance --
     require 'libuv/mixins/assertions'  # Common code to check arguments
+    require 'libuv/mixins/accessors'   # Helper methods for accessing reactor functions
     require 'libuv/mixins/resource'    # Common code to check for errors
     require 'libuv/mixins/listener'    # Common callback code
 
     require 'libuv/handle'      # Base class for most libuv functionality
-    require 'libuv/prepare'     # Called at the end of a loop cycle
-    require 'libuv/async'       # Provide a threadsafe way to signal the event loop
+    require 'libuv/prepare'     # Called at the end of a reactor cycle
+    require 'libuv/async'       # Provide a threadsafe way to signal the event reactor
     require 'libuv/timer'       # High resolution timer
-    require 'libuv/loop'        # The libuv reactor or event loop
+    require 'libuv/reactor'        # The libuv reactor or event reactor
+    require 'libuv/coroutines'
     # --
 
     autoload :FsChecks, 'libuv/mixins/fs_checks'   # Common code to check file system results
@@ -25,7 +32,7 @@ module Libuv
     autoload :Filesystem, 'libuv/filesystem'  # Async directory manipulation
     autoload :FSEvent,    'libuv/fs_event'    # Notifies of changes to files and folders as they occur
     autoload :Signal,     'libuv/signal'      # Used to handle OS signals
-    autoload :Check,      'libuv/check'       # Called before processing events on the loop
+    autoload :Check,      'libuv/check'       # Called before processing events on the reactor
     autoload :File,       'libuv/file'        # Async file reading and writing
     autoload :Idle,       'libuv/idle'        # Called when there are no events to process
     autoload :Work,       'libuv/work'        # Provide work to be completed on another thread (thread pool)
@@ -52,4 +59,22 @@ module Libuv
             return nil
         end
     end
+
+    # Include all the accessors at this level
+    extend Accessors
+
+    # Run the default reactor
+    at_exit do
+        reactor = Reactor.default
+        reactor.run if $!.nil? && reactor.run_count == 0
+    end
+end
+
+
+class Object
+    private
+    
+    def reactor(&blk)
+        Libuv.reactor &blk
+    end
 end

data/lib/libuv/async.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Libuv
     class Async < Handle
 
@@ -5,14 +7,14 @@ module Libuv
         define_callback function: :on_async
 
 
-        # @param thread [::Libuv::Loop] loop this async callback will be associated
-        def initialize(thread, callback = nil, &blk)
-            @loop = thread
+        # @param reactor [::Libuv::Reactor] reactor this async callback will be associated
+        def initialize(reactor, callback = nil, &blk)
+            @reactor = reactor
             @callback = callback || blk
 
             async_ptr = ::Libuv::Ext.allocate_handle_async
             on_async = callback(:on_async, async_ptr.address)
-            error = check_result(::Libuv::Ext.async_init(loop.handle, async_ptr, on_async))
+            error = check_result(::Libuv::Ext.async_init(reactor.handle, async_ptr, on_async))
 
             super(async_ptr, error)
         end
@@ -22,13 +24,15 @@ module Libuv
             return if @closed
             error = check_result ::Libuv::Ext.async_send(handle)
             reject(error) if error
+            self
         end
 
         # Used to update the callback that will be triggered when async is called
         #
-        # @param callback [Proc] the callback to be called on loop prepare
+        # @param callback [Proc] the callback to be called on reactor prepare
         def progress(callback = nil, &blk)
             @callback = callback || blk
+            self
         end
 
 
@@ -36,11 +40,13 @@ module Libuv
 
 
         def on_async(handle)
-            begin
-                @callback.call
-            rescue Exception => e
-                @loop.log :error, :async_cb, e
-            end
+            ::Fiber.new {
+                begin
+                    @callback.call
+                rescue Exception => e
+                    @reactor.log e, 'performing async callback'
+                end
+            }.resume
         end
     end
 end

data/lib/libuv/check.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Libuv
     class Check < Handle
 
@@ -5,14 +7,14 @@ module Libuv
         define_callback function: :on_check
 
 
-        # @param loop [::Libuv::Loop] loop this check will be associated
-        # @param callback [Proc] callback to be called on loop check
-        def initialize(loop, callback = nil, &blk)
-            @loop = loop
+        # @param reactor [::Libuv::Reactor] reactor this check will be associated
+        # @param callback [Proc] callback to be called on reactor check
+        def initialize(reactor, callback = nil, &blk)
+            @reactor = reactor
             @callback = callback || blk
 
             check_ptr = ::Libuv::Ext.allocate_handle_check
-            error = check_result(::Libuv::Ext.check_init(loop.handle, check_ptr))
+            error = check_result(::Libuv::Ext.check_init(reactor.handle, check_ptr))
 
             super(check_ptr, error)
         end
@@ -22,6 +24,7 @@ module Libuv
             return if @closed
             error = check_result ::Libuv::Ext.check_start(handle, callback(:on_check))
             reject(error) if error
+            self
         end
 
         # Disables the check handler.
@@ -29,13 +32,15 @@ module Libuv
             return if @closed
             error = check_result ::Libuv::Ext.check_stop(handle)
             reject(error) if error
+            self
         end
 
-        # Used to update the callback that will be triggered on loop check
+        # Used to update the callback that will be triggered on reactor check
         #
-        # @param callback [Proc] the callback to be called on loop check
+        # @param callback [Proc] the callback to be called on reactor check
         def progress(callback = nil, &blk)
             @callback = callback || blk
+            self
         end
 
 
@@ -43,11 +48,13 @@ module Libuv
 
 
         def on_check(handle)
-            begin
-                @callback.call
-            rescue Exception => e
-                @loop.log :error, :check_cb, e
-            end
+            ::Fiber.new {
+                begin
+                    @callback.call
+                rescue Exception => e
+                    @reactor.log e, 'performing check callback'
+                end
+            }.resume
         end
     end
 end

data/lib/libuv/coroutines.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 require 'fiber'
 
-class ::Libuv::Loop
-    @@use_fibers = true
+class CoroutineRejection < RuntimeError
+    attr_accessor :value
 end
 
 class Object
@@ -15,32 +17,57 @@ class Object
     # @return [Object] Returns the result of a single promise or an array of results if provided multiple promises
     # @raise [Exception] if the promise is rejected
     def co(*yieldable, &block)
+        on_reactor = Libuv::Reactor.current
+        raise 'must be running on a reactor thread to use coroutines' unless on_reactor
+
         f = Fiber.current
         wasError = false
 
-        # Convert the input into a promise
+        # Convert the input into a promise on the current reactor
         if yieldable.length == 1
             promise = yieldable[0]
+            # Passed independently as this is often overwritten for performance
+            promise.progress(block) if block_given?
         else
-            promise = ::Libuv::Loop.current.all(*yieldable)
+            promise = on_reactor.all(*yieldable)
         end
 
         # Use the promise to resume the Fiber
         promise.then(proc { |res|
-            f.resume res
+            if Libuv::Reactor.current == on_reactor
+                f.resume res
+            else
+                on_reactor.schedule { f.resume(res) }
+            end
         }, proc { |err|
             wasError = true
-            f.resume err
+            if Libuv::Reactor.current == on_reactor
+                f.resume err
+            else
+                on_reactor.schedule { f.resume(err) }
+            end
         })
 
-        # Passed independently as this is often overwritten for performance
-        promise.progress(block) if block_given?
-
-        # Assign the result from the resume
-        result = Fiber.yield
+        # We want to prevent the reactor from stopping while we are waiting on a response
+        on_reactor.ref
+        result = Fiber.yield # Assign the result from the resume
+        on_reactor.unref
 
         # Either return the result or raise an error
-        raise result if wasError
+        if wasError
+            if result.is_a?(Exception)
+                raise result
+            else
+                e = case result
+                when String, Symbol
+                    CoroutineRejection.new(result.to_s)
+                else
+                    CoroutineRejection.new
+                end
+                e.value = result
+                raise e
+            end
+        end
         result
     end
 end

data/lib/libuv/dns.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Libuv
     class Dns < Q::DeferredPromise
         include Resource, Listener, Net
@@ -28,11 +30,11 @@ module Libuv
         end
 
 
-        # @param loop [::Libuv::Loop] loop this work request will be associated
+        # @param reactor [::Libuv::Reactor] reactor this work request will be associated
         # @param domain [String] the domain name to resolve
         # @param port [Integer, String] the port we wish to use
-        def initialize(loop, domain, port, hint = :IPv4)
-            super(loop, loop.defer)
+        def initialize(reactor, domain, port, hint = :IPv4, wait: true)
+            super(reactor, reactor.defer)
 
             @domain = domain
             @port = port
@@ -42,13 +44,15 @@ module Libuv
             @error = nil    # error in callback
 
             @instance_id = @pointer.address
-            error = check_result ::Libuv::Ext.getaddrinfo(@loop, @pointer, callback(:on_complete), domain, port.to_s, HINTS[hint])
+            error = check_result ::Libuv::Ext.getaddrinfo(@reactor, @pointer, callback(:on_complete), domain, port.to_s, HINTS[hint])
 
             if error
                 ::Libuv::Ext.free(@pointer)
                 @complete = true
                 @defer.reject(error)
             end
+
+            co(@defer.promise) if wait
         end
 
         # Indicates if the lookup has completed yet or not.
@@ -67,22 +71,25 @@ module Libuv
             ::Libuv::Ext.free(req)
 
             e = check_result(status)
-            if e
-                @defer.reject(e)
-            else
-                begin
-                    current = addrinfo
-                    @results = []
-                    while !current.null?
-                        @results << get_ip_and_port(current[:addr])
-                        current = current[:next]
-                    end
-                    @defer.resolve(@results)
-                rescue Exception => e
+
+            ::Fiber.new { 
+                if e
                     @defer.reject(e)
+                else
+                    begin
+                        current = addrinfo
+                        @results = []
+                        while !current.null?
+                            @results << get_ip_and_port(current[:addr])
+                            current = current[:next]
+                        end
+                        @defer.resolve(@results)
+                    rescue Exception => e
+                        @defer.reject(e)
+                    end
+                    ::Libuv::Ext.freeaddrinfo(addrinfo)
                 end
-                ::Libuv::Ext.freeaddrinfo(addrinfo)
-            end
+            }.resume
 
             # Clean up references
             cleanup_callbacks