libuv 2.0.12 → 3.0.0

data/lib/libuv/{loop.rb → reactor.rb}

@@ -1,19 +1,21 @@
+# frozen_string_literal: true
+
 require 'thread'
 
 module Libuv
-    class Loop
+    class Reactor
         include Resource, Assertions
+        extend Accessors
 
 
-        LOOPS = ThreadSafe::Cache.new
-        CRITICAL = Mutex.new
-        @@use_fibers = false
+        REACTORS = ::Concurrent::Map.new
+        CRITICAL = ::Mutex.new
 
 
         module ClassMethods
-            # Get default loop
+            # Get default reactor
             # 
-            # @return [::Libuv::Loop]
+            # @return [::Libuv::Reactor]
             def default
                 return @default unless @default.nil?
                 CRITICAL.synchronize {
@@ -21,55 +23,79 @@ module Libuv
                 }
             end
 
-            # Create new Libuv loop
+            # Create new Libuv reactor
             # 
-            # @return [::Libuv::Loop]
-            def new
-                return create(::Libuv::Ext.loop_new)
+            # @return [::Libuv::Reactor]
+            def new(&blk)
+                thread = create(::Libuv::Ext.loop_new)
+                if block_given?
+                    ::Thread.new do
+                        thread.run &blk
+                    end
+                end
+                thread
             end
 
-            # Build a Ruby Libuv loop from an existing loop pointer
+            # Build a Ruby Libuv reactor from an existing reactor pointer
             # 
-            # @return [::Libuv::Loop]
+            # @return [::Libuv::Reactor]
             def create(pointer)
                 allocate.tap { |i| i.send(:initialize, FFI::AutoPointer.new(pointer, ::Libuv::Ext.method(:loop_delete))) }
             end
 
-            # Checks for the existence of a loop on the current thread
+            # Checks for the existence of a reactor on the current thread
             #
-            # @return [::Libuv::Loop | nil]
+            # @return [::Libuv::Reactor | nil]
             def current
-                LOOPS[Thread.current]
+                REACTORS[Thread.current]
             end
         end
         extend ClassMethods
 
 
-        # Initialize a loop using an FFI::Pointer to a libuv loop
+        # Initialize a reactor using an FFI::Pointer to a libuv reactor
         def initialize(pointer) # :notnew:
             @pointer = pointer
-            @loop = self
+            @reactor = self
+            @run_count = 0
+            @ref_count = 0
 
             # Create an async call for scheduling work from other threads
             @run_queue = Queue.new
-            @process_queue = @loop.async method(:process_queue_cb)
+            @process_queue = @reactor.async method(:process_queue_cb)
             @process_queue.unref
 
             # Create a next tick timer
-            @next_tick = @loop.timer method(:next_tick_cb)
+            @next_tick = @reactor.timer method(:next_tick_cb)
             @next_tick.unref
 
-            # Create an async call for ending the loop
-            @stop_loop = @loop.async method(:stop_cb)
-            @stop_loop.unref
+            # Create an async call for ending the reactor
+            @stop_reactor = @reactor.async method(:stop_cb)
+            @stop_reactor.unref
 
             # Libuv can prevent the application shutting down once the main thread has ended
             # The addition of a prepare function prevents this from happening.
-            @loop_prep = Libuv::Prepare.new(@loop, method(:noop))
-            @loop_prep.unref
-            @loop_prep.start
+            @reactor_prep = Libuv::Prepare.new(@reactor, method(:noop))
+            @reactor_prep.unref
+            @reactor_prep.start
+
+            # LibUV ingnores program interrupt by default.
+            # We provide normal behaviour and allow this to be overriden
+            @on_signal = proc { stop_cb }
+            sig_callback = method(:signal_cb)
+            self.signal(:INT, sig_callback).unref
+            self.signal(:HUP, sig_callback).unref
+            self.signal(:TERM, sig_callback).unref
+
+            # Notify of errors
+            @throw_on_exit = nil
+            @reactor_notify = proc { |error|
+                @throw_on_exit = error
+            }
         end
 
+        attr_reader :run_count
+
 
         protected
 
@@ -77,12 +103,16 @@ module Libuv
         def noop; end
 
         def stop_cb
-            LOOPS.delete(@reactor_thread)
+            REACTORS.delete(@reactor_thread)
             @reactor_thread = nil
 
             ::Libuv::Ext.stop(@pointer)
         end
 
+        def signal_cb(_)
+            @on_signal.call
+        end
+
         def next_tick_cb
             @next_tick_scheduled = false
             @next_tick.unref
@@ -94,7 +124,8 @@ module Libuv
             length = @run_queue.length
             update_time
             length.times do
-                process_item
+                # This allows any item to pause its execution without effecting this loop
+                ::Fiber.new { process_item }.resume
             end
         end
 
@@ -103,7 +134,7 @@ module Libuv
                 run = @run_queue.pop true  # pop non-block
                 run.call
             rescue Exception => e
-                @loop.log :error, :next_tick_cb, e
+                @reactor.log e, 'performing next tick callback'
             end
         end
 
@@ -120,47 +151,76 @@ module Libuv
 
         def handle; @pointer; end
 
-        # Run the actual event loop. This method will block until the loop is stopped.
+        # Run the actual event reactor. This method will block until the reactor is stopped.
         #
         # @param run_type [:UV_RUN_DEFAULT, :UV_RUN_ONCE, :UV_RUN_NOWAIT]
         # @yieldparam promise [::Libuv::Q::Promise] Yields a promise that can be used for logging unhandled
-        #   exceptions on the loop.
+        #   exceptions on the reactor.
         def run(run_type = :UV_RUN_DEFAULT)
             if @reactor_thread.nil?
-                @loop_notify = @loop.defer
-
                 begin
-                    @reactor_thread = Thread.current
-                    LOOPS[@reactor_thread] = @loop
+                    @reactor_thread = ::Thread.current
+                    raise 'only one reactor allowed per-thread' if REACTORS[@reactor_thread]
+
+                    REACTORS[@reactor_thread] = @reactor
+                    @throw_on_exit = nil
+
                     if block_given?
                         update_time
-                        if @@use_fibers
-                            Fiber.new { yield @loop_notify.promise }.resume
-                        else
-                            yield @loop_notify.promise
-                        end
+                        ::Fiber.new {
+                            begin
+                                yield @reactor
+                            rescue Exception => e
+                                log(e, 'in reactor run block')
+                            end
+                        }.resume
                     end
+                    @run_count += 1
                     ::Libuv::Ext.run(@pointer, run_type)  # This is blocking
                 ensure
+                    REACTORS.delete(@reactor_thread)
                     @reactor_thread = nil
                     @run_queue.clear
                 end
+
+                # Raise the last unhandled error to occur on the reactor thread
+                raise @throw_on_exit if @throw_on_exit
+
             elsif block_given?
-                if @@use_fibers
-                    schedule { Fiber.new { yield @loop_notify.promise }.resume }
+                if reactor_thread?
+                    update_time
+                    yield @reactor
                 else
-                    schedule { yield @loop_notify.promise }
+                    raise 'reactor already running on another thread'
                 end
             end
-            @loop
+
+            @reactor
+        end
+
+        # Prevents the reactor loop from stopping
+        def ref
+            if reactor_thread? && reactor_running?
+                @process_queue.ref if @ref_count == 0
+                @ref_count += 1
+            end
+        end
+
+        # Allows the reactor loop to stop
+        def unref
+            if reactor_thread? && reactor_running? && @ref_count > 0
+                @ref_count -= 1
+                @process_queue.unref if @ref_count == 0
+            end
         end
 
 
         # Provides a promise notifier for receiving un-handled exceptions
         #
         # @return [::Libuv::Q::Promise]
-        def notifier
-            @loop_notify.promise
+        def notifier(callback = nil, &blk)
+            @reactor_notify = callback || blk
+            self
         end
 
         # Creates a deferred result object for where the result of an operation may only be returned 
@@ -168,7 +228,7 @@ module Libuv
         #
         # @return [::Libuv::Q::Deferred]
         def defer
-            Q.defer(@loop)
+            Q.defer(@reactor)
         end
 
         # Combines multiple promises into a single promise that is resolved when all of the input
@@ -180,7 +240,7 @@ module Libuv
         #   the promises is resolved with a rejection, this resulting promise will be resolved with the
         #   same rejection.
         def all(*promises)
-            Q.all(@loop, *promises)
+            Q.all(@reactor, *promises)
         end
 
         #
@@ -190,7 +250,7 @@ module Libuv
         # @param *promises [::Libuv::Q::Promise] a number of promises that will be combined into a single promise
         # @return [::Libuv::Q::Promise] Returns a single promise
         def any(*promises)
-            Q.any(@loop, *promises)
+            Q.any(@reactor, *promises)
         end
 
         #
@@ -201,15 +261,16 @@ module Libuv
         # @return [::Libuv::Q::Promise] Returns a single promise that will be resolved with an array of values,
         #   each [result, wasResolved] value pair corresponding to a at the same index in the `promises` array.
         def finally(*promises)
-            Q.finally(@loop, *promises)
+            Q.finally(@reactor, *promises)
         end
         
 
-        # forces loop time update, useful for getting more granular times
+        # forces reactor time update, useful for getting more granular times
         # 
         # @return nil
         def update_time
             ::Libuv::Ext.update_time(@pointer)
+            self
         end
 
         # Get current time in milliseconds
@@ -228,28 +289,30 @@ module Libuv
 
             if name
                 msg  = ::Libuv::Ext.strerror(err)
-                ::Libuv::Error.const_get(name.to_sym).new(msg)
+                ::Libuv::Error.const_get(name.to_sym).new("#{msg}, #{name}:#{err}")
             else
                 # We want a back-trace in this case
                 raise "error lookup failed for code #{err}"
             end
         rescue Exception => e
-            @loop.log :warn, :error_lookup_failed, e
+            @reactor.log e, 'performing error lookup'
             e
         end
 
         # Get a new TCP instance
         # 
         # @return [::Libuv::TCP]
-        def tcp
-            TCP.new(@loop)
+        def tcp(callback = nil, &blk)
+            callback ||= blk
+            TCP.new(@reactor, progress: callback)
         end
 
         # Get a new UDP instance
         #
         # @return [::Libuv::UDP]
-        def udp
-            UDP.new(@loop)
+        def udp(callback = nil, &blk)
+            callback ||= blk
+            UDP.new(@reactor, progress: callback)
         end
 
         # Get a new TTY instance
@@ -260,7 +323,7 @@ module Libuv
         def tty(fileno, readable = false)
             assert_type(Integer, fileno, "io#fileno must return an integer file descriptor, #{fileno.inspect} given")
 
-            TTY.new(@loop, fileno, readable)
+            TTY.new(@reactor, fileno, readable)
         end
 
         # Get a new Pipe instance
@@ -268,7 +331,7 @@ module Libuv
         # @param ipc [true, false] indicate if a handle will be used for ipc, useful for sharing tcp socket between processes
         # @return [::Libuv::Pipe]
         def pipe(ipc = false)
-            Pipe.new(@loop, ipc)
+            Pipe.new(@reactor, ipc)
         end
 
         # Get a new timer instance
@@ -276,21 +339,21 @@ module Libuv
         # @param callback [Proc] the callback to be called on timer trigger
         # @return [::Libuv::Timer]
         def timer(callback = nil, &blk)
-            Timer.new(@loop, callback || blk)
+            Timer.new(@reactor, callback || blk)
         end
 
         # Get a new Prepare handle
         # 
         # @return [::Libuv::Prepare]
         def prepare(callback = nil, &blk)
-            Prepare.new(@loop, callback || blk)
+            Prepare.new(@reactor, callback || blk)
         end
 
         # Get a new Check handle
         # 
         # @return [::Libuv::Check]
         def check(callback = nil, &blk)
-            Check.new(@loop, callback || blk)
+            Check.new(@reactor, callback || blk)
         end
 
         # Get a new Idle handle
@@ -298,7 +361,7 @@ module Libuv
         # @param callback [Proc] the callback to be called on idle trigger
         # @return [::Libuv::Idle]
         def idle(callback = nil, &block)
-            Idle.new(@loop, callback || block)
+            Idle.new(@reactor, callback || block)
         end
 
         # Get a new Async handle
@@ -306,7 +369,7 @@ module Libuv
         # @return [::Libuv::Async]
         def async(callback = nil, &block)
             callback ||= block
-            handle = Async.new(@loop)
+            handle = Async.new(@reactor)
             handle.progress callback if callback
             handle
         end
@@ -316,12 +379,18 @@ module Libuv
         # @return [::Libuv::Signal]
         def signal(signum = nil, callback = nil, &block)
             callback ||= block
-            handle = Signal.new(@loop)
+            handle = Signal.new(@reactor)
             handle.progress callback if callback
             handle.start(signum) if signum
             handle
         end
 
+        # Allows user defined behaviour when sig int is received
+        def on_program_interrupt(callback = nil, &block)
+            @on_signal = callback || block
+            self
+        end
+
         # Queue some work for processing in the libuv thread pool
         #
         # @param callback [Proc] the callback to be called in the thread pool
@@ -330,7 +399,7 @@ module Libuv
         def work(callback = nil, &block)
             callback ||= block
             assert_block(callback)
-            Work.new(@loop, callback)    # Work is a promise object
+            Work.new(@reactor, callback)    # Work is a promise object
         end
 
         # Lookup a hostname
@@ -339,10 +408,14 @@ module Libuv
         # @param port [Integer, String] the service being connected too
         # @param callback [Proc] the callback to be called on success
         # @return [::Libuv::Dns]
-        def lookup(hostname, hint = :IPv4, port = 9, &block)
-            dns = Dns.new(@loop, hostname, port, hint)    # Work is a promise object
-            dns.then block if block_given?
-            dns
+        def lookup(hostname, hint = :IPv4, port = 9, wait: true, &block)
+            dns = Dns.new(@reactor, hostname, port, hint, wait: wait)    # Work is a promise object
+            if block_given? || !wait
+                dns.then block
+                dns
+            else
+                dns.results
+            end
         end
 
         # Get a new FSEvent instance
@@ -352,7 +425,7 @@ module Libuv
         # @raise [ArgumentError] if path is not a string
         def fs_event(path)
             assert_type(String, path)
-            FSEvent.new(@loop, path)
+            FSEvent.new(@reactor, path)
         end
 
         # Opens a file and returns an object that can be used to manipulate it
@@ -361,21 +434,21 @@ module Libuv
         # @param flags [Integer] see ruby File::Constants
         # @param mode [Integer]
         # @return [::Libuv::File]
-        def file(path, flags = 0, mode = 0)
+        def file(path, flags = 0, mode: 0, **opts, &blk)
             assert_type(String, path, "path must be a String")
             assert_type(Integer, flags, "flags must be an Integer")
             assert_type(Integer, mode, "mode must be an Integer")
-            File.new(@loop, path, flags, mode)
+            File.new(@reactor, path, flags, mode: mode, **opts, &blk)
         end
 
         # Returns an object for manipulating the filesystem
         #
         # @return [::Libuv::Filesystem]
         def filesystem
-            Filesystem.new(@loop)
+            Filesystem.new(@reactor)
         end
 
-        # Schedule some work to be processed on the event loop as soon as possible (thread safe)
+        # Schedule some work to be processed on the event reactor as soon as possible (thread safe)
         #
         # @param callback [Proc] the callback to be called on the reactor thread
         # @raise [ArgumentError] if block is not given
@@ -389,9 +462,11 @@ module Libuv
                 @run_queue << callback
                 @process_queue.call
             end
+
+            self
         end
 
-        # Queue some work to be processed in the next iteration of the event loop (thread safe)
+        # Queue some work to be processed in the next iteration of the event reactor (thread safe)
         #
         # @param callback [Proc] the callback to be called on the reactor thread
         # @raise [ArgumentError] if block is not given
@@ -410,27 +485,29 @@ module Libuv
             else
                 @process_queue.call
             end
+
+            self
         end
 
-        # Notifies the loop there was an event that should be logged
+        # Notifies the reactor there was an event that should be logged
         #
-        # @param level [Symbol] the error level (info, warn, error etc)
-        # @param id [Object] some kind of identifying information
-        # @param *args [*args] any additional information
-        def log(level, id, *args)
-            @loop_notify.notify(level, id, *args)
+        # @param error [Exception] the error
+        # @param msg [String|nil] optional context on the error
+        # @param trace [Array<String>] optional additional trace of caller if async
+        def log(error, msg = nil, trace = nil)
+            @reactor_notify.call(error, msg, trace)
         end
 
-        # Closes handles opened by the loop class and completes the current loop iteration (thread safe)
+        # Closes handles opened by the reactor class and completes the current reactor iteration (thread safe)
         def stop
-            @stop_loop.call
+            @stop_reactor.call
         end
 
         # True if the calling thread is the same thread as the reactor.
         #
         # @return [Boolean]
         def reactor_thread?
-            @reactor_thread == Thread.current
+            @reactor_thread == ::Thread.current
         end
 
         # Exposed to allow joining on the thread, when run in a multithreaded environment. Performing other actions on the thread has undefined semantics (read: a dangerous endevor).
@@ -438,11 +515,12 @@ module Libuv
         # @return [Thread]
         attr_reader :reactor_thread
 
-        # Tells you whether the Libuv reactor loop is currently running.
+        # Tells you whether the Libuv reactor reactor is currently running.
         #
         # @return [Boolean]
         def reactor_running?
             !@reactor_thread.nil?
         end
+        alias_method :running?, :reactor_running?
     end
 end