tap 0.11.1 → 0.12.0

data/lib/tap/support/constant.rb

@@ -21,7 +21,8 @@ module Tap
         # const_name.  When a constant is missing, constantize yields
         # the current base and any non-existant constant names the block,
         # if given, or raises a NameError.  The block is expected 
-        # to return the proper constant.
+        # to return the desired constant; in the example 'Non::Existant'
+        # is effectively mapping to ConstName.
         #
         #   module ConstName; end
         #

data/lib/tap/support/constant_manifest.rb

@@ -4,18 +4,24 @@ require 'tap/support/constant'
 module Tap
   module Support
     
+    # :startdoc:::-
+    #
     # ConstantManifest builds a manifest of Constant entries using Lazydoc.
-    # The idea is that Lazydoc can find files with resouces of a specific type
-    # (ex tasks) and Constant can reference those resouces and load them as 
-    # necessary. ConstantManifest registers paths so that they may be lazily
-    # scanned when searching for a specific resource.
+    #
+    # Lazydoc can quickly scan files for constant attributes, and thereby
+    # identify constants based upon a flag like the '::manifest' attribute used
+    # to identify task classes.  ConstantManifest registers paths that will be
+    # scanned for a specific resource, and lazily builds the references to load
+    # them as necessary.
+    # 
+    # :startdoc:::+
     class ConstantManifest < Support::Manifest
       
-      # The attribute identifying resources in a file
+      # The attribute identifying constants in a file
       attr_reader :const_attr
       
-      # Registered [root, [paths]] pairs that will be searched
-      # for the const_attr
+      # An array of registered (root, [paths]) pairs
+      # that will be searched for const_attr
       attr_reader :search_paths
       
       # The current index of search_paths
@@ -24,7 +30,8 @@ module Tap
       # The current index of paths
       attr_reader :path_index
       
-      # Initializes a new ConstantManifest
+      # Initializes a new ConstantManifest that will identify constants
+      # using the specified constant attribute.
       def initialize(const_attr)
         @const_attr = const_attr
         @search_paths = []
@@ -55,15 +62,15 @@ module Tap
       # Sets search_path_index and path_index to zero and clears entries.
       # Returns self.
       def reset
-        # Support::Lazydoc[path].resolved = false
+        @search_paths.each {|path| Lazydoc[path].resolved = false }
         @entries.clear
         @search_path_index = 0
         @path_index = 0
         super
       end
       
-      # Yields each entry to the block.  Unless built?, each lazily
-      # iterates over search_paths to look for new entries.
+      # Yields each Constant entry to the block.  Unless built?, each
+      # lazily iterates over search_paths to look for new entries.
       def each
         entries.each do |entry|
           yield(entry)
@@ -93,25 +100,21 @@ module Tap
       # objects for each.   If the document has no default_const_name set,
       # resolve will set the default_const_name based on the relative
       # filepath from path_root to path.
-      def resolve(path_root, path)
+      def resolve(path_root, path) # :nodoc:
         entries = []
-        lazydoc = nil
+        document = nil
         
-        Lazydoc.scan(File.read(path), const_attr) do |const_name, attr_key, comment|
-          if lazydoc == nil
-            lazydoc = Lazydoc[path]
-            
-            if lazydoc.default_const_name.empty?
-              relative_path = Root.relative_filepath(path_root, path).chomp(File.extname(path))
-              lazydoc.default_const_name = relative_path.camelize
-            end
+        Lazydoc::Document.scan(File.read(path), const_attr) do |const_name, key, value|
+          if document == nil
+            relative_path = Root.relative_filepath(path_root, path).chomp(File.extname(path))
+            document = Lazydoc.register_file(path, relative_path.camelize)
           end
           
-          if const_name.empty? 
-            const_name = lazydoc.default_const_name
-          end
+          const_name = document.default_const_name if const_name.empty? 
+          comment = Lazydoc::Subject.new(nil, document)
+          comment.value = value
           
-          lazydoc[const_name][attr_key] = comment
+          document[const_name][key] = comment
           entries << Constant.new(const_name, path)
         end
         

data/lib/tap/support/dependency.rb

@@ -12,7 +12,7 @@ module Tap
         base.instance_variable_set(:@_result, nil)
       end
       
-      # Conditional _execute; only calls _method_name if
+      # Conditional _execute; only calls method_name if
       # resolved? is false (thus assuring self will only
       # be executed once).
       #

data/lib/tap/support/executable.rb

@@ -1,4 +1,5 @@
 require 'tap/support/audit'
+require 'tap/support/joins'
 
 module Tap
   module Support
@@ -10,7 +11,7 @@ module Tap
       attr_reader :app
       
       # The method called during _execute
-      attr_reader :_method_name
+      attr_reader :method_name
     
       # The block called when _execute completes
       attr_reader :on_complete_block
@@ -18,143 +19,33 @@ module Tap
       # An array of dependency indicies that will be resolved on _execute
       attr_reader :dependencies
       
-      # The batch for self
-      attr_reader :batch
-      
       public
       
       # Extends obj with Executable and sets up all required variables.  The
       # specified method will be called on _execute.
-      def self.initialize(obj, method_name, app=App.instance, batch=[], dependencies=[], &on_complete_block)
+      def self.initialize(obj, method_name, app=App.instance, dependencies=[], &on_complete_block)
         obj.extend Executable
         obj.instance_variable_set(:@app, app)
-        obj.instance_variable_set(:@_method_name, method_name)
+        obj.instance_variable_set(:@method_name, method_name)
         obj.instance_variable_set(:@on_complete_block, on_complete_block)
         obj.instance_variable_set(:@dependencies, dependencies)
-        obj.instance_variable_set(:@batch, batch)
-        batch << obj
-        
         obj
       end
       
-      # Initializes a new batch object and adds the object to batch.
-      # The object will be a duplicate of self.  (Note this method
-      # can raise an error for objects that don't support dup, 
-      # notably Method objects generated by Object#_method).
-      def initialize_batch_obj
-        obj = self.dup
-        
-        if obj.kind_of?(Executable)
-          batch << obj
-          obj
-        else
-          Executable.initialize(obj, _method_name, app, batch, dependencies, &on_complete_block)
-        end
-      end
-      
-      # Returns true if the batch size is greater than one 
-      # (the one is assumed to be self).  
-      def batched?
-        batch.length > 1
-      end
-
-      # Returns the index of self in batch.
-      def batch_index
-        batch.index(self)
-      end
-      
-      # Merges the batches for self and the specified Executables,
-      # removing duplicates.
-      #
-      #   class BatchExecutable
-      #     include Tap::Support::Executable
-      #     def initialize(batch=[])
-      #       @batch = batch
-      #       batch << self
-      #     end
-      #   end
-      #
-      #   b1 = BatchExecutable.new
-      #   b2 = BatchExecutable.new
-      #   b3 = BatchExecutable.new
-      #
-      #   b1.batch_with(b2, b3)
-      #   b1.batch                   # => [b1, b2, b3]
-      #   b3.batch                   # => [b1, b2, b3]
-      #
-      # Note that batch_with is not recursive (ie it does not 
-      # merge the batches of each member in the batch):
-      #
-      #   b4 = BatchExecutable.new
-      #   b4.batch_with(b3)   
-      #            
-      #   b4.batch                   # => [b4, b1, b2, b3]
-      #   b3.batch                   # => [b4, b1, b2, b3]
-      #   b2.batch                   # => [b1, b2, b3]
-      #   b1.batch                   # => [b1, b2, b3]
-      #
-      # However it does affect all objects that share the same
-      # underlying batch:
-      #
-      #   b5 = BatchExecutable.new(b1.batch)
-      #   b6 = BatchExecutable.new
-      #
-      #   b5.batch.object_id         # => b1.batch.object_id
-      #   b5.batch                   # => [b1, b2, b3, b5]
-      #
-      #   b5.batch_with(b6)
-      #
-      #   b5.batch                   # => [b1, b2, b3, b5, b6]
-      #   b1.batch                   # => [b1, b2, b3, b5, b6]
-      #
-      # Returns self.
-      def batch_with(*executables)
-        batches = [batch] + executables.collect {|executable| executable.batch }
-        batches.uniq!
-        
-        merged = []
-        batches.each do |batch| 
-          merged.concat(batch)
-          batch.clear
-        end
-        
-        merged.uniq!
-        batches.each {|batch| batch.concat(merged) }
-        self
-      end
-      
-      # Enqueues each member of batch (and implicitly self) to app with the
-      # inputs. The number of inputs provided should match the number of
-      # inputs for the _method_name method.
+      # Enqueues self to app with the inputs. The number of inputs provided
+      # should match the number of inputs for the method_name method.
       def enq(*inputs)
-        batch.each do |executable| 
-          executable.unbatched_enq(*inputs)
-        end
-        self
-      end
-      
-      # Like enq, but only enques self.
-      def unbatched_enq(*inputs)
         app.queue.enq(self, inputs)
         self
       end
       
-      # Sets a block to receive the results of _execute for each member of 
-      # batch (and implicitly self).  Raises an error if on_complete_block
-      # is already set within the batch.  Override the existing 
+      # Sets a block to receive the results of _execute.  Raises an error if
+      # an on_complete_block is already set.  Override the existing 
       # on_complete_block by specifying override = true.
       #
       # Note: the block recieves an audited result and not the result
       # itself (see Audit for more information).
       def on_complete(override=false, &block) # :yields: _result
-        batch.each do |executable| 
-          executable.unbatched_on_complete(override, &block)
-        end
-        self
-      end
-      
-      # Like on_complete, but only sets the on_complete_block for self.
-      def unbatched_on_complete(override=false, &block) # :yields: _result
         unless on_complete_block == nil || override
           raise "on_complete_block already set: #{self}" 
         end
@@ -163,56 +54,54 @@ module Tap
       end
       
       # Sets a sequence workflow pattern for the tasks; each task
-      # enques the next task with it's results, starting with self.  
-      # See Joins::Sequence.
+      # enques the next task with it's results, starting with self.
       def sequence(*tasks, &block) # :yields: _result
-        Joins::Sequence.join(self, tasks, &block)
+        options = tasks[-1].kind_of?(Hash) ? tasks.pop : {}
+        
+        current_task = self
+        tasks.each do |next_task|
+          Join.new(options).join([current_task], [next_task], &block)
+          current_task = next_task
+        end
       end
 
-      # Sets a fork workflow pattern for self; each target
-      # will enque the results of self.  See Joins::Fork.
+      # Sets a fork workflow pattern for self; each target will enque the
+      # results of self.
       def fork(*targets, &block) # :yields: _result
-        Joins::Fork.join(self, targets, &block)
+        options = targets[-1].kind_of?(Hash) ? targets.pop : {}
+        Join.new(options).join([self], targets, &block)
       end
 
       # Sets a simple merge workflow pattern for the source tasks. Each 
       # source enques self with it's result; no synchronization occurs, 
-      # nor are results grouped before being enqued.  See Joins::Merge.
+      # nor are results grouped before being enqued.
       def merge(*sources, &block) # :yields: _result
-        Joins::Merge.join(self, sources, &block)
+        options = sources[-1].kind_of?(Hash) ? sources.pop : {}
+        Join.new(options).join(sources, [self], &block)
       end
 
       # Sets a synchronized merge workflow for the source tasks.  Results 
       # from each source are collected and enqued as a single group to
       # self.  The collective results are not enqued until all sources
       # have completed.  See Joins::SyncMerge.
-      #
-      # Raises an error if a source returns twice before the target is enqued.
       def sync_merge(*sources, &block) # :yields: _result
-        Joins::SyncMerge.join(self, sources, &block)
+        options = sources[-1].kind_of?(Hash) ? sources.pop : {}
+        Joins::SyncMerge.new(options).join(sources, [self], &block)
       end
 
-      # Sets a switch workflow pattern for self.  When _execute completes, 
-      # switch yields the audited result to the block which should return
-      # the index of the target to enque with the results. No target will 
-      # be enqued if the index is false or nil; an error is raised if no 
-      # target can be found for the specified index. See Joins::Switch.
+      # Sets a switch workflow pattern for self.  On complete, switch yields
+      # the audited result to the block and the block should return the index
+      # of the target to enque with the results. No target will be enqued if
+      # the index is false or nil.  An error is raised if no target can be
+      # found for the specified index. See Joins::Switch.
       def switch(*targets, &block) # :yields: _result
-        Joins::Switch.join(self, targets, &block)
+        options = targets[-1].kind_of?(Hash) ? targets.pop : {}
+        Joins::Switch.new(options).join([self], targets, &block)
       end
       
-      # Adds the dependency to each member in batch (and implicitly self).
-      # The dependency will be resolved with the input arguments during 
-      # _execute, using resolve_dependencies.
+      # Adds the dependencies to self.  Dependencies are resolved during
+      # _execute through resolve_dependencies.
       def depends_on(*dependencies)
-        batch.each do |e| 
-          e.unbatched_depends_on(*dependencies)
-        end
-        self
-      end
-      
-      # Like depends_on, but only adds the dependency to self.
-      def unbatched_depends_on(*dependencies)
         raise ArgumentError, "cannot depend on self" if dependencies.include?(self)
         
         dependencies.each do |dependency|
@@ -236,53 +125,37 @@ module Tap
         self
       end
       
-      # Auditing method call.  Resolves dependencies, executes _method_name,
+      # Auditing method call.  Resolves dependencies, executes method_name,
       # and sends the audited result to the on_complete_block (if set).
       #
-      # Audits are initialized in the follwing manner:
-      # no inputs:: Creates a new, empty Audit.  The first value of the audit
-      #             will be the result of call.
-      # one input:: Forks the input if it is an audit, otherwise initializes
-      #             a new audit using the input.
-      # multiple inputs:: Merges the inputs into a new Audit.
-      #
+      # Returns the audited result.
       def _execute(*inputs)
         resolve_dependencies
         
-        audit = case inputs.length
-        when 0 then Audit.new
-        when 1 
-          audit = inputs.first
-          if audit.kind_of?(Audit) 
-            inputs = [audit._current]
-            audit._fork
+        previous = []
+        inputs.collect! do |input| 
+          if input.kind_of?(Audit) 
+            previous << input
+            input.value
           else
-            Audit.new(audit)
-          end 
-        else
-          sources = []
-          inputs.collect! do |input| 
-            if input.kind_of?(Audit) 
-              sources << input._fork
-              input._current
-            else
-              sources << nil
-              input
-            end
+            previous << Audit.new(nil, input)
+            input
           end
-          Audit.new(inputs, sources)
         end
-      
-        audit._record(self, send(_method_name, *inputs))
-        on_complete_block ? on_complete_block.call(audit) : app.aggregator.store(audit)
+         
+        audit = Audit.new(self, send(method_name, *inputs), previous)
+        if complete_block = on_complete_block || app.on_complete_block
+          complete_block.call(audit)
+        else 
+          app.aggregator.store(audit)
+        end
         
         audit
       end
       
-      # Calls _execute with the inputs and returns the un-audited result.
-      # Execute is not a batched method.
+      # Calls _execute with the inputs and returns the non-audited result.
       def execute(*inputs)
-        _execute(*inputs)._current
+        _execute(*inputs).value
       end
       
       # Raises a TerminateError if app.state == State::TERMINATE.
@@ -294,10 +167,6 @@ module Tap
         end
       end
       
-      def inspect
-        "#<#{self.class.to_s}:#{object_id} _method: #{_method_name} batch_length: #{batch.length} app: #{app}>"
-      end
-      
     end
   end
 end

data/lib/tap/support/executable_queue.rb

@@ -1,35 +1,39 @@
+require 'tap/support/executable'
+
 module Tap
   module Support
     
-    # ExecutableQueue allows thread-safe enqueing and dequeing of 
-    # Executable methods and inputs for execution.  
-    class ExecutableQueue
-      include MonitorMixin
+    # ExecutableQueue allows thread-safe enqueing and dequeing of Executable
+    # methods and inputs for execution.
+    class ExecutableQueue < Monitor
       
       # Creates a new ExecutableQueue
       def initialize
-        # required for MonitorMixin
-        super()
-        @queue = []
+        super
+        @rounds = [[]]
       end
       
-      # Clears all methods and inputs.  Returns the existing queue as an array.
+      # Clears self and returns an array of the enqueued methods and inputs,
+      # organized by round.
       def clear
         synchronize do
-          current = self.queue
-          self.queue = []
+          current, @rounds = @rounds, [[]]
           current
         end
       end
       
       # Returns the number of enqueued methods
       def size
-        queue.length
+        synchronize do
+          size = 0 
+          @rounds.each {|round| size += round.length }
+          size
+        end
       end
       
       # True if no methods are enqueued
       def empty?
-        queue.empty?
+        synchronize { size == 0 }
       end
       
       # Enqueues the method and inputs. Raises an error if the  
@@ -56,26 +60,52 @@ module Tap
         synchronize { queue.shift }
       end
       
-      def concat(array)
+      # Enques an array of [method, inputs] entries as a round.  Rounds are
+      # dequeued completely before the next round is dequeued.
+      def concat(round)
         synchronize do
-          array.each do |method, inputs|
-            enq(method, inputs)
+          round.each do |method, inputs|
+            check_method(method)
           end
+          
+          @rounds << round.dup
         end
       end
       
-      # Converts self to an array.
-      def to_a
-        queue.dup
+      # Converts self to an array.  If flatten is specified, all rounds are
+      # concatenated into a single array.
+      def to_a(flatten=true)
+        synchronize do
+          if flatten
+            array = []
+            @rounds.each {|round| array.concat(round) }
+            array
+          else
+            @rounds.collect {|round| round.dup}
+          end
+        end
       end
       
       protected
       
-      attr_accessor :queue # :nodoc:
+      # Returns the active round.
+      def queue # :nodoc:
+        while @rounds.length > 1
+          queue = @rounds[0]
+          
+          if queue.empty?
+            @rounds.shift
+          else
+            return queue
+          end
+        end
+        
+        @rounds[0]
+      end
       
       # Checks if the input method is extended with Executable
       def check_method(method) # :nodoc:
-        raise "not Executable: #{method}" unless method.kind_of?(Executable)
+        raise "not executable: #{method.inspect}" unless method.kind_of?(Executable)
       end
     end 
   end