police-dataflow 0.0.1 → 0.0.2

data/lib/police/dataflow/labeling.rb

@@ -3,37 +3,35 @@ module Police
 module DataFlow
   # Attaches a label to a piece of data.
   #
-  # @param [Object] data the data that will be labeled
-  # @param [Police::DataFlow::Label] label the label to be applied to the object
-  # @return [BasicObject] either the given piece of data, or a proxy that should
-  #     be used instead of it
+  # @param [BasicObject] data the data that will be labeled
+  # @param [Police::DataFlow::Label] label the label to be applied to the
+  #     object
+  # @return [BasicObject] either the given piece of data, or a proxy that
+  #     should be used instead of it
   def self.label(data, label)
     label_set = data.__police_labels__
-    if label_set.nil?
+    if nil == label_set
       proxied = data
       label_set = {}
-      autoflow_set = {}
     else
       proxied = data.__police_proxied__
-      autoflow_set = data.__police_autoflows__
     end
-    
-    if Police::DataFlow::Labeling.add_label_to_set label, label_set,
-                                                   autoflow_set
-      data = Police::DataFlow::Proxying.proxy proxied, label_set, autoflow_set
-      data
+
+    if Police::DataFlow::Labeling.add_label_to_set label, label_set
+      data = Police::DataFlow::Proxying.proxy proxied, label_set
     end
     data
   end
-  
+
   # All the labels attached to a piece of data.
   #
   # @param [Object] data the data whose labels are queried
-  # @return [Array<Police::DataFlow::Label>] all the labels attached to the data
+  # @return [Array<Police::DataFlow::Label>] all the labels attached to the
+  #     data
   def self.labels(data)
     return [] unless label_set = data.__police_labels__
     return label_set.first.last.keys if label_set.length == 1
-    
+
     labels = []
     label_set.each { |label_key, label_hash| labels.concat label_hash.keys }
     labels
@@ -41,31 +39,114 @@ module DataFlow
 
 # Label algebra.
 module Labeling
+  # The actual class of a proxy object.
+  #
+  # This is necessary because the class method for a proxy object must return
+  # the proxied object's class.
+  #
+  # @private
+  # This is intended to help testing the proxying code. It should not be used
+  # by client code.
+  #
+  # @param [BasicObject] data a proxy returned by {Police::DataFlow#label}
+  # @return [Class] a subclass of {Police::DataFlow::ProxyBase}, or nil if the
+  #     given object is not a proxy
+  def self.proxy_class(data)
+    if data.__police_labels__.nil?
+      nil
+    else
+      data.__police_class__
+    end
+  end
+
   # Adds a label to the set of labels held by an object's proxy.
   #
+  # @param [Police::DataFlow::Label] label the label to be added to the set
   # @param [Hash<Integer,Hash<Police::DataFlow::Label,Boolean>>] label_set the
   #     set of all labels that will be held by the object's proxy
-  # @param [Hash<Integer,Hash<Police::DataFlow::Label,Boolean>>] autoflow_set
-  #     the set of labels whose autoflow? method returned true
   # @return [Boolean] false if the set already had a label of the same type, so
   #     the proxy holding the set can still be used; true if the set had to be
   #     expanded, so a new proxy is needed
-  def self.add_label_to_set(label, label_set, autoflow_set)
+  def self.add_label_to_set(label, label_set)
     label_class = label.class
     label_key = label_class.__id__
     if label_set.has_key? label_key
       label_set[label_key][label] = true
-      # NOTE: autoflow_set uses use the same hash, so no work is necessary
       return false
     end
-    
+
     label_entry = { label => true }
     label_set[label_key] = label_entry
-    autoflow_set[label_key] = label_entry if label_class.autoflow?
     true
   end
+
+  # Merges a set of labels into another set.
+  #
+  # @param [Hash<Integer,Hash<Police::DataFlow::Label,Boolean>>] target_set one
+  #     of the label sets to be merged; this set will be modified by the method
+  # @param [Hash<Integer,Hash<Police::DataFlow::Label,Boolean>>] source_set the
+  #     other label set that will be merged; this set will not be modified
+  # @return [Boolean] false if the target set already had labels of all the
+  #     types in the source set, so the proxy holding the target object can
+  #     still be used; true if the target set had to be expanded, so a new
+  #     proxy is needed
+  def self.merge_sets!(target_set, source_set)
+    expanded = false
+    source_set.each do |class_id, label_classes|
+      target_classes = target_set[class_id]
+      if nil == target_classes
+        target_set[class_id] = label_classes.dup
+        expanded = true
+      else
+        target_classes.merge! label_classes
+      end
+    end
+    expanded
+  end
+
+  # Applies sticky labels to a piece of data.
+  #
+  # @private
+  # This is an version of {Police::DataFlow.label} optimized for sticky label
+  # propagation. User code should not depend on it.
+  #
+  # @param [BasicObject] data the data that will be labeled
+  # @param [Hash<Integer,Hash<Police::DataFlow::Label,Boolean>>] sticky_set a
+  #     set of sticky labels that
+  # @param [Police::DataFlow::Label] label the label to be applied to the
+  #     object
+  # @return [BasicObject] either the given piece of data, or a proxy that
+  #     should be used instead of it
+  def self.bulk_sticky_label(data, sticky_set)
+    label_set = data.__police_labels__
+    if nil == label_set
+      # Unlabeled data.
+      return Police::DataFlow::Proxying.proxy(data, dup_set(sticky_set))
+    end
+
+    # TODO(pwnall): implement copy-on-write to waste less memory on gated ops
+    if merge_sets! label_set, sticky_set
+      Police::DataFlow::Proxying.proxy data.__police_proxied__, label_set
+    else
+      data
+    end
+  end
+
+  # Creates a shallow copy of a label set.
+  #
+  # The resulting copy is slightly deeper than what {Hash#clone} would produce,
+  # because the groups are copied as well.
+  #
+  # @param [Hash<Integer,Hash<Police::DataFlow::Label,Boolean>>] label_set the
+  #     set of labels that will be copied
+  # @return [Hash<Integer,Hash<Police::DataFlow::Label,Boolean>>] label_set a
+  #     copy of the given label set that can be used with another object's
+  #     proxy
+  def self.dup_set(label_set)
+    Hash[label_set.map { |k, v| [k, v.dup] } ]
+  end
 end  # namespace Police::DataFlow::Labeling
-  
+
 end  # namespace Police::DataFlow
 
 end  # namespace Police

data/lib/police/dataflow/proxies.rb

@@ -9,7 +9,7 @@ module Proxies
   # @param [Class] proxied_class the class whose instances will be proxied by
   #     instances of the returned class
   # @param [Hash<Integer,Hash<Police::DataFlow::Label,Boolean>>] label_set the
-  #     set of all labels that will be carried by the proxied object
+  #     set of all labels that will be held by the proxy
   # @return [Class] a Police::DataFlow::ProxyBase subclass that can proxy
   #     instances of the given class
   def self.for(proxied_class, label_set)
@@ -17,20 +17,48 @@ module Proxies
       class_cache = {}
       @classes[proxied_class] = class_cache
     end
-     
+
     cache_key = label_set.keys.sort!.freeze
     return class_cache[cache_key] if class_cache.has_key? cache_key
-    
+
     label_classes = label_set.map { |label_key, label_hash|
       label_hash.first.first.class
     }.sort_by!(&:__id__).freeze
 
-    proxy_class = Class.new Police::DataFlow::ProxyBase
-    proxy_class.__police_classes__ = label_classes
+    proxy_class = for! proxied_class, label_classes
     class_cache[cache_key] = proxy_class
     proxy_class
   end
 
+  # A class whose instances proxy instances of a Ruby class.
+  #
+  # @private
+  # Use for instead of calling this directly.
+  #
+  # @param [Class] proxied_class the class whose instances will be proxied by
+  #     instances of the returned class
+  # @param [Array<Class>] label_classes classes for all the labels that will be
+  #     held by proxies instantiated from this class; the array should not have
+  #     duplicates
+  # @return [Class] a Police::DataFlow::ProxyBase subclass that can proxy
+  #   instances of the given class
+  def self.for!(proxied_class, label_classes)
+    proxy_class = nil
+    klass = proxied_class
+    until klass == nil
+      if klass == String
+        # TODO(pwnall): String-specific proxying
+        break
+      elsif klass == Numeric
+        proxy_class = Class.new Police::DataFlow::ProxyNumeric
+      end
+      klass = klass.superclass
+    end
+    proxy_class ||= Class.new Police::DataFlow::ProxyBase
+    proxy_class.__police_classes__ = label_classes
+    proxy_class
+  end
+
   # Clears the cache of proxy classes associated with Ruby classes.
   #
   # This method has a terrible impact on VM performance, and is only intended

data/lib/police/dataflow/proxy_base.rb

@@ -7,43 +7,62 @@ class ProxyBase < BasicObject
   # The object being proxied by this object.
   #
   # @private
-  # Use the Police::DataFlow API instead of reading this attribute directly.
+  # Use the {Police::DataFlow} API instead of reading this attribute directly.
   attr_reader :__police_proxied__
-  
-  # The Label instances attached to the proxied object.
+
+  # The {Police::DataFlow::Label} instances attached to the proxied object.
+  #
+  # This is a Hash whose keys are the __id__s of the Class objects for the
+  # labels' classes. The values are sets of labels that are instances of the
+  # corresponding label classes. Sets are implemented as Hashes mapping the
+  # label instances to boolean true values.
   #
   # @private
-  # Use the Police::DataFlow API instead of reading this attribute directly.
+  # Use the {Police::DataFlow} API instead of reading this attribute directly.
   attr_reader :__police_labels__
-  
-  # The subset of this object's labels whose autoflow? method returns true.
+
+  # Attached {Police::DataFlow::Label} instances whose classes are sticky.
+  #
+  # @private
+  # This is a proxying implementation detail and should not be relied on.
+  attr_reader :__police_stickies__
+
+  # The actual class of a proxy object.
+  #
+  # This is necessary because the class method for a proxy object must return
+  # the proxied object's class.
   #
   # @private
-  # This is an optimization used by the Police::DataFlow implementation. Do not
-  # read it directly.
-  attr_reader :__police_autoflows__
-  
+  # Use the {Police::DataFlow} API instead of reading this attribute directly.
+  attr_reader :__police_class__
+
   # Creates a proxied object.
   #
   # @param [Object] proxied the object that will receive messages sent to the
   #     newly created proxy
   # @param [Class<Police::DataFlow::ProxyBase>] proxy_class the
-  #     Police::DataFlow::ProxyBase subclass being instantiated; Object
+  #     {Police::DataFlow::ProxyBase} subclass being instantiated; Object
   #     instances can call Object#class to get to their class, but BasicObject
   #     instances don't have this luxury
   # @param [Hash<Integer,Hash<Police::DataFlow::Label,Boolean>>] label_set the
   #     set of all labels that will be held by the object's proxy
-  # @param [Hash<Integer,Hash<Police::DataFlow::Label,Boolean>>] autoflow_set
-  #     the set of labels whose autoflow? method returned true
-  def initialize(proxied, proxy_class, label_set, autoflow_set)
+  def initialize(proxied, proxy_class, label_set)
     @__police_proxied__ = proxied
     @__police_labels__ = label_set
 
+    # Cache the sticky labels to speed up certain computations.
+    @__police_stickies__ = {}
+    @__police_labels__.each do |class_id, instance_set|
+      label_class = instance_set.first.first.class
+      next unless label_class.sticky?
+      # NOTE: the set of instances is intentionally shared with
+      #       @__police_labels__ so updates to the former are automatically
+      #       reflected in the stickies cache
+      @__police_stickies__[class_id] = instance_set
+    end
+
     # Holds the object's class, because Object#class is not available.
     @__police_class__ = proxy_class
-
-    # Labels that flow automatically across method calls.
-    @__police_autoflows__ = autoflow_set
   end
 
   # Handles method calls to the proxied object.
@@ -54,77 +73,98 @@ class ProxyBase < BasicObject
     # Build a fast path for future method calls, if possible.
     respond_to_missing? name, true
 
+    # NOTE: going out of our way to use the fast path methods, because they
+    #       handle native method argument unwrapping correctly
+    if @__police_class__.method_defined?(name) ||
+        @__police_class__.private_method_defined?(name)
+      return __send__(name, *args, &block)
+    end
+
     if block
       return_value = @__police_proxied__.__send__ name, *args do |*yield_args|
         # Yielded values filtering.
         @__police_labels__.each do |_, label_hash|
-          next unless hook = label_hash.first.first.class.yield_args_hook(name)
-          label_hash.each do |label, _|
-            block_args = label.__send__ hook, self, yield_args, *args
+          label_class = label_hash.first.first.class
+          if hook = label_class.yield_args_hook(name)
+            label_hash.each do |label, _|
+              yield_args = label.__send__ hook, self, yield_args, *args
+            end
+          elsif label_class.sticky?
+            label_hash.each do |label, _|
+              yield_args.map! { |arg| ::Police::DataFlow.label arg, label }
+            end
           end
         end
-        
+
         yield_return = yield(*yield_args)
         # TODO(pwnall): consider adding a yield value filter
         next yield_return
       end
     else
-      return_value = @__police_proxied__.__send__ name, *args, &block
+      return_value = @__police_proxied__.__send__ name, *args
     end
-    
+
     # Return value filtering.
     @__police_labels__.each do |_, label_hash|
-      next unless hook = label_hash.first.first.class.return_hook(name)
-      label_hash.each do |label, _|
-        return_value = label.__send__ hook, return_value, self, *args
+      label_class = label_hash.first.first.class
+      if hook = label_hash.first.first.class.return_hook(name)
+        label_hash.each do |label, _|
+          return_value = label.__send__ hook, return_value, self, *args
+        end
+      elsif label_class.sticky?
+        label_hash.each do |label, _|
+          return_value = ::Police::DataFlow.label return_value, label
+        end
       end
     end
     return return_value
   end
-  
+
   # Called when Object#respond_to? returns false.
   def respond_to_missing?(name, include_private)
     return false unless @__police_proxied__.respond_to? name, include_private
-    
+
     # A method on the proxied object doesn't have a corresponding proxy.
     # Fix this by creating all possible proxies.
-    
+
     # NOTE: this approach is cheaper than creating proxies one by one, because
     #       it plays nice with method caches
-    
-    ::Police::DataFlow::Proxying.add_class_methods @__police_class__,
-                                                   @__police_proxied__.class
-    
+
+    ::Police::DataFlow::Proxying.add_instance_methods @__police_class__,
+                                                      @__police_proxied__.class
+
     # NOTE: we don't want to create unnecessary singleton classes
     # target_methods = @__police_proxied__.singleton_methods true
     # unless target_methods.empty?
     #  ::Police::DataFlow::Proxying.add_singleton_methods self,
     #      @__police_proxied__, target_methods
     # end
-    
+
     true
   end
-  
+
   # Ruby 1.9 throws scary warnings if proxies define object_id.
   # In either case, it's probably best to have it match __id__.
   alias object_id __id__
-  
+
   # Remove the == and != implementations from BasicObject, so that we can proxy
   # them. This is particularly important for String.
   #
   # NOTE: We don't remove equal?, because Object's documentation says that
   #       BasicObject subclasses should really not override it. We also don't
-  #       remove instance_eval and instance_exec, so the code that gets executed
-  #       using them will still have its method calls proxied correctly.
+  #       remove instance_eval and instance_exec, so the code that gets
+  #       executed using them will still have its method calls proxied
+  #       correctly.
   undef ==, !=
 
   class <<self
     # The classes of the labels supported by the proxy class.
     #
     # @private
-    # This is a Police::DataFlow implementation detail. Do not read it directly.
+    # This is a Police::DataFlow implementation detail. Do not read it
+    # directly.
     attr_accessor :__police_classes__
-  end  
+  end
 end  # class Police::DataFlow::ProxyBase
 
 end  # namespace Police::DataFlow

data/lib/police/dataflow/proxy_numeric.rb

@@ -0,0 +1,22 @@
+module Police
+
+module DataFlow
+
+# Base class for labeled Numeric replacements.
+class ProxyNumeric < ProxyBase
+  # Called when a regular Numeric is added, multiplied, etc to a proxied one.
+  #
+  # Wraps the regular Numeric instance with a proxy, so that call dispatch can
+  # take place.
+  def coerce(numeric)
+    if numeric.__police_labels__
+      return [numeric, self]
+    end
+    proxied_numeric = ::Police::DataFlow::Proxying.proxy numeric, {}
+    [proxied_numeric, self]
+  end
+end
+
+end  # namespace DataFlow
+
+end  # namespace Police