wires 0.5.6 → 0.5.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 51987a7590eb20419d2b26717efc9085ea19043f
-  data.tar.gz: ed10fe66856e3517d7e9779188957e022232d4d2
+  metadata.gz: e9f2487653b2bc09e49a835f4945890973744d1a
+  data.tar.gz: 273bf1a229f890c1a1bae0e7002cfa8c99c56e2d
 SHA512:
-  metadata.gz: 75b868f5b060e88b5fc8f8024946cd6c862af613f8afbccfea85247e11a33bb87498f38677f941869cbd6ee7b8b81122f32249bbd61c82d95b7876244fa9350a
-  data.tar.gz: 9f70b430842b38fbec44c558720e6a846ce88d738a7e742777a873f46c9d129aa4ee519a1663ed0194f9befcd99c05aa6e62b3eb5f1590cf1df91221351ee110
+  metadata.gz: a087b9a5bc3c6cc604d1272401e24d0e428b9868b6c3a615384bd35af3862b5ef896832bbb6d6c671b683871f8993ca6630ad37b53eff1f1ce418cb075ca888b
+  data.tar.gz: f6fd9105f3d1cbc90489e2e933065214657463a261e94de1fe85faac8f2c609689b303b6384bd6f50e388ccfd0b5689418c7caf6533406324700baf22ee89c62

data/lib/wires/base/channel.rb

@@ -291,6 +291,123 @@ module Wires.current_network::Namespace
       fire(*args, **kwargs)
     end
     
+    # Synchronize execution of this thread to an incoming event.
+    #   The user block will be executed, and will not return until a matching
+    #   incoming event has been fired
+    #   (see the {SyncHelper})
+    #
+    # @note In order to use this method correctly, the "action" that causes the
+    #   incoming event to be fired should happen within the user block.  If
+    #   it happens before the user block, one risks a race condition; if after,
+    #   one risks deadlock (or timeout) due to the feedback event being missed.
+    #   As long as the feedback event happens after execution of the user block
+    #   has begun, the event is guaranteed to be caught and processed.
+    #
+    # @param *events [<Symbol, Event>] the event pattern(s) filter
+    #   to listen with. (see {#register}).
+    # @param timeout [Fixnum] the timeout, in seconds.
+    #   (see {SyncHelper#wait}).
+    # @param &block [Proc] the user block. This block will be executed inline
+    #   and passed an instance of {SyncHelper}.  Within this block, the helper
+    #   should be configured using its methods.  Optionally, {SyncHelper#wait}
+    #   can be called to wait in a specific location in the block.  Otherwise,
+    #   it will be called implicitly at the end of the block.
+    #
+    def sync_on(*events, timeout:nil, &block)
+      SyncHelper.new(events, self, timeout:timeout, &block)
+      nil
+    end
+    
+    # Helper class passed to user block in {Channel#sync} 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}
+      # @api private
+      def initialize(events, channel, timeout:nil)
+        @timeout = timeout
+        @lock, @cond = Mutex.new, ConditionVariable.new
+        @conditions = []
+        @executions = []
+        @received   = []
+        
+        # Create the temporary event handler to capture incoming matches
+        proc = Proc.new { |e,c| @lock.synchronize { snag e,c } }
+        
+        # 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 {#conditions} 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
+          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/convenience.rb

@@ -13,6 +13,11 @@ module Wires.current_network::Namespace
       codeblock
     end
     
+    def sync_on(event, channel=self, **kwargs, &codeblock)
+      channel = Channel.new(channel) unless channel.is_a? Channel
+      channel.sync_on(event, **kwargs, &codeblock)
+    end
+    
     def fire(event, channel=self, **kwargs)
       channel = Channel.new(channel) unless channel.is_a? Channel
       

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wires
 version: !ruby/object:Gem::Version
-  version: 0.5.6
+  version: 0.5.7
 platform: ruby
 authors:
 - Joe McIlvain
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-19 00:00:00.000000000 Z
+date: 2014-02-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: threadlock
@@ -162,7 +162,7 @@ files:
 - lib/wires/core_ext/time.rb
 homepage: https://github.com/jemc/wires/
 licenses:
-- Copyright 2013 Joe McIlvain. All rights reserved.
+- Copyright 2013-2014 Joe McIlvain. All rights reserved.
 metadata: {}
 post_install_message: 
 rdoc_options: []
@@ -185,3 +185,4 @@ signing_key:
 specification_version: 4
 summary: wires
 test_files: []
+has_rdoc: