facets-glimmer 3.2.0

data/lib/standard/facets/memoizable.rb

@@ -0,0 +1,141 @@
+# Memoization is an optimization technique used primarily to speed up 
+# programs by having function calls avoid repeating the calculation
+# of results for previously-processed inputs.
+#
+# When you "memoize" a method/function using Memoizable its results are cached
+# so that later calls return results from the cache instead of recalculating
+# them.
+#
+#   class T
+#     include Memoizable
+#
+#     def initialize(a)
+#       @a = a
+#     end
+#
+#     def a
+#       "#{@a ^ 3 + 4}"
+#     end
+#
+#     memoize :a
+#   end
+#
+#   t = T.new(10)
+#   (t.a.__id__ == t.a.__id__)  #=> true
+#
+# This method can also be used at the instance level to cache singleton
+# (qua class) methods by including it in the singleton class.
+#
+#--
+# TODO: It would be very cool if Memoizable could set-up default parameters
+# via #[] method, e.g. `include Memoizable[:freeze=>true]`.
+#++
+
+module Memoizable
+
+  @cache = Hash.new{|h,k|h[k]=Hash.new{|h,k|h[k]={}}}
+
+  #
+  def self.cache
+    @cache
+  end
+
+  #
+  def self.append_features(base)
+    Module == base ? super(base) : base.extend(self)
+  end
+
+  # Directive for making your functions faster by trading space for time.
+  # When you "memoize" a method/function using #memoize its results are
+  # cached so that later calls with the same arguments return results from
+  # the cache instead of recalculating them.
+  #
+  # The #memoize method also handles a few options to alter
+  # behavior of the memoization:
+  #
+  #   :class     => true      cache per-class not per-object
+  #   :freeze    => true      freeze the memoized return values
+  #   :arguments => false     do not index cache by arguments
+  #
+  def memoize(*method_names)
+    options = Hash === method_names.last ? method_names.pop : {}
+
+    options[:arguments] = true if options[:arguments].nil?  # default to true
+
+    ref = options[:class]     ? 'self.class.name'       : 'self'
+    frz = options[:freeze]    ? '.freeze'               : ''
+    arg = options[:arguments] ? '[__a__, block_given?]' : 'nil'
+
+    code = ""
+    method_names.each do |m|
+      code << <<-code
+        alias_method '#{ m }:memo', '#{ m }'
+        private '#{ m }:memo'
+        def #{ m }(*__a__,&__b__)
+          c = Memoizable.cache[#{ref}][:'#{ m }']
+          k = #{arg}
+          if c.has_key?(k)
+            c[k]
+          else
+            c[k] = __send__('#{ m }:memo',*__a__,&__b__)#{frz}
+          end
+        end
+      code
+    end
+    module_eval(code)
+  end
+
+  # Remove the memoized value from the memoization cache.
+  # The next time a memoized methos is called if will be
+  # remomoized.
+  def rememoize(*method_names)
+    if Memoizable.cache[self]
+      if method_names.empty?
+        Memoizable.cache.delete(self)
+      else
+        method_names.each do |m|
+          Memoizable.cache[self].delete(m.to_sym)
+        end
+      end
+    end
+    if Memoizable.cache[self.class.name]
+      if method_names.empty?
+        Memoizable.cache.delete(self.class.name)
+      else
+        method_names.each do |m|
+          Memoizable.cache[self.class.name].delete(m.to_sym)
+        end
+      end
+    end
+  end
+
+  #
+  def unmemoize(*method_names)
+    rememoize(*method_names)
+    method_names.each do |m|
+      alias_method name, "#{ m }:memo"
+    end
+  end
+
+  # Include Memoizable alone with an #initialize_copy method that
+  # will copy the memoization cache when #dup or #clone is used.
+  #
+  # TODO: Is this best approach? Perhaps a method to easily create
+  # the #initialize_copy method would suffice?
+  module Copy
+
+    #
+    def self.included(base)
+      base.extend(Memoizable)
+    end 
+
+    #
+    def initialize_copy(original)
+      if Memoizable.cache.key?(original)
+        Memoizable.cache[self] = Memoizable.cache[original].dup
+      end
+    end
+
+  end
+
+end

data/lib/standard/facets/memoizer.rb

@@ -0,0 +1,63 @@
+# Memoizer wraps objects to provide cached method calls.
+#
+#   class X
+#     def initialize ; @tick = 0 ; end
+#     def tick; @tick + 1; end
+#     def memo; @memo ||= Memoizer.new(self) ; end
+#   end
+#
+#   x = X.new
+#   x.tick       #=> 1
+#   x.memo.tick  #=> 2
+#   x.tick       #=> 3
+#   x.memo.tick  #=> 2
+#   x.tick       #=> 4
+#   x.memo.tick  #=> 2
+#
+# You can also use to cache collections of objects to gain code speed ups.
+#
+#   points = points.collect{|point| Memoizer.cache(point)}
+#
+# After our algorithm has finished using points, we want to get rid of
+# these Memoizer objects. That's easy:
+#
+#    points = points.collect{|point| point.__self__ }
+#
+# Or if you prefer (it is ever so slightly safer):
+#
+#    points = points.collect{|point| Memoizer.uncache(point)}
+#
+# Memoizer is the work of Erik Veenstra
+#
+# Copyright (c) 2006 Erik Veenstra
+#
+# See http://javathink.blogspot.com/2008/09/what-is-memoizer-and-why-should-you.html
+
+class Memoizer
+
+  #private :class, :clone, :display, :type, :method, :to_a, :to_s
+  private *instance_methods(true).select{ |m| m.to_s !~ /^__/ }
+
+  def initialize(object)
+    @self  = object
+    @cache = {}
+  end
+
+  def __self__ ; @self ; end
+
+  # Not thread-safe! Speed is important in caches... ;]
+  def method_missing(method_name, *args, &block)
+    @cache[[method_name, args, block]] ||= @self.__send__(method_name, *args, &block)
+  end
+
+  #def self; @self; end
+
+  def self.cache(object)
+    new(object)
+  end
+
+  def self.uncache(cached_object)
+    cached_object.instance_variable_get('@self')
+  end
+
+end

data/lib/standard/facets/multipliers.rb

@@ -0,0 +1,65 @@
+class Numeric
+
+  # = Numeric::Multipliers
+  #
+  # Adds methods to Numeric to make working with
+  # magnitudes (kilo, mega, giga, milli, micro, etc.)
+  #
+  #   1.kilo               #=> 1000
+  #   1.milli              #=> 0.001
+  #   1.kibi               #=> 1024
+  #
+  # To display a value in a certain denomination, simply
+  # perform the inverse operation by placing the
+  # multiplier called on unit (1) in the denominator.
+  #
+  #   (1000 / 1.kilo)        #=> 1
+  #   (1024 / 1.kibi)        #=> 1
+  #
+  # Thanks to Rich Kilmer and bytes.rb which inspired this library.
+
+  module Multipliers
+
+    # SI Multipliers
+
+    def deka  ; self * 10 ; end
+    def hecto ; self * 100 ; end
+    def kilo  ; self * 1000 ; end
+    def mega  ; self * 1000000 ; end
+    def giga  ; self * 1000000000 ; end
+    def tera  ; self * 1000000000000 ; end
+    def peta  ; self * 1000000000000000 ; end
+    def exa   ; self * 1000000000000000000 ; end
+
+    # SI Fractional
+
+    def deci  ; self.to_f / 10 ; end
+    def centi ; self.to_f / 100 ; end
+    def milli ; self.to_f / 1000 ; end
+    def micro ; self.to_f / 1000000 ; end
+    def nano  ; self.to_f / 1000000000 ; end
+    def pico  ; self.to_f / 1000000000000 ; end
+    def femto ; self.to_f / 1000000000000000 ; end
+    def atto  ; self.to_f / 1000000000000000000 ; end
+
+    # SI Binary
+
+    def kibi ; self * 1024 ; end
+    def mebi ; self * 1024**2 ; end
+    def gibi ; self * 1024**3 ; end
+    def tebi ; self * 1024**4 ; end
+    def pebi ; self * 1024**5 ; end
+    def exbi ; self * 1024**6 ; end
+
+    # Bits and Bytes
+
+    #def bit   ; self ; end
+    #def bits  ; self ; end
+    #def byte  ; self * 8 ; end
+    #def bytes ; self * 8 ; end
+  end
+
+  include Multipliers
+end
+
+# Copyright (c) 2005 Thomas Sawyer

data/lib/standard/facets/multiton.rb

@@ -0,0 +1,387 @@
+# = Multiton
+#
+# == Synopsis
+#
+# Multiton design pattern ensures only one object is allocated for a given state.
+#
+# The 'multiton' pattern is similar to a singleton, but instead of only one
+# instance, there are several similar instances.  It is useful when you want to
+# avoid constructing objects many times because of some huge expense (connecting
+# to a database for example), require a set of similar but not identical
+# objects, and cannot easily control how many times a contructor may be called.
+#
+#   class SomeMultitonClass
+#     include Multiton
+#     attr :arg
+#     def initialize(arg)
+#       @arg = arg
+#     end
+#   end
+#
+#   a = SomeMultitonClass.new(4)
+#   b = SomeMultitonClass.new(4)   # a and b are same object
+#   c = SomeMultitonClass.new(2)   # c is a different object
+#
+# == Previous Behavior
+#
+# In previous versions of Multiton the #new method was made
+# private and #instance had to be used in its stay --just like Singleton.
+# But this is less desirable for Multiton since Multitions can
+# have multiple instances, not just one.
+#
+# So instead Multiton now defines #create as a private alias of
+# the original #new method (just in case it is needed) and then
+# defines #new to handle the multiton; #instance is provided
+# as an alias for it.
+#
+#--
+# So if you must have the old behavior, all you need do is re-alias
+# #new to #create and privatize it.
+#
+#   class SomeMultitonClass
+#     include Multiton
+#     alias_method :new, :create
+#     private :new
+#     ...
+#   end
+#
+# Then only #instance will be available for creating the Multiton.
+#++
+#
+# == How It Works
+#
+# A pool of objects is searched for a previously cached object,
+# if one is not found we construct one and cache it in the pool
+# based on class and the args given to the contructor.
+#
+# A limitation of this approach is that it is impossible to
+# detect if different blocks were given to a contructor (if it takes a
+# block).  So it is the constructor arguments _only_ which determine
+# the uniqueness of an object. To workaround this, define the _class_
+# method ::multiton_id.
+#
+#   def SomeMultitonClass.multiton_id(*args, &block)
+#     # ...
+#   end
+#
+# Which should return a hash key used to identify the object being
+# constructed as (not) unique.
+#
+# == Authors
+#
+# * Christoph Rippel
+# * Thomas Sawyer
+#
+# = Copying
+#
+# Copyright (c) 2007 Christoph Rippel, Thomas Sawyer
+#
+# Ruby License / BSD-2 License
+#
+# This module is free software. You may use, modify, and/or redistribute this
+# software under the same terms as Ruby.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.
+
+require 'thread'
+
+# = Multiton
+#
+# Multiton design pattern ensures only one object is allocated for a given state.
+#
+# The 'multiton' pattern is similar to a singleton, but instead of only one
+# instance, there are several similar instances.  It is useful when you want to
+# avoid constructing objects many times because of some huge expense (connecting
+# to a database for example), require a set of similar but not identical
+# objects, and cannot easily control how many times a contructor may be called.
+#
+#   class SomeMultitonClass
+#     include Multiton
+#     attr :arg
+#     def initialize(arg)
+#       @arg = arg
+#     end
+#   end
+#
+#   a = SomeMultitonClass.new(4)
+#   b = SomeMultitonClass.new(4)   # a and b are same object
+#   c = SomeMultitonClass.new(2)   # c is a different object
+#
+# == How It Works
+#
+# A pool of objects is searched for a previously cached object,
+# if one is not found we construct one and cache it in the pool
+# based on class and the args given to the contructor.
+#
+# A limitation of this approach is that it is impossible to
+# detect if different blocks were given to a contructor (if it takes a
+# block).  So it is the constructor arguments _only_ which determine
+# the uniqueness of an object. To workaround this, define the _class_
+# method ::multiton_id.
+#
+#   def SomeMultitonClass.multiton_id(*args, &block)
+#     # ...
+#   end
+#
+# Which should return a hash key used to identify the object being
+# constructed as (not) unique.
+
+module Multiton
+
+  # Disable build-in copying methods.
+
+  def clone
+    raise TypeError, "can't clone Multiton #{self}"
+    ##self
+  end
+
+  def dup
+    raise TypeError, "can't dup Multiton #{self}"
+    ##self
+  end
+
+  # Default marshalling strategy.
+
+  protected
+
+  def _dump(depth=-1)
+    Marshal.dump(@multiton_initializer)
+  end
+
+  # Mutex to safely store multiton instances.
+
+  class InstanceMutex < Hash  #:nodoc:
+    def initialize
+      @global = Mutex.new
+    end
+
+    def initialized(arg)
+      store(arg, DummyMutex)
+    end
+
+    def (DummyMutex = Object.new).synchronize
+      yield
+    end
+
+    def default(arg)
+      @global.synchronize{ fetch(arg){ store(arg, Mutex.new) } }
+    end
+  end
+
+  # Multiton can be included in another module, in which case that module
+  # effectively becomes a multiton behavior distributor too. This is why we
+  # propogate #included to the base module by putting it in another module.
+  #
+  #--
+  #    def append_features(mod)
+  #      # help out people counting on transitive mixins
+  #      unless mod.instance_of?(Class)
+  #        raise TypeError, "Inclusion of Multiton in module #{mod}"
+  #      end
+  #      super
+  #    end
+  #++
+
+  module Inclusive
+    private
+    def included(base)
+      class << base
+        ##alias_method(:new!, :new) unless method_defined?(:new!)
+        ## gracefully handle multiple inclusions of Multiton
+        unless include?(Multiton::MetaMethods)
+          alias_method :new!, :new
+          private :allocate #, :new
+          include Multiton::MetaMethods
+
+          if method_defined?(:marshal_dump)
+            undef_method :marshal_dump
+            warn "warning: marshal_dump was undefined since it is incompatible with the Multiton pattern"
+          end
+        end
+      end
+    end
+  end
+
+  extend Inclusive
+
+  #
+
+  module MetaMethods
+
+    include Inclusive
+
+    def instance(*e, &b)
+      arg = multiton_id(*e, &b)
+      multiton_instance.fetch(arg) do
+        multiton_mutex[arg].synchronize do
+          multiton_instance.fetch(arg) do
+            val = multiton_instance[arg] = new!(*e, &b) #new(*e, &b)
+            val.instance_variable_set(:@multiton_initializer, e, &b)
+            multiton_mutex.initialized(arg)
+            val
+          end
+        end
+      end
+    end
+    alias_method :new, :instance
+
+    def initialized?(*e, &b)
+      multiton_instance.key?(multiton_id(*e, &b))
+    end
+
+    protected
+
+    def multiton_instance
+      @multiton_instance ||= Hash.new
+    end
+
+    def multiton_mutex
+      @multiton_mutex ||= InstanceMutex.new
+    end
+
+    def reinitialize
+      multiton_instance.clear
+      multiton_mutex.clear
+    end
+
+    def _load(str)
+      instance(*Marshal.load(str))
+    end
+
+    private
+
+    # Default method to to create a key to cache already constructed
+    # instances. In the use case MultitonClass.new(e), MultiClass.new(f)
+    # must be semantically equal if multiton_id(e).eql?(multiton_id(f))
+    # evaluates to true.
+    def multiton_id(*e, &b)
+      e
+    end
+
+    def singleton_method_added(sym)
+      super
+      if (sym == :marshal_dump) & singleton_methods.include?('marshal_dump')
+        raise TypeError, "Don't use marshal_dump - rely on _dump and _load instead"
+      end
+    end
+
+  end
+
+end
+
+
+
+
+=begin
+# TODO: Convert this into a real test and/or benchmark.
+
+if $0 == __FILE__
+
+  ### Simple marshalling test #######
+  class A
+    def initialize(a,*e)
+      @e = a
+    end
+
+    include Multiton
+    begin
+      def self.marshal_dump(depth = -1)
+      end
+    rescue => mes
+      p mes
+      class << self; undef marshal_dump end
+    end
+  end
+
+  C = Class.new(A.clone)
+  s = C.instance('a','b')
+
+  raise unless Marshal.load(Marshal.dump(s)) == s
+
+
+  ### Interdependent initialization example and threading benchmark ###
+
+  class Regular_SymPlane
+    def self.multiton_id(*e)
+        a,b = e
+        (a+b - 1)*(a+b )/2  + (a > b ? a : b)
+    end
+
+    def initialize(a,b)
+      klass = self.class
+      if a < b
+        @l =  b > 0 ?  klass.instance(a,b-1) : nil
+        @r =  a > 0 ?  klass.instance(a-1,b) : nil
+      else
+        @l =  a > 0 ?  klass.instance(a-1,b) : nil
+        @r =  b > 0 ?  klass.instance(a,b-1) : nil
+      end
+    end
+
+    include Multiton
+  end
+
+
+
+  def nap
+  # Thread.pass
+  sleep(rand(0.01))
+  end
+
+  class SymPlane < Regular_SymPlane
+    @m = Mutex.new
+    @count = 0
+  end
+
+  class << SymPlane
+    attr_reader :count
+    def reinitialize
+      super
+      @m = Mutex.new
+      @count = 0
+    end
+    def inherited(sub_class)
+      super
+      sub_class.instance_eval { @m = Mutex.new; @count = 0 }
+    end
+
+    def multiton_id(*e)
+      nap()
+      super
+    end
+
+    def new!(*e)  # NOTICE!!!
+      super
+    ensure
+      nap()
+      @m.synchronize { p @count if (@count += 1) % 15 == 0 }
+    end
+
+    def run(k)
+      threads = 0
+      max = k * (k+1) / 2
+      puts ""
+      while count() < max
+        Thread.new { threads+= 1; instance(rand(30),rand(30)) }
+      end
+      puts "\nThe simulation created #{threads} threads"
+    end
+  end
+
+
+  require 'benchmark'
+  include Benchmark
+
+  bmbm do |x|
+    x.report('Initialize 465 SymPlane instances') { SymPlane.run(30) }
+    x.report('Reinitialize ') do
+      sleep 3
+      SymPlane.reinitialize
+    end
+  end
+
+end
+=end
+

data/lib/standard/facets/net/http.rb

@@ -0,0 +1,51 @@
+require 'net/http'
+
+module Net
+
+  # Returns a response object for the given URL or raises
+  # an exception with the appropriate error status code if unable to
+  # complete the request
+  #
+  #   Net.download('http://example.com/')
+  #   Net.download('http://example.com/', 2) # fail after 2 redirects
+  #
+  # CREDIT: Daniel Huckstep
+  def self.download(url, limit = nil)
+    limit ||= 10
+    raise ArgumentError, 'HTTP redirect too deep' if limit.zero?
+    resp = Net::HTTP.get_response(URI.parse(url))
+    case resp
+    when Net::HTTPSuccess     then resp
+    when Net::HTTPRedirection then download(resp['location'], limit - 1)
+    else resp.error!
+    end
+  end
+
+  # Downloads a given URL and saves it to disk at the specified path.
+  # If path is not provided or nil, then the last segment in the path of
+  # the URL is used as the file name.
+  #
+  # Takes a third parameters as a hash of options:
+  # * <tt>limit</tt> - passed to Net.download to limit number of redirects
+  # * <tt>mode</tt>, <tt>:open_args<tt>, etc - passed to File.write to save the file.
+  #   For details on those options, see File.write
+  #
+  #   # Saves robots.txt to PWD as robots.txt
+  #   Net.download_and_save('http://example.com/robots.txt')
+  #
+  #   # Saves robots.txt to PWD as example.txt
+  #   Net.download_and_save('http://example.com/robots.txt', 'example.txt')
+  #
+  #   # Saves robots.txt to PWD as robots.txt, and writes the result as binary
+  #   Net.download_and_save('http://example.com/robots.txt', nil, mode: 'wb')
+  #
+  # CREDIT: Daniel Huckstep
+  def self.download_and_save(url, path = nil, options = {})
+    opts = options.dup
+    path = File.expand_path(path || url.split('/').last)
+    raise ArgumentError.new('Save path is a directory') if File.directory?(path)
+    resp = download(url, opts.delete(:limit))
+    File.write(path, resp.body, opts) if resp.is_a?(Net::HTTPSuccess)
+  end
+end
+