cow_proxy 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 93c94796743b8e64ce62fca81e4b6cbb00d10c5e
+  data.tar.gz: 8c9097cc09c2691f13564318245dd9b09b7a580f
+SHA512:
+  metadata.gz: cb70d45374e3edc354755f2a39e4e7d2ece560ceb2739123f37a3ba6e54aea1931bc26585d13e3472ea389e6f0d246d5ad9ba230b7740f2d3f2472267ada8271
+  data.tar.gz: 4e87fb81c8fa67831e195f8f41b79e676c97c47f6dae5545b0f8ad129f672a76f662819d5727f4af8bda4fd70fa12831c003a96ca8b687e9fad47b337aa17e30

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2016-2017 Sergio Cambra
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,81 @@
+Overview
+========
+
+This is a copy-on-write proxy for frozen Ruby objects, so duplicating frozen object is delayed until a method tries to change frozen object.
+
+CowProxy classes for array, hash, string and struct are provided. Objects from other classes will be proxied without copy-on-write, you have to create a CowProxy class for them. Also you have to create CowProxy class for each object which have any getter method with arguments, because default CowProxy won't wrap returned value. Immutable classes such as Integer or TrueClass doesn't need copy-on-write proxy because they can't be changed.
+
+You can wrap every object in a proxy. Proxy will always send method calls to wrapped object, and wrap returned value with CowProxy if method had no argument, so a proxy will always return proxy objects for getters without arguments. When a method tries to change a frozen object, if proxy has copy-on-write enabled, it will duplicate frozen object and will send next method calls to duplicated object, in other case an exception is raised.
+
+Usage
+-----
+
+Call CowProxy.wrap with object to be proxied:
+
+```ruby
+CowProxy.wrap(obj)
+```
+
+It doesn't need to be a frozen object, it can be frozen later or only have references to frozen objects, but no object will be duplicated until some change is requested on frozen object.
+
+To create a CowProxy class for custom class, create a new class which inherits from CowProxy::WrapClass(CustomClass):
+
+```ruby
+module YourModule
+  class CustomProxy < CowProxy::WrapClass(CustomClass)
+  end
+end
+  
+obj = CustomClass.new(...)
+obj.freeze
+proxy = CowProxy.wrap(obj)
+```
+
+You can create proxy in CowProxy module too:
+
+```ruby
+module CowProxy
+  class CustomClass < WrapClass(::CustomClass)
+  end
+end
+```
+
+If your custom class has some getters with arguments, such as [] method of Array or Hash, you will have to define it in your Proxy so it wraps returned values and memoizes them, and override _copy_on_write to set memoized proxies to duplicated object. Wrapped object can be accessed from proxy with \__getobj\__ method. You can see an example in CowProxy::Container module, which is used for Array and Hash classes.
+ 
+If your custom class inherits from a class with CowProxy class, you don't need to create an own class, unless you need to override some method:
+ 
+ ```ruby
+module CowProxy
+  class CustomClass < Array
+    def custom_get(arg)
+      return @custom_var[index] if @custom_var && @custom_var.has_key?(arg)
+
+      begin
+        value = __getobj__.custom_get(arg)
+        return value if @custom_var.nil?
+        wrap_value = wrap(value)
+        @custom_var[index] = wrap_value if wrap_value
+        wrap_value || value
+      ensure
+        $@.delete_if {|t| /\A#{Regexp.quote(__FILE__)}:#{__LINE__-2}:/o =~ t} if $@
+      end
+    end
+
+    def initialize(obj, *)
+      super
+      @custom_var = {}
+    end
+
+    def _copy_on_write(*)
+      super.tap do
+        if @custom_var
+          @custom_var.each do |k, v|
+            __getobj__.custom_set(k, v)
+          end
+          @custom_var = nil
+        end
+      end
+    end
+  end
+end
+```

data/lib/cow_proxy.rb

@@ -0,0 +1,118 @@
+module CowProxy
+  class << self
+    @@wrapper_classes = {}
+
+    # create new proxy class for klass, with copy on write
+    # in other case CowProxy will wrap objects with class without copy on write
+    #
+    # module CowProxy
+    #   module MyModule
+    #     class MyClass < WrapClass(::MyModule::MyClass)
+    #     end
+    #   end
+    # end
+    def WrapClass(klass)
+      _WrapClass(klass)
+    end
+
+    # register proxy to be used when another proxy returns a value of klass,
+    # so it wraps with proxy_klass.
+    #
+    # called automatically when inheriting from class returned by WrapClass
+    def register_proxy(klass, proxy_klass)
+      puts "register proxy for #{klass} with #{proxy_klass} < #{proxy_klass.superclass}" if ENV['DEBUG'] && !@@wrapper_classes[klass]
+      @@wrapper_classes[klass] ||= proxy_klass
+    end
+
+    # return a proxy wrapping obj, using registered class for obj's class
+    # if no class is registered for obj, it uses default proxy without
+    # copy on write
+    def wrap(obj)
+      wrapper_class(obj).new(obj)
+    end
+
+    # returns proxy wrapper class for obj, registered proxy or default proxy
+    # without copy on write
+    def wrapper_class(obj)
+      # only classes with defined wrapper and Structs has COW enabled by default
+      @@wrapper_classes[obj.class] || _WrapClass(obj.class, obj.class < Struct, true)
+    end
+
+    protected
+    def wrapping_block(mid, cow_allowed)
+      lambda do |*args, &block|
+        target = __getobj__
+        inst_var = "@#{mid}" if mid.to_s =~ /^\w+$/
+        return _instance_variable_get(inst_var) if inst_var && _instance_variable_defined?(inst_var)
+        if mid.to_s =~ /^(\w+)=$/ && _instance_variable_defined?("@#{$1}")
+          Kernel.puts "remove #{$1}" if ENV['DEBUG']
+          _remove_instance_variable "@#{$1}"
+        end
+
+        cow = cow_allowed
+        begin
+          Kernel.puts "run on #{target.class.name} (#{target.object_id}) #{mid} #{args.inspect unless args.empty?}" if ENV['DEBUG']
+          value = target.__send__(mid, *args, &block)
+          if inst_var && args.empty? && block.nil?
+            wrap_value = wrap(value, inst_var)
+            _instance_variable_set(inst_var, wrap_value) if wrap_value
+          end
+          wrap_value || value
+        rescue => e
+          raise unless cow && e.message =~ /^can't modify frozen/
+          Kernel.puts "copy on write to run #{mid} #{args.inspect unless args.empty?} (#{e.message})" if ENV['DEBUG']
+          target = _copy_on_write
+          Kernel.puts "new target #{target.class.name} (#{target.object_id})" if ENV['DEBUG']
+          cow = false
+          retry
+        ensure
+          Kernel.puts '-----' if ENV['DEBUG']
+          # cleanup exception from cow proxy files
+          $@.delete_if {|t| /\A#{Regexp.quote(__FILE__)}:#{__LINE__-2}:/o =~ t} if $@
+        end
+      end
+    end
+
+    private
+    def _WrapClass(klass, cow = true, register = false)
+      proxy_superclass = get_proxy_klass_for(klass.superclass) || Base
+      Kernel.puts "create new proxy class for #{klass}#{" from #{proxy_superclass}" if proxy_superclass}" if ENV['DEBUG']
+      proxy_klass = Class.new(proxy_superclass) do |k|
+        k.wrapped_class = klass
+      end
+      register_proxy klass, proxy_klass if register
+      methods = klass.instance_methods
+      methods -= [:_copy_on_write, :===, :frozen?]
+      methods -= proxy_superclass.wrapped_class.instance_methods if proxy_superclass.wrapped_class
+      methods -= [:inspect] if ENV['DEBUG']
+
+      proxy_klass.module_eval do
+        methods.each do |method|
+          define_method method, CowProxy.send(:wrapping_block, method, cow)
+        end
+      end
+      proxy_klass.define_singleton_method :public_instance_methods do |all=true|
+        super(all) - klass.protected_instance_methods
+      end
+      proxy_klass.define_singleton_method :protected_instance_methods do |all=true|
+        super(all) | klass.protected_instance_methods
+      end
+      proxy_klass
+    end
+
+    def get_proxy_klass_for(klass)
+      wrapper = nil
+      klass.ancestors.each do |ancestor|
+        wrapper = @@wrapper_classes[ancestor] and break
+      end
+      wrapper
+    end
+  end
+end
+
+require 'cow_proxy/base.rb'
+require 'cow_proxy/container.rb'
+require 'cow_proxy/array.rb'
+require 'cow_proxy/hash.rb'
+require 'cow_proxy/string.rb'
+require 'cow_proxy/set.rb'

data/lib/cow_proxy/array.rb

@@ -0,0 +1,6 @@
+module CowProxy
+  class Array < WrapClass(::Array)
+    include Container
+  end
+
+end

data/lib/cow_proxy/base.rb

@@ -0,0 +1,50 @@
+module CowProxy
+  class Base
+    class << self
+      attr_accessor :wrapped_class
+
+      def inherited(subclass)
+        subclass.wrapped_class = wrapped_class
+        CowProxy.register_proxy wrapped_class, subclass if wrapped_class
+      end
+    end
+
+    def initialize(obj, parent = nil, parent_var = nil)
+      @delegate_dc_obj = obj
+      @parent_proxy = parent
+      @parent_var = parent_var
+    end
+
+    def _copy_on_write(parent = true)
+      Kernel.puts "copy on write on #{__getobj__.class.name}" if ENV['DEBUG']
+      @delegate_dc_obj = @delegate_dc_obj.dup.tap do |new_target|
+        if parent && @parent_proxy
+          @parent_proxy._copy_on_write(false)
+          if @parent_var
+            parent_dc = @parent_proxy._instance_variable_get(:@delegate_dc_obj)
+            method = @parent_var[1..-1] + '='
+            parent_dc.send(method, new_target)
+          end
+        end
+      end
+    end
+
+    private
+    def __getobj__  # :nodoc:
+      @delegate_dc_obj
+    end
+
+    def wrap(value, inst_var = nil)
+      if value.frozen?
+        Kernel.puts "wrap #{value.class.name} with parent #{self.class.name}" if ENV['DEBUG']
+        CowProxy.wrapper_class(value).new(value, self, inst_var)
+      end
+    end
+
+    alias :_instance_variable_get :instance_variable_get
+    alias :_instance_variable_set :instance_variable_set
+    alias :_remove_instance_variable :remove_instance_variable
+    alias :_instance_variable_defined? :instance_variable_defined?
+    alias :_instance_variables? :instance_variable_defined?
+  end
+end

data/lib/cow_proxy/container.rb

@@ -0,0 +1,33 @@
+module CowProxy
+  module Container
+    def [](index)
+      return @hash[index] if @hash && @hash.has_key?(index)
+
+      begin
+        value = __getobj__[index]
+        return value if @hash.nil?
+        wrap_value = wrap(value)
+        @hash[index] = wrap_value if wrap_value
+        wrap_value || value
+      ensure
+        $@.delete_if {|t| /\A#{Regexp.quote(__FILE__)}:#{__LINE__-2}:/o =~ t} if $@
+      end
+    end
+
+    def initialize(obj, *)
+      super
+      @hash = {}
+    end
+
+    def _copy_on_write(*)
+      super.tap do
+        if @hash
+          @hash.each do |k, v|
+            __getobj__[k] = v
+          end
+          @hash = nil
+        end
+      end
+    end
+  end
+end

data/lib/cow_proxy/hash.rb

@@ -0,0 +1,6 @@
+module CowProxy
+  class Hash < WrapClass(::Hash)
+    include Container
+  end
+
+end

data/lib/cow_proxy/set.rb

@@ -0,0 +1,7 @@
+require 'set'
+
+module CowProxy
+  class Set < WrapClass(::Set)
+  end
+
+end

data/lib/cow_proxy/string.rb

@@ -0,0 +1,4 @@
+module CowProxy
+  class String < WrapClass(::String)
+  end
+end

data/lib/cow_proxy/version.rb

@@ -0,0 +1,9 @@
+module CowProxy
+  module Version
+    MAJOR = 0
+    MINOR = 1
+    PATCH = 0
+
+    STRING = [MAJOR, MINOR, PATCH].compact.join('.')
+  end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: cow_proxy
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sergio Cambra
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-03-16 00:00:00.000000000 Z
+dependencies: []
+description: Make a COW proxy for a frozen object (or deep frozen), it will delegate
+  every read method to proxied object, wrap value in COW proxy if frozen. Trying to
+  modify object will result in data stored in proxy.
+email: sergio@programatica.es
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- LICENSE
+- README.md
+- lib/cow_proxy.rb
+- lib/cow_proxy/array.rb
+- lib/cow_proxy/base.rb
+- lib/cow_proxy/container.rb
+- lib/cow_proxy/hash.rb
+- lib/cow_proxy/set.rb
+- lib/cow_proxy/string.rb
+- lib/cow_proxy/version.rb
+homepage: http://github.com/Programatica/cow_proxy
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.10
+signing_key: 
+specification_version: 4
+summary: Copy-on-write proxy class, to use with frozen objects
+test_files: []