wires 0.5.1 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b75245c516a29082cbc30499aa0ccdb1a66e4a06
-  data.tar.gz: 82267cb4a27d04f8fce823f29a4a85767fe3be4b
+  metadata.gz: 98b3ac8452b025a1a79925458a5731528ba14bb7
+  data.tar.gz: 926044b8d23b987c3f6d5e1d590d8257bd2ccfe2
 SHA512:
-  metadata.gz: ba93a9b65347f9c547ae977fc331665cd8f977290cbfa75b38a3945f6c27acf54938bf074301bfe10e856e559fc8a9cb72ff99f3aa9ed2b05fbd8f74d36fee18
-  data.tar.gz: 3df28faff0f05f21b1ffdfaa08dfaa8d5f8cb2f9689bd2501d31db886bd946b1006fde807afbba0b0c0f017d81319e0e326e86d229a5eec11d53546a2847eedf
+  metadata.gz: 68494726a3f024be4901491891967494f9e11984118e7cf605bfa7db5c4e6f1483e2f0b6348cbe35ab88060e31b9f71164c6fcb5e9edeb3f3ed80c5720febff3
+  data.tar.gz: c8722a29b08c8c47d66ec8ff617975aa3be544f35a0e9bd6ea03602ec944f593e1eb5cf829287bc682a577a1dfa810367ada5c450b7cf8219ec1e8dd83f615af

data/lib/wires/base/channel.rb

@@ -1,101 +1,243 @@
 
 module Wires
   
+  #  
+  #
+  # = Hooks Summary
+  # As a courtesy for custom services seeking to integrate with {Wires}, some
+  # hooks are provided for the {Channel} class.  These hooks can be accessed
+  # by the methods inherited from {Util::Hooks}.  Note that they are on a class
+  # level, so registering a hook will affect all instances of {Channel}. 
+  # There are two hooks types that {Channel} will invoke:
+  # * +:@before_fire+ - yields the event object and channel {#name} to the 
+  #   user block before {#fire} invokes {Hub.spawn} (see source code).
+  # * +:@after_fire+ - yields the event object and channel {#name} to the 
+  #   user block after {#fire} invokes {Hub.spawn} (see source code).
   class Channel
     
+    # The unique name of the channel, which can be any kind of hashable object.
+    #
+    # Because it is unique, a reference to the channel may be obtained from 
+    # the class-level method {Channel.[] Channel[]} using only the {#name}.
+    #
     attr_reader :name
-    attr_reader :handlers
+    
+    # An array specifying the exception type and string to raise if {#fire} is
+    # called, or +nil+ if it's okay to {#fire} from this channel.
+    #
+    # This is meant to be determined by the {Router} that is selected as the 
+    # current {.router}, and not accessed from any other user code.
+    #
     attr_accessor :not_firable
     
+    # @return [String] friendly output showing the class and channel {#name}
     def inspect; "#{self.class}[#{name.inspect}]"; end
     
     @hub    = Hub
     @router = Router::Default
     @new_lock = Monitor.new
-    @@aim_lock = Mutex.new
+    @@aim_lock = Mutex.new # @api private
     
-    # Add hook methods
     extend Util::Hooks
     
     class << self
+      
+      # The currently selected {Hub} for all channels ({Hub} by default).
+      #
+      # It is the {Hub}'s responsibility to execute event handlers.
+      # @api private
+      #
       attr_accessor :hub
+      
+      # The currently selected {Router} for all channels 
+      # ({Router::Default} by default).
+      #
+      # It is the router's responsibility to decide whether to create new 
+      # channel objects or return existing ones when {.[] Channel[]} is called
+      # and to determine which channels should receive {#fire}d events from
+      # a channel (its {#receivers}).
+      #
+      # {Wires} provides two routers: {Router::Default} and {Router::Simple},
+      # but any object that implements the router interface can be selected.
+      #
       attr_accessor :router
       
-      def new(*args)
+      # Access a channel by {#name}, creating a new channel object if necessary.
+      #
+      # The work of deciding if an object with the given {#name} already 
+      # exists is delegated to the currently selected {.router}.
+      #
+      # @note Because this method does not always create a new object,
+      #   it is recommended to use the alias {[] Channel[]}, which more clearly
+      #   communicates the intention.
+      #
+      # @param name [#hash] a hashable object of any type 
+      #   to use as the channel {#name}
+      #
+      # @return [Channel] the new or existing channel object with that {#name}
+      #
+      def new(name)
         channel = @new_lock.synchronize do
-          router.get_channel(self, *args) { |name| super(name) }
+          router.get_channel(self, name) { |name| super(name) }
         end
       end
       alias_method :[], :new
     end
     
+    # Assigns the given +name+ as the {#name} of this channel object
+    #
+    # @param name [#hash] a hashable object of any type, unique to this channel
+    #
     def initialize(name)
       @name = name
-      @handlers = []
+      @handlers = {}
     end
     
-    # Register a proc to be triggered by an event on this channel
-    # Return the proc that was passed in
-    def register(*events, &proc)
+    # Register an event handler to be executed when a matching event occurs.
+    #
+    # One or more event patterns should be passed as the arguments.
+    # If an event matching one or more of the given event patterns is 
+    # {#fire}d on a channel that has this channel as one of its {#receivers},
+    # then the handler is executed, and yielded the event object and the {#name} 
+    # of the channel upon which {#fire} was called as arguments.
+    #
+    # @param *events [<Symbol, Event>] the event pattern(s)
+    #   to listen for. If the pattern is a symbol or event with a type and no 
+    #   other arguments, any event with that type will be heard.  If the 
+    #   pattern is an event that has other arguments, each of the arguments 
+    #   and keyword arguments in the pattern must also be present in the
+    #   fired event for it to be heard by the handler, but the fired event may
+    #   also include other arguments that were not declared in the pattern
+    #   and still be heard by the handler (see {Event#=~}).
+    # @param &callable [Proc] the executable code to register as a handler 
+    #   on this channel for the given pattern.
+    #
+    # @return [Proc] the +&callable+ given, which has been extended with an
+    #   +#unregister+ method on the object itself. The injected method takes
+    #   no arguments and will unregister the +&callable+ from every channel
+    #   on which it is {#register}ed. This can be a helpful alternative to 
+    #   calling {#unregister} on the relevant channel(s) by hand.
+    # 
+    # @raise [ArgumentError] if no ampersand-argument or inline block is 
+    #   given as the +&callable+.
+    #
+    def register(*events, &callable)
       raise ArgumentError, "No callable given to execute on event: #{events}" \
-        unless proc.respond_to? :call
+        unless callable.respond_to? :call
       events = Event.list_from *events
       
+      # Register the events under the callable in the @handlers hash
       @@aim_lock.synchronize do
-        @handlers << [events, proc] \
-          unless @handlers.include? [events, proc]
+        ary = (@handlers.has_key?(callable) ?
+                 @handlers[callable]        :
+                 @handlers[callable] = [])
+        events.each { |e| ary << e unless ary.include? e }
       end
       
-      # Insert the @registered_channels variable into the proc
-      channels = proc.instance_variable_get(:@registered_channels)
+      # Insert the @registered_channels variable into the callable
+      channels = callable.instance_variable_get(:@registered_channels)
       if channels
         channels << self
       else
-        proc.instance_variable_set(:@registered_channels, [self])
+        callable.instance_variable_set(:@registered_channels, [self])
       end
       
-      # Insert the #unregister method into the proc
-      proc.singleton_class.send :define_method, :unregister do
+      # Insert the #unregister method into the callable
+      callable.singleton_class.send :define_method, :unregister do
         singleton_class.send :remove_method, :unregister
         @registered_channels.each do |c|
-          c.unregister self
+          c.unregister &self
         end
-      end unless proc.respond_to? :unregister
+      end unless callable.respond_to? :unregister
       
-      proc
+      callable
     end
     
-    # Unregister a proc from the target list of this channel
-    # Return true if at least one matching target was unregistered, else false
-    def unregister(proc)
+    # Unregister an event handler that was defined with #register
+    #
+    # @note It is not necessary to unregister event handlers 'owned' by
+    #   persistent objects, but for short-lived objects, it is critical to
+    #   to do so.  Due to the way that Proc objects (including those 
+    #   generated implicitly from inline blocks) enclose their surrounding 
+    #   scope, the +&callable+ handler will keep alive any objects it encloses,
+    #   and the channel that holds a reference to the +&callable+ will keep it
+    #   alive until it is unregistered.
+    #
+    # @note As an alternative to calling {Channel#unregister}, one may use
+    #   the +#unregister+ method that was injected into the +&callable+ 
+    #   (refer to the return value of {#register})
+    #
+    # @param &callable [Proc] the same callable object that was given to 
+    #   (and returned by) {#register}.
+    #
+    # @return [Boolean] +true+ if the callable was previously {#register}ed 
+    #   (and is now {#unregister}ed); +false+ otherwise.
+    #
+    # @TODO break the GC note out into a dedicated document and link to it
+    # @TODO try to remove all references to this channel object when it
+    #   has no more handlers (and try to determine if this would ever be a 
+    #   bad idea or would cause errant behavior) - possibly implement 
+    #   Channel#forget instead?
+    #
+    def unregister(&callable)
       @@aim_lock.synchronize do
-        !!(@handlers.reject! do |stored_events, stored_proc|
-          proc==stored_proc
-        end)
+        !!(@handlers.delete callable)
       end
     end
     
-    # Fire an event on this channel
-    def fire(input, blocking:false, parallel:!blocking)
+    # Return the list of {#register}ed handlers for this channel
+    #
+    # @return [Array<Array(Array<Symbol,Event>,Proc)>] an array of arrays, each 
+    #   containing an array of event patterns followed by the associated Proc.
+    #
+    def handlers
+      @handlers.map { |callable, events| [events, callable] }
+    end
+    
+    # Fire an event on this channel.
+    #
+    # Each handler with an event pattern matching the fired event (see 
+    # {Event#=~}) that is {#register}ed on a channel that matches the firing 
+    # channel (see {Channel#=~}) will be executed, and passed the event object
+    # and channel name as arguments.
+    #
+    # This method fires in a nonblocking manner by default, but this behavior 
+    # can be overriden with the +:blocking+ parameter. See {#fire!} for 
+    # blocking default behavior.
+    #
+    # @param [Event, Symbol] event the event to be fired, as an Event or Symbol.
+    #   In this context, a Symbol is treated as an 'empty' Event of that type
+    #   (see to {Symbol#[]}).
+    # @param [Boolean] :blocking when true, the method will wait to return 
+    #   until all handlers have finished their execution.
+    # @param [Boolean] :parallel when true, the handlers will be executed in 
+    #   parallel, if there are more than one; otherwise, they will be executed
+    #   serially (in an undefined order).  Unless otherwise specified, this 
+    #   parameter will be set to the opposite of the value of the +:blocking+
+    #   parameter; that is, nonblocking firing will by default also be parallel,
+    #   and blocking firing will by default also be sequential.
+    #
+    # @return [Array<Thread>] the array of threads spawned by the method, 
+    #   if any.  This could be useful for manually joining the threads later
+    #   or monitoring their status.
+    #
+    # @raise An exception of the type and message contained in the 
+    #   {#not_firable} attribute if it has been assigned by the active 
+    #   {.router} through the {#not_firable=} accessor.
+    #
+    # @TODO Test the return array in each of the four concurrency cases
+    #
+    def fire(event, blocking: false, parallel: !blocking)
       raise *@not_firable if @not_firable
       
-      return [] << Thread.new { fire(input, blocking:true, parallel:false) } \
+      return [] << Thread.new { fire(event, blocking:true, parallel:false) } \
         if !blocking and !parallel
       
       backtrace = caller
       
-      event = Event.list_from input
+      event = event.to_wires_event
       
-      case event.count
-      when 0
-        raise ArgumentError,"Can't create an event from input: #{input.inspect}"
-      when 1
-        event = event.first
-      else
-        raise ArgumentError,"Can't fire on multiple events: #{event.inspect}"
-      end
-      
-      self.class.run_hooks(:@before_fire, event, self.name)
+      self.class.send(:run_hooks, :@before_fire, event, self.name)
       
       # Select appropriate targets
       procs = []
@@ -104,7 +246,7 @@ module Wires
         .get_receivers(self).each do |chan|
           chan.handlers.each do |elist, pr|
             elist.each do |e|
-              procs << pr if e =~ event
+              procs << pr if e =~ [event, 55, 55.6, 0x00, /regexp/, 'string', "string"]
             end
           end
         end
@@ -123,29 +265,68 @@ module Wires
       
       threads.each &:join if blocking and parallel
       
-      self.class.run_hooks(:@after_fire, event, self.name)
+      self.class.send(:run_hooks, :@after_fire, event, self.name)
       
       threads
     end
     
-    # Fire a blocking event on this channel
+    # Fire an event on this channel.
+    #
+    # Each handler with an event pattern matching the fired event (see 
+    # {Event#=~}) that is {#register}ed on a channel that matches the firing 
+    # channel (see {Channel#=~}) will be executed, and passed the event object
+    # and channel name as arguments.
+    #
+    # This method fires in a blocking manner by default, but this behavior 
+    # can be overriden with the +:blocking+ parameter. See {#fire!} for 
+    # nonblocking default behavior.
+    #
+    # @param (see Channel#fire)
+    # @return (see Channel#fire)
+    # @raise (see Channel#fire)
+    # @overload fire!(event, blocking: true, parallel: !blocking)
+    #
     def fire!(*args, **kwargs)
       kwargs[:blocking] = true unless kwargs.has_key? :blocking
       fire(*args, **kwargs)
     end
     
-    # Returns true if listening on 'self' would hear a firing on 'other'
-    # (not commutative)
+    # Determine if one channel matches another.
+    # 
+    # In this context, a match indicates a receiver relationship.
+    # That is, this method tests if +self+ is one of the {#receivers} of 
+    # +other+. For a matching pair of channels, a {#fire}d event on the 
+    # right-hand channel could be received by a relevant event handler on 
+    # the left-hand channel. 
+    #
+    # Note that, depending on the strategy of the {.router}, this operator 
+    # is not necessarily commutative. That is, having +a =~ b+ does not 
+    # guarantee that +b =~ a+.
+    #
+    # @note Channel receiver relationships are entirely dictated by the 
+    #   selected {.router}. Refer to the examples in the documentation for 
+    #   {Router::Default} to learn about the routing patterns of the default
+    #   router, but know that other {Router}s may be substituted as needed
+    #   on a global basis with the {.router=} class-level accessor.
+    #
+    # @param other [Channel] the channel to which +self+ should be compared.
+    # @return [Boolean] +true+ if +self+ is one of +other+'s {#receivers};
+    #   +false+ otherwise.
+    #
     def =~(other)
       (other.is_a? Channel) ?
         (self.class.router.get_receivers(other).include? self) : 
         super
     end
     
+    # @return [Array<Channel>] the list of channels whose {#register}ed 
+    #   event handlers would receive a relevant event {#fire}d by this channel.
+    # 
+    # @note (see Channel#=~)
+    #
     def receivers
       self.class.router.get_receivers self
     end
     
   end
-  
-end
+end

data/lib/wires/base/hub.rb

@@ -2,7 +2,7 @@
 module Wires
   # An Event Hub. Event/proc associations come in, and the procs 
   # get called in new threads in the order received
-  class self::Hub
+  class Hub
     class << self
       
       # Refuse to instantiate; it's a singleton!
@@ -64,7 +64,7 @@ module Wires
       end
       
       # Spawn a task - user code should never call this directly
-      def spawn(*args) # :args: event, chan, proc, blocking, fire_bt
+      def spawn(*args) # :args: event, chan, proc, blocking, parallel, fire_bt
         
         event, chan, proc, blocking, parallel, fire_bt = *args
         *proc_args = event, chan

data/lib/wires/base/time_scheduler_item.rb

@@ -61,7 +61,8 @@ module Wires
     
     # Fire the event now, regardless of time or active status
     def fire(**kwargs) # kwargs merge with and override @kwargs
-      @channel.fire(@events, **(@fire_kwargs.merge kwargs))
+      kwargs = @fire_kwargs.merge kwargs
+      @events.each { |e| @channel.fire(e, **kwargs) }
       count_dec
       
       if @active

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

@@ -4,6 +4,7 @@ module Wires
     module Hooks
       
       # Register a hook - can be called multiple times if retain is true
+      # @param hooks_sym [Symbol] the symbol...
       def add_hook(hooks_sym, retain=false, &proc)
         hooks = instance_variable_get(hooks_sym.to_sym)
         if hooks
@@ -21,12 +22,14 @@ module Wires
         hooks.reject! {|h| h[0]==proc}
       end
       
-      # Run all hooks, deleting those not marked for retention
+    private
+      
+      # Run all hooks
       def run_hooks(hooks_sym, *exc_args)
         hooks = instance_variable_get(hooks_sym.to_sym)
         return unless hooks
         for hook in hooks
-          proc, retain = hook
+          proc, _ = hook
           proc.call(*exc_args)
         end
       nil end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wires
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.5.2
 platform: ruby
 authors:
 - Joe McIlvain
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-24 00:00:00.000000000 Z
+date: 2013-12-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: threadlock