wires 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ed1477b941ed3c64b10f1d6d7f0087fc17f07aad
-  data.tar.gz: db91d0d10df1770328f942a8f4febe4be4c90502
+  metadata.gz: f6ef896589b7b29bffcde2800b2a0205c993bf70
+  data.tar.gz: 849f9147f51646922d9148fdae2d592dc3998fc2
 SHA512:
-  metadata.gz: d179bf2b1d6d0642ef84483c9f8521f49f8628bd676dd11a87da1d9108da152827ed657887e43dd6458ddaa10eb7b027941644578243844c8370249584dfb20c
-  data.tar.gz: f88af8249cceebf4774de1ba33e60bb9f203d5d0da6f13fdadb128ea0fc244cbb35bb717e50c0f573b3feea95dcf73418897bc8122236e612fa85ce0d20ccda5
+  metadata.gz: a27d75fe9e4020189e732e04e93cc6e22493390b7b28ebe616d31420a97d18e1a3c56a43b940a2030f75dfba27e396ea0762965dad59f47496bc0f2d8c40b6d9
+  data.tar.gz: ba4092b89082a0fd4f6da1af2aa7664eca682a6017e6cb5ebaa00b7d8e8804305b6f1f26107fb2eba318807456a08353f09ca5c34b7d5feef88ed316b022adec

data/lib/wires/base.rb

@@ -48,9 +48,11 @@ loader.call 'base/util/hooks'
 loader.call 'base/util/router_table'
 
 loader.call 'base/event'
+loader.call 'base/future'
 loader.call 'base/launcher'
 loader.call 'base/router'
 loader.call 'base/channel'
+loader.call 'base/channel/sync_helper'
 loader.call 'base/time_scheduler_item'
 loader.call 'base/time_scheduler'
 loader.call 'base/convenience'

data/lib/wires/base/channel.rb

@@ -263,6 +263,10 @@ module Wires.current_network::Namespace
         end
       end
       
+      procs.map! do |pr|
+        Future.new &pr
+      end
+      
       # Fire to selected targets
       threads = procs.uniq.map do |pr|
         Launcher.spawn \
@@ -330,103 +334,6 @@ module Wires.current_network::Namespace
       nil
     end
     
-    # Helper class passed to user block in {Channel#sync_on} method.
-    #   Read here for how to use the helper, but never instantiate it yourself.
-    class SyncHelper
-      
-      # Don't instantiate this class directly, use {Channel#sync_on}
-      # @api private
-      def initialize(events, channel, timeout:nil)
-        @timeout = timeout
-        @lock, @cond = Mutex.new, ConditionVariable.new
-        @conditions = []
-        @executions = []
-        @received   = []
-        @thread     = Thread.current
-        
-        # Create the temporary event handler to capture incoming matches
-        proc = Proc.new do |e,c|
-          if Thread.current==@thread
-            snag e,c
-          else
-            @lock.synchronize { snag e,c }
-          end
-        end
-        
-        # Run the user block within the lock and wait afterward if they didn't
-        @lock.synchronize {
-          channel.register events, &proc
-          yield self
-          wait unless @waited
-          channel.unregister &proc
-        }
-      end
-      
-      # Add a condition which must be fulfilled for {#wait} to find a match.
-      #
-      # @param block [Proc] the block specifiying the condition to be met.
-      #   It will be passed the event and channel, and the truthiness of its
-      #   return value will be evaluated to determine if the condition is met.
-      #   It will only be executed if the +[event,channel]+ pair fits the 
-      #   filter and meets all of the other evaluated conditions so far.
-      #    
-      def condition(&block)
-        @conditions << block if block
-        nil
-      end
-      
-      # Add a execution to run on the matching event for each {#wait}.
-      #
-      # @param block [Proc] the block to be executed.
-      #   It will only be executed if the +[event,channel]+ pair fits the 
-      #   filter and met all of the conditions to fulfill the {#wait}.
-      #   The block will not be run if the {#wait} times out.
-      #
-      def execute(&block)
-        @executions << block if block
-        nil
-      end
-      
-      # Wait for exactly one matching event meeting all {#condition}s to come.
-      #
-      # @note This will be called once implicitly at the end of the user block
-      #   unless it gets called explicitly somewhere within the user block.
-      #   It can be called multiple times within the user block to require
-      #   one matching event each time within the block.
-      #
-      # @param timeout [Fixnum] The maximum time to wait for a match, 
-      #   specified in seconds.  By default, it will be the number used at
-      #   instantiation (passed from {Channel#sync_on}).
-      #
-      # @return the matching {Event} object, or nil if timed out.
-      #
-      def wait(timeout=@timeout)
-        @waited = true
-        result = nil
-        
-        # Loop through each result, making sure it matches the conditions,
-        #   returning nil if the wait timed out and didn't push into @received
-        loop do
-          @cond.wait @lock, timeout if @received.empty?
-          result = @received.pop
-          return nil unless result
-          break if !@conditions.detect { |blk| !blk.call *result }
-        end
-        
-        # Run all the execute blocks on the result
-        @executions.each { |blk| blk.call *result }
-        result.first #=> return event
-      end
-      
-    private
-      
-      # Snag the given event and channel to try it out in the blocking thread
-      def snag(*args)
-        @received << args
-        @cond.signal # Pass execution back to blocking thread and block this one
-      end
-    end
-    
     # Determine if one channel matches another.
     # 
     # In this context, a match indicates a receiver relationship.

data/lib/wires/base/channel/sync_helper.rb

@@ -0,0 +1,104 @@
+
+module Wires.current_network::Namespace
+  
+  class Channel
+    
+    # Helper class passed to user block in {Channel#sync_on} method.
+    #   Read here for how to use the helper, but never instantiate it yourself.
+    class SyncHelper
+      
+      # Don't instantiate this class directly, use {Channel#sync_on}
+      # @api private
+      def initialize(events, channel, timeout:nil)
+        @timeout = timeout
+        @lock, @cond = Mutex.new, ConditionVariable.new
+        @conditions = []
+        @executions = []
+        @received   = []
+        @thread     = Thread.current
+        
+        # Create the temporary event handler to capture incoming matches
+        proc = Proc.new do |e,c|
+          if Thread.current==@thread
+            snag e,c
+          else
+            @lock.synchronize { snag e,c }
+          end
+        end
+        
+        # Run the user block within the lock and wait afterward if they didn't
+        @lock.synchronize {
+          channel.register events, &proc
+          yield self
+          wait unless @waited
+          channel.unregister &proc
+        }
+      end
+      
+      # Add a condition which must be fulfilled for {#wait} to find a match.
+      #
+      # @param block [Proc] the block specifiying the condition to be met.
+      #   It will be passed the event and channel, and the truthiness of its
+      #   return value will be evaluated to determine if the condition is met.
+      #   It will only be executed if the +[event,channel]+ pair fits the 
+      #   filter and meets all of the other evaluated conditions so far.
+      #    
+      def condition(&block)
+        @conditions << block if block
+        nil
+      end
+      
+      # Add a execution to run on the matching event for each {#wait}.
+      #
+      # @param block [Proc] the block to be executed.
+      #   It will only be executed if the +[event,channel]+ pair fits the 
+      #   filter and met all of the conditions to fulfill the {#wait}.
+      #   The block will not be run if the {#wait} times out.
+      #
+      def execute(&block)
+        @executions << block if block
+        nil
+      end
+      
+      # Wait for exactly one matching event meeting all {#condition}s to come.
+      #
+      # @note This will be called once implicitly at the end of the user block
+      #   unless it gets called explicitly somewhere within the user block.
+      #   It can be called multiple times within the user block to require
+      #   one matching event each time within the block.
+      #
+      # @param timeout [Fixnum] The maximum time to wait for a match, 
+      #   specified in seconds.  By default, it will be the number used at
+      #   instantiation (passed from {Channel#sync_on}).
+      #
+      # @return the matching {Event} object, or nil if timed out.
+      #
+      def wait(timeout=@timeout)
+        @waited = true
+        result = nil
+        
+        # Loop through each result, making sure it matches the conditions,
+        #   returning nil if the wait timed out and didn't push into @received
+        loop do
+          @cond.wait @lock, timeout if @received.empty?
+          result = @received.pop
+          return nil unless result
+          break if !@conditions.detect { |blk| !blk.call *result }
+        end
+        
+        # Run all the execute blocks on the result
+        @executions.each { |blk| blk.call *result }
+        result.first #=> return event
+      end
+      
+    private
+      
+      # Snag the given event and channel to try it out in the blocking thread
+      def snag(*args)
+        @received << args
+        @cond.signal # Pass execution back to blocking thread and block this one
+      end
+    end
+    
+  end
+end

data/lib/wires/base/future.rb

@@ -0,0 +1,133 @@
+
+module Wires.current_network::Namespace
+  
+  # In this context, a {Future} is thread-safe container for a {#codeblock}
+  # and for the {#result} produced when it is {#execute}d.
+  #
+  # Call {#execute} to run the block in place, or {#start} to {#execute} in
+  # a new thread.  After {#execute} is done, the {#result} will be available.
+  # Calling {#result} will block if {#execute} has not yet finished.
+  # The block is guaranteed to run at most one time, so any subsequent 
+  # calls to {#execute} will merely return the existing {#result}.
+  # If running the block again is desired, use {#dup} to create a new {Future}
+  # with the same {#codeblock}.
+  #
+  #   future = Future.new { |*args| expensive_operation *args }
+  #   future.start 1,2,3 # Run expensive_operation in a thread with args=1,2,3
+  #   # ...
+  #   puts future.result # Block until expensive_operation is done and print result
+  #
+  # @note Primarily, {Future} is included in this library for the return value
+  #   of {Launcher.spawn} (and, by extension, {Channel#fire}), but users should
+  #   feel free to use it's documented API for other purposes as well.
+  #
+  class Future
+    
+    # The block passed at {#initialize} to be run when {#execute} is called.
+    # It will be run at most one time.
+    #
+    attr_reader :codeblock
+    
+    # @param codeblock [Proc] The code block to run when {#execute} is called.
+    # @raise [ArgumentError] If +codeblock+ is not given.
+    #
+    def initialize &codeblock
+      raise ArgumentError, "Future must be instantiated with a block" \
+        unless codeblock
+      
+      @codeblock = codeblock
+      @state     = :initial
+      @result    = nil
+      @statelock = Mutex.new
+      @cond      = ConditionVariable.new
+    end
+    
+    # Run {#execute} in a new +Thread+. If {#execute} raises an +Exception+,
+    # it will be rescued at the top level of the +Thread+, but will be raised
+    # when {#result} is called.
+    #
+    # @param args The arguments to pass to {#codeblock} in {#execute}.
+    # @param block The block argument to pass to {#codeblock} in {#execute}.
+    # @return [Thread] The spawned +Thread+.
+    #
+    def start *args, &block
+      Thread.new do
+        begin
+          execute *args, &block
+        rescue Exception
+          # Exceptions get raised through when #result is called.
+        end
+      end
+    end
+    
+    # Run the {#codeblock} passed to {#initialize} with the given arguments.
+    #
+    # If the {#codeblock} has already been {#execute}d, it won't be run again;
+    # instead, the result returned by the first call will be returned again.
+    #
+    # @param args The arguments to pass to {#codeblock}.
+    # @param block The block argument to pass to {#codeblock}.
+    # @return The return value of the call to {#codeblock}.
+    # @raise The exception raised by the call to {#codeblock}, if any.
+    #
+    def execute *args, &block
+      @statelock.synchronize do
+        return @result if @state == :complete
+        @state = :running
+        
+        begin
+          @codeblock.call(*args, &block).tap do |result|
+            @result = result
+            @state  = :complete
+          end
+        rescue Exception => exception
+          @result = exception
+          @state  = :exception
+          raise exception
+        ensure
+          @cond.broadcast
+        end
+      end
+    end
+    alias call execute
+    
+    # Get the return value of the call to {#codeblock}.
+    #
+    # If {#execute} has not yet been called, or if it is still {#running?},
+    # {#result} will block until the {#codeblock} has been run.
+    #
+    # @return The return value of the call to {#codeblock}.
+    # @raise The exception raised by the call to {#codeblock}, if any.
+    #
+    def result
+      @statelock.synchronize do
+        @cond.wait @statelock unless complete?
+        @state==:exception ? raise(@result) : @result
+      end
+    end
+    alias join result
+    
+    # @return [Boolean]
+    #   +true+ if {#codeblock} is currently executing, else +false+.
+    def running?;  @state == :running;  end
+    alias executing? running?
+    
+    # @return [Boolean]
+    #   +true+ if {#codeblock} has already executed, else +false+.
+    def complete?; @state == :complete || @state == :exception; end
+    alias ready? complete?
+    
+    # Duplicate the Future, without copying its {#running?}/{#complete?} state.
+    # This is the preferred way to "reuse" a {Future}, because each {Future}
+    # is guaranteed to run at most one time.  It is the same as creating a
+    # new {Future} with the same {#codeblock} object passed to {#initialize}.
+    #
+    # @return [Future] A new {Future} with the same {#codeblock}.
+    #
+    def dup
+      self.class.new &@codeblock
+    end
+    
+  end
+  
+end

data/lib/wires/base/launcher.rb

@@ -18,7 +18,6 @@ module Wires.current_network::Namespace
       
       # Moved to a dedicated method for subclass' sake
       def class_init
-        # @queue = Queue.new
         @max_children   = nil
         @children       = Array.new
         @children .extend MonitorMixin
@@ -45,10 +44,10 @@ module Wires.current_network::Namespace
       nil end
       
       def reset_neglect_procs
-        @on_neglect = Proc.new do |args|
+        @on_neglect = Proc.new do |*args|
           $stderr.puts "#{self} neglected to spawn task: #{args.inspect}"
         end
-        @on_neglect_done = Proc.new do |args|
+        @on_neglect_done = Proc.new do |*args|
           $stderr.puts "#{self} finally spawned neglected task: #{args.inspect}"
         end
       nil end
@@ -64,25 +63,27 @@ module Wires.current_network::Namespace
       end
       
       # Spawn a task - user code should never call this directly
-      def spawn(*args) # :args: event, chan, proc, blocking, parallel, fire_bt
+      def spawn(*args) # :args: event, chan, future, blocking, parallel, fire_bt
         
-        event, chan, proc, blocking, parallel, fire_bt = *args
+        event, chan, future, blocking, parallel, fire_bt = *args
         *proc_args = event, chan
         *exc_args  = event, chan, fire_bt
         
-        # If not parallel, run the proc in this thread
+        # If not parallel, run the future in this thread
         if !parallel
           begin
-            proc.call(*proc_args)
+            future.call(*proc_args)
           rescue Exception => exc
             unhandled_exception(exc, *exc_args)
           end
           
-          return nil
+          return future
         end
         
-        return neglect(*args) \
-          if @hold_lock.instance_variable_get(:@mon_mutex).locked?
+        if @hold_lock.instance_variable_get(:@mon_mutex).locked?
+          neglect(*args)
+          return future
+        end
         
         # If not parallel, clear old threads and spawn a new thread
         Thread.exclusive do
@@ -93,7 +94,7 @@ module Wires.current_network::Namespace
             # Start the new child thread; follow with chain of neglected tasks
             @children << Thread.new do
               begin
-                proc.call(*proc_args)
+                future.call(*proc_args)
               rescue Exception => exc
                 unhandled_exception(exc, *exc_args)
               ensure
@@ -103,9 +104,12 @@ module Wires.current_network::Namespace
             end
             
           # Capture ThreadError from either OS or user-set limitation
-          rescue ThreadError; return neglect(*args) end
+          rescue ThreadError
+            neglect(*args)
+            return future
+          end
           
-          return @children.last
+          return future
         end
         
       end
@@ -142,13 +146,13 @@ module Wires.current_network::Namespace
           @on_neglect.call(*args)
           @neglected << args
         end
-      false end
+      nil end
       
       # Run a chain of @neglected tasks in place until no more are waiting
       def spawn_neglected_task_chain
         args = @neglected.synchronize do
           return nil if @neglected.empty?
-          ((@neglected.shift)[0...-1]<<true) # Call with blocking
+          @neglected.shift.tap { |a| a[3] = true } # Call with blocking
         end
         spawn(*args)
         @on_neglect_done.call(*args)
@@ -160,7 +164,7 @@ module Wires.current_network::Namespace
         until (cease||=false)
           args = @neglected.synchronize do
             break if (cease = @neglected.empty?)
-            ((@neglected.shift)[0...-1]<<false) # Call without blocking
+            @neglected.shift.tap { |a| a[3] = false } # Call without blocking
           end
           break if cease
           spawn(*args)

data/lib/wires/base/util/router_table.rb

@@ -9,7 +9,7 @@ module Wires.current_network::Namespace
       def weak?; @weak end
       
       def initialize(obj)
-        raise ValueError "#{self.class} referent cannot be nil" if obj.nil?
+        raise ArgumentError, "#{self.class} referent cannot be nil" if obj.nil?
         
         # Make initial weak reference (if possible)
         begin
@@ -64,7 +64,9 @@ module Wires.current_network::Namespace
     
     def []=(key, value)
       begin; ObjectSpace.define_finalizer key, @finalizer
-      rescue RuntimeError; end
+      rescue RuntimeError => e
+        raise unless e.message =~ /can't modify frozen/
+      end
       
       @lock.synchronize do
         id    = key.object_id

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wires
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Joe McIlvain
@@ -150,6 +150,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  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: A lightweight, extensible asynchronous event routing framework in Ruby.
 email: joe.eli.mac@gmail.com
 executables: []
@@ -162,8 +176,10 @@ files:
 - lib/wires/base.rb
 - lib/wires/base/actor.rb
 - lib/wires/base/channel.rb
+- lib/wires/base/channel/sync_helper.rb
 - lib/wires/base/convenience.rb
 - lib/wires/base/event.rb
+- lib/wires/base/future.rb
 - lib/wires/base/launcher.rb
 - lib/wires/base/router.rb
 - lib/wires/base/time_scheduler.rb
@@ -194,7 +210,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.0
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: wires