ruby_multiton 0.0.1.pre → 0.0.2.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e8cf6a0a0a714b94d3b1fb2ee4445c3eed9e463d
-  data.tar.gz: 60969f326372e90e304b652abf64b11f3fc27185
+  metadata.gz: afff779cb9cfe9e4064c5ae34eb3b586eb4d9fd8
+  data.tar.gz: a56bd90775c2936ac005e71096d2e18da0dc423d
 SHA512:
-  metadata.gz: e61c552243c7343d68fd446616fd3ab0b934fb6053b67701e726b790c345e01e60b7ea455c51f06b79c1e127502be4718fead2334ae35d0c838bcf9f66c2c5f7
-  data.tar.gz: 0b1ac68e83427d364f70a5983ad96a497956d50322cfc8c097bf942ac21ab8636e50943994c59b60a95e36fabaa2cfad64c0de66d79b39d0df807b4d3110134c
+  metadata.gz: 2fe09106e68a4a800ca2b14a6fcb8bca4c81a66d8ae97c77987a7b909f8a23223d6d3f29d9187821dbfafd5e00243954b21d84672d37dccf60baa60d54cdda1a
+  data.tar.gz: e065a49b34a460e8b7982becb9d5f39fc9752059f89b00c68088a774bc9f7edb0b95373a67828b5324d8ca2cb1bfb0eca7382f7028471eaf033fb3004672cf78

data/lib/multiton/instance_box.rb

@@ -0,0 +1,60 @@
+require "sync".freeze
+require "multiton/utils".freeze
+
+module Multiton
+  ##
+  # InstanceBox is a thread safe container for storing and retrieving multiton instances.
+  class InstanceBox
+    ##
+    # call-seq:
+    #   new => new_instance
+    #
+    # Returns a new InstanceBox instance.
+    def initialize
+      self.hash = {}
+      self.sync = Sync.new
+      self
+    end
+
+    ##
+    # call-seq:
+    #   get(key) => instance
+    #
+    # Returns the instance associated with +key+. If +key+ does not exist it returns +nil+.
+    def get(key)
+      sync.synchronize(:SH) { hash[key] }
+    end
+
+    ##
+    # call-seq:
+    #   key(instance) => key
+    #
+    # Returns the multiton key associated with +instance+. If +instance+ does not exist it returns +nil+.
+    def key(instance)
+      sync.synchronize(:SH) { Utils.hash_key(hash, instance) }
+    end
+
+    ##
+    # call-seq:
+    #   store(key, instance) => instance
+    #
+    # Stores +instance+ indexed by +key+.
+    #
+    # Returns +instance+.
+    def store(key, instance)
+      sync.synchronize(:EX) { hash[key] ||= instance }
+    end
+
+    private
+
+    ##
+    # A hash that contains the created instances indexed by their multiton key.
+    attr_accessor :hash
+
+    ##
+    # An instance of Sync[https://ruby-doc.org/stdlib-2.4.1/libdoc/sync/rdoc/Sync.html] to provide thread safety (via
+    # a {shared-exclusive lock}[https://en.wikipedia.org/wiki/Readers%E2%80%93writer_lock]) when reading and writing
+    # multiton instances to #hash.
+    attr_accessor :sync
+  end
+end

data/lib/multiton/mixin.rb

@@ -0,0 +1,38 @@
+module Multiton
+  ##
+  # Mixin adds appropriate behavior to multiton instances.
+  module Mixin
+    ##
+    # call-seq:
+    #   _dump(level) => string
+    #
+    # Serializes the instance as a string that can be reconstituted at a later point.
+    #
+    # Returns string.
+    def _dump(_level)
+      self.class.instance_variable_get(:@__multiton_instances).key self
+    end
+
+    ##
+    # call-seq:
+    #   clone
+    #
+    # Raises a TypeError[https://ruby-doc.org/core-2.4.1/TypeError.html] since multiton instances can not be cloned.
+    #
+    # Never returns.
+    def clone
+      raise TypeError, "can't clone instance of multiton `#{self.class.name}`"
+    end
+
+    ##
+    # call-seq:
+    #   dup
+    #
+    # Raises a TypeError[https://ruby-doc.org/core-2.4.1/TypeError.html] since multiton instances can not be duplicated.
+    #
+    # Never returns.
+    def dup
+      raise TypeError, "can't dup instance of multiton `#{self.class.name}`"
+    end
+  end
+end

data/lib/multiton/utils.rb

@@ -0,0 +1,30 @@
+module Multiton
+  ##
+  # Adds compatibility methods to support different Ruby versions.
+  module Utils
+    class << self
+      if RUBY_VERSION >= "1.9".freeze
+        ##
+        # call-seq:
+        #   hash_key(hash, value) => key
+        #
+        # Returns the key associated with +value+ on +hash+. If +value+ does not exist returns +nil+.
+        def hash_key(hash, value)
+          hash.key value
+        end
+      else
+        # :nocov:
+
+        ##
+        # call-seq:
+        #   hash_key(hash, value) => key
+        #
+        # Returns the key associated with +value+ on +hash+. If +value+ does not exist returns +nil+.
+        def hash_key(hash, value)
+          hash.index value
+        end
+        # :nocov:
+      end
+    end
+  end
+end

data/lib/multiton/version.rb

@@ -0,0 +1,5 @@
+module Multiton
+  ##
+  # Current version of Multiton.
+  VERSION = "0.0.2.pre".freeze
+end

data/lib/multiton.rb

@@ -0,0 +1,166 @@
+require "extensible".freeze
+require "multiton/instance_box".freeze
+require "multiton/mixin".freeze
+require "multiton/version".freeze
+
+##
+# The Multiton extension implements the {multiton pattern}[https://en.wikipedia.org/wiki/Multiton_pattern] in a manner
+# similar to Ruby standard library's Singleton[https://ruby-doc.org/stdlib-2.4.1/libdoc/singleton/rdoc/Singleton.html]
+# module. As a matter of fact Multiton can be used to implement the singleton pattern in a very straightforward way:
+#
+#   class C
+#     extend Multiton
+#   end
+#
+#   C.instance.object_id  #=> 47362978769640
+#   C.instance.object_id  #=> 47362978769640
+#
+# In order to generate and access different instances a +key+ must be provided as a parameter to the +initialize+
+# method:
+#
+#   class C
+#     extend Multiton
+#
+#     def initialize(key)
+#       # Initialize this instance (if needed).
+#     end
+#   end
+#
+#   one = C.instance(:one)
+#   two = C.instance(:two)
+#
+#   one.object_id               #=> 46941338337020
+#   C.instance(:one).object_id  #=> 46941338337020
+#
+#   two.object_id               #=> 46941338047140
+#   C.instance(:two).object_id  #=> 46941338047140
+#
+# Almost any object or set of objects will work as a valid +key+. The +key+ assembly is transparently handled by
+# Multiton internally, leaving the end user with an uncluttered and familiar way of designing their classes:
+#
+#   class Person
+#     extend Multiton
+#
+#     attr_reader :full_name
+#
+#     def initialize(name:, surname:)
+#       self.full_name = "#{surname}, #{name} --- (id: #{object_id})".freeze
+#     end
+#
+#     private
+#
+#     attr_writer :full_name
+#   end
+#
+#   alice = Person.instance(name: "Alice", surname: "Alcorta")
+#   bob = Person.instance(name: "Bob", surname: "Berman")
+#
+#   alice.full_name                                               #=> "Alcorta, Alice --- (id: 46921440327980)"
+#   Person.instance(name: "Alice", surname: "Alcorta").full_name  #=> "Alcorta, Alice --- (id: 46921440327980)"
+#
+#   bob.full_name                                                 #=> "Berman, Bob --- (id: 46921440022260)"
+#   Person.instance(name: "Bob", surname: "Berman").full_name     #=> "Berman, Bob --- (id: 46921440022260)"
+#
+# Note that even though keyword arguments will work with Multiton, passing the keywords in a different order will
+# generate a different instance. It is left up to the end user to design their +key+ in a way that minimizes the
+# possibility of improper use.
+module Multiton
+  extend Extensible
+
+  when_extended do |klass|
+    unless klass.is_a? Class
+      raise TypeError, "expected to extend object of type `Class` with module `#{name}`, got `#{klass.class}` instead"
+    end
+
+    klass.class_eval do
+      include Mixin
+      @__multiton_instances = InstanceBox.new
+    end
+  end
+
+  ##
+  # call-seq:
+  #   _load(args_string) => an_instance
+  #
+  # Creates or reconstitutes a multiton instance from +args_string+, which is a marshalled representation of the +key+
+  # argument(s) passed to #instance.
+  #
+  # Returns a multiton instance.
+  def _load(args_string)
+    instance(*Marshal.load(args_string)) # rubocop:disable Security/MarshalLoad
+  end
+
+  ##
+  # call-seq:
+  #   dup => a_class
+  #
+  # Creates a duplicate of the multiton class. Instances will not be shared between the original and duplicate classes.
+  #
+  # Returns a new class.
+  def dup
+    super.tap {|klass| klass.instance_variable_set(:@__multiton_instances, InstanceBox.new) }
+  end
+
+  ##
+  # call-seq:
+  #   instance(*args_key) => an_instance
+  #
+  # Creates or retrieves the instance corresponding to +args_key+.
+  #
+  # Returns a multiton instance.
+  def instance(*args_key)
+    key = Marshal.dump(args_key)
+    @__multiton_instances.get(key) || @__multiton_instances.store(key, new(*args_key))
+  end
+
+  private
+
+  ##
+  # call-seq:
+  #   allocate => nil
+  #
+  # Empty implementation of the +allocate+ method to block the original implemented in +Class+. Effectively does
+  # nothing.
+  #
+  # Returns +nil+.
+  def allocate; end
+
+  ##
+  # call-seq:
+  #   inherited(subclass) => nil
+  #
+  # This is called when a multiton class is inherited to properly initialize +subclass+. Instances will not be shared
+  # between the superclass and its subclasses.
+  #
+  # Returns +nil+.
+  def inherited(subclass)
+    super
+    subclass.instance_variable_set(:@__multiton_instances, InstanceBox.new)
+    nil
+  end
+
+  ##
+  # call-seq:
+  #   initialize_copy(source) => self
+  #
+  # This is called (on the clone) when a multiton class (+source+) is cloned to properly initialize it. Instances will
+  # not be shared between the original and cloned classes.
+  #
+  # Returns +self+.
+  def initialize_copy(_source)
+    super
+    extend Multiton
+    self
+  end
+
+  ##
+  # call-seq:
+  #   new(*args) => new_instance
+  #
+  # Creates a new multiton instance and initializes it by passing +args+ to its constructor.
+  #
+  # Returns a new multiton instance.
+  def new(*args)
+    super
+  end
+end

data/lib/ruby_multiton.rb

@@ -0,0 +1 @@
+require "multiton".freeze

data/ruby_multiton.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
     "*.gemspec".freeze,
     "LICENSE.*".freeze,
     "README.*".freeze,
-    "liv/**/*.rb".freeze
+    "lib/**/*.rb".freeze
   ]
   spec.name = "ruby_multiton".freeze
   spec.summary = "Ruby Multiton pattern implementation.".freeze

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_multiton
 version: !ruby/object:Gem::Version
-  version: 0.0.1.pre
+  version: 0.0.2.pre
 platform: ruby
 authors:
 - Gabriel de Oliveira
@@ -172,6 +172,12 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
+- lib/multiton.rb
+- lib/multiton/instance_box.rb
+- lib/multiton/mixin.rb
+- lib/multiton/utils.rb
+- lib/multiton/version.rb
+- lib/ruby_multiton.rb
 - ruby_multiton.gemspec
 homepage: https://github.com/gdeoliveira/ruby_multiton
 licenses: