rubysl-singleton 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a68b8b94eadd7fe3c8e3f30ff58b1fb1d0303481
+  data.tar.gz: 4f0af342cda53ce98431f81227ea3fdced184877
+SHA512:
+  metadata.gz: 04dfdf1c1cb3776b10f8100c2d650c3aaf3d58d7224460ce800ebd3eff49d8cc251510a07367b80645617e85acd282953433fbb10d8580327e59774d6a6a085d
+  data.tar.gz: add0ca325e06b7e6cb6c5d46d016a7a7e7175df4db5e5e96ade43f4bfe411311c867902d8ad58bf495a84f605aaf8891bbb95c4b86644b36d4d7727e3bf0304d

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+before_install:
+  - gem update --system
+  - gem --version
+  - gem install rubysl-bundler
+script: bundle exec mspec spec
+rvm:
+  - rbx-nightly-18mode

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in rubysl-singleton.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2013, Brian Shirai
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+3. Neither the name of the library nor the names of its contributors may be
+   used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,29 @@
+# Rubysl::Singleton
+
+TODO: Write a gem description
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'rubysl-singleton'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rubysl-singleton
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/rubysl/singleton.rb

@@ -0,0 +1,2 @@
+require "rubysl/singleton/singleton"
+require "rubysl/singleton/version"

data/lib/rubysl/singleton/singleton.rb

@@ -0,0 +1,313 @@
+# The Singleton module implements the Singleton pattern.
+#
+# Usage:
+#    class Klass
+#       include Singleton
+#       # ...
+#    end
+#
+# *  this ensures that only one instance of Klass lets call it
+#    ``the instance'' can be created.
+#
+#      a,b  = Klass.instance, Klass.instance
+#      a == b    # => true
+#      Klass.new #  NoMethodError - new is private ...
+#
+# *  ``The instance'' is created at instantiation time, in other
+#    words the first call of Klass.instance(), thus
+#
+#      class OtherKlass
+#        include Singleton
+#        # ...
+#      end
+#      ObjectSpace.each_object(OtherKlass){} # => 0.
+#
+# *  This behavior is preserved under inheritance and cloning.
+#
+#
+#
+# This is achieved by marking
+# *  Klass.new and Klass.allocate - as private
+#
+# Providing (or modifying) the class methods
+# *  Klass.inherited(sub_klass) and Klass.clone()  -
+#    to ensure that the Singleton pattern is properly
+#    inherited and cloned.
+#
+# *  Klass.instance()  -  returning ``the instance''. After a
+#    successful self modifying (normally the first) call the
+#    method body is a simple:
+#
+#       def Klass.instance()
+#         return @singleton__instance__
+#       end
+#
+# *  Klass._load(str)  -  calling Klass.instance()
+#
+# *  Klass._instantiate?()  -  returning ``the instance'' or
+#    nil. This hook method puts a second (or nth) thread calling
+#    Klass.instance() on a waiting loop. The return value
+#    signifies the successful completion or premature termination
+#    of the first, or more generally, current "instantiation thread".
+#
+#
+# The instance method of Singleton are
+# * clone and dup - raising TypeErrors to prevent cloning or duping
+#
+# *  _dump(depth) - returning the empty string.  Marshalling strips
+#    by default all state information, e.g. instance variables and
+#    taint state, from ``the instance''.  Providing custom _load(str)
+#    and _dump(depth) hooks allows the (partially) resurrections of
+#    a previous state of ``the instance''.
+
+require 'thread'
+
+module Singleton
+  #  disable build-in copying methods
+  def clone
+    raise TypeError, "can't clone instance of singleton #{self.class}"
+  end
+  def dup
+    raise TypeError, "can't dup instance of singleton #{self.class}"
+  end
+
+  #  default marshalling strategy
+  def _dump(depth = -1)
+    ''
+  end
+
+  module SingletonClassMethods
+    # properly clone the Singleton pattern - did you know
+    # that duping doesn't copy class methods?
+    def clone
+      Singleton.__init__(super)
+    end
+
+    def _load(str)
+      instance
+    end
+
+    private
+
+    #  ensure that the Singleton pattern is properly inherited
+    def inherited(sub_klass)
+      super
+      Singleton.__init__(sub_klass)
+    end
+  end
+
+  class << Singleton
+    def __init__(klass)
+      klass.instance_eval {
+        @singleton__instance__ = nil
+        @singleton__mutex__ = Mutex.new
+      }
+      def klass.instance
+        return @singleton__instance__ if @singleton__instance__
+        @singleton__mutex__.synchronize {
+          return @singleton__instance__ if @singleton__instance__
+          @singleton__instance__ = new()
+        }
+        @singleton__instance__
+      end
+      klass
+    end
+
+    private
+
+    #  extending an object with Singleton is a bad idea
+    undef_method :extend_object
+
+    def append_features(mod)
+      #  help out people counting on transitive mixins
+      unless mod.instance_of?(Class)
+        raise TypeError, "Inclusion of the OO-Singleton module in module #{mod}"
+      end
+      super
+    end
+
+    def included(klass)
+      super
+      klass.private_class_method  :new, :allocate
+      klass.extend SingletonClassMethods
+      Singleton.__init__(klass)
+    end
+  end
+
+end
+
+
+if __FILE__ == $0
+
+def num_of_instances(klass)
+    "#{ObjectSpace.each_object(klass){}} #{klass} instance(s)"
+end
+
+# The basic and most important example.
+
+class SomeSingletonClass
+  include Singleton
+end
+puts "There are #{num_of_instances(SomeSingletonClass)}"
+
+a = SomeSingletonClass.instance
+b = SomeSingletonClass.instance # a and b are same object
+puts "basic test is #{a == b}"
+
+begin
+  SomeSingletonClass.new
+rescue  NoMethodError => mes
+  puts mes
+end
+
+
+
+puts "\nThreaded example with exception and customized #_instantiate?() hook"; p
+Thread.abort_on_exception = false
+
+class Ups < SomeSingletonClass
+  def initialize
+    self.class.__sleep
+    puts "initialize called by thread ##{Thread.current[:i]}"
+  end
+end
+
+class << Ups
+  def _instantiate?
+    @enter.push Thread.current[:i]
+    while false.equal?(@singleton__instance__)
+      @singleton__mutex__.unlock
+      sleep 0.08
+      @singleton__mutex__.lock
+    end
+    @leave.push Thread.current[:i]
+    @singleton__instance__
+  end
+
+  def __sleep
+    sleep(rand(0.08))
+  end
+
+  def new
+    begin
+      __sleep
+      raise  "boom - thread ##{Thread.current[:i]} failed to create instance"
+    ensure
+      # simple flip-flop
+      class << self
+        remove_method :new
+      end
+    end
+  end
+
+  def instantiate_all
+    @enter = []
+    @leave = []
+    1.upto(9) {|i|
+      Thread.new {
+        begin
+          Thread.current[:i] = i
+          __sleep
+          instance
+        rescue RuntimeError => mes
+          puts mes
+        end
+      }
+    }
+    puts "Before there were #{num_of_instances(self)}"
+    sleep 3
+    puts "Now there is #{num_of_instances(self)}"
+    puts "#{@enter.join '; '} was the order of threads entering the waiting loop"
+    puts "#{@leave.join '; '} was the order of threads leaving the waiting loop"
+  end
+end
+
+
+Ups.instantiate_all
+# results in message like
+# Before there were 0 Ups instance(s)
+# boom - thread #6 failed to create instance
+# initialize called by thread #3
+# Now there is 1 Ups instance(s)
+# 3; 2; 1; 8; 4; 7; 5 was the order of threads entering the waiting loop
+# 3; 2; 1; 7; 4; 8; 5 was the order of threads leaving the waiting loop
+
+
+puts "\nLets see if class level cloning really works"
+Yup = Ups.clone
+def Yup.new
+  begin
+    __sleep
+    raise  "boom - thread ##{Thread.current[:i]} failed to create instance"
+  ensure
+    # simple flip-flop
+    class << self
+      remove_method :new
+    end
+  end
+end
+Yup.instantiate_all
+
+
+puts "\n\n","Customized marshalling"
+class A
+  include Singleton
+  attr_accessor :persist, :die
+  def _dump(depth)
+    # this strips the @die information from the instance
+    Marshal.dump(@persist,depth)
+  end
+end
+
+def A._load(str)
+  instance.persist = Marshal.load(str)
+  instance
+end
+
+a = A.instance
+a.persist = ["persist"]
+a.die = "die"
+a.taint
+
+stored_state = Marshal.dump(a)
+# change state
+a.persist = nil
+a.die = nil
+b = Marshal.load(stored_state)
+p a == b  #  => true
+p a.persist  #  => ["persist"]
+p a.die      #  => nil
+
+
+puts "\n\nSingleton with overridden default #inherited() hook"
+class Up
+end
+def Up.inherited(sub_klass)
+  puts "#{sub_klass} subclasses #{self}"
+end
+
+
+class Middle < Up
+  include Singleton
+end
+
+class Down < Middle; end
+
+puts  "and basic \"Down test\" is #{Down.instance == Down.instance}\n
+Various exceptions"
+
+begin
+  module AModule
+    include Singleton
+  end
+rescue TypeError => mes
+  puts mes  #=> Inclusion of the OO-Singleton module in module AModule
+end
+
+begin
+  'aString'.extend Singleton
+rescue NoMethodError => mes
+  puts mes  #=> undefined method `extend_object' for Singleton:Module
+end
+
+end

data/lib/rubysl/singleton/version.rb

@@ -0,0 +1,5 @@
+module RubySL
+  module Singleton
+    VERSION = "1.0.0"
+  end
+end

data/lib/singleton.rb

@@ -0,0 +1 @@
+require "rubysl/singleton"

data/rubysl-singleton.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+require './lib/rubysl/singleton/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "rubysl-singleton"
+  spec.version       = RubySL::Singleton::VERSION
+  spec.authors       = ["Brian Shirai"]
+  spec.email         = ["brixen@gmail.com"]
+  spec.description   = %q{Ruby standard library singleton.}
+  spec.summary       = %q{Ruby standard library singleton.}
+  spec.homepage      = "https://github.com/rubysl/rubysl-singleton"
+  spec.license       = "BSD"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "mspec", "~> 1.5"
+  spec.add_development_dependency "rubysl-prettyprint", "~> 1.0"
+end

data/spec/allocate_spec.rb

@@ -0,0 +1,7 @@
+require File.expand_path('../fixtures/classes', __FILE__)
+
+describe "Singleton.allocate" do
+  it "is a private method" do
+    lambda { SingletonSpecs::MyClass.allocate }.should raise_error(NoMethodError)
+  end
+end

data/spec/clone_spec.rb

@@ -0,0 +1,7 @@
+require File.expand_path('../fixtures/classes', __FILE__)
+
+describe "Singleton#clone" do
+  it "is prevented" do
+    lambda { SingletonSpecs::MyClass.instance.clone }.should raise_error(TypeError)
+  end
+end

data/spec/dump_spec.rb

@@ -0,0 +1,13 @@
+require File.expand_path('../fixtures/classes', __FILE__)
+
+describe "Singleton#_dump" do
+
+  it "returns an empty string" do
+    SingletonSpecs::MyClass.instance.send(:_dump).should == ""
+  end
+
+  it "returns an empty string from a singleton subclass" do
+    SingletonSpecs::MyClassChild.instance.send(:_dump).should == ""
+  end
+
+end

data/spec/dup_spec.rb

@@ -0,0 +1,7 @@
+require File.expand_path('../fixtures/classes', __FILE__)
+
+describe "Singleton#dup" do
+  it "is prevented" do
+    lambda { SingletonSpecs::MyClass.instance.dup }.should raise_error(TypeError)
+  end
+end

data/spec/fixtures/classes.rb

@@ -0,0 +1,18 @@
+require 'singleton'
+
+module SingletonSpecs
+  class MyClass
+    attr_accessor :data
+    include Singleton
+  end
+
+  class NewSpec
+    include Singleton
+  end
+
+  class MyClassChild < MyClass
+  end
+
+  class NotInstantiated < MyClass
+  end
+end

data/spec/instance_spec.rb

@@ -0,0 +1,29 @@
+require File.expand_path('../fixtures/classes', __FILE__)
+
+describe "Singleton.instance" do
+  it "returns an instance of the singleton class" do
+    SingletonSpecs::MyClass.instance.should be_kind_of(SingletonSpecs::MyClass)
+  end
+
+  it "returns the same instance for multiple calls to instance" do
+    SingletonSpecs::MyClass.instance.should equal(SingletonSpecs::MyClass.instance)
+  end
+
+  it "returns an instance of the singleton's subclasses" do
+    SingletonSpecs::MyClassChild.instance.should be_kind_of(SingletonSpecs::MyClassChild)
+  end
+
+  it "returns the same instance for multiple class to instance on subclasses" do
+    SingletonSpecs::MyClassChild.instance.should equal(SingletonSpecs::MyClassChild.instance)
+  end
+
+  it "returns an instance of the singleton's clone" do
+    klone = SingletonSpecs::MyClassChild.clone
+    klone.instance.should be_kind_of(klone)
+  end
+
+  it "returns the same instance for multiple class to instance on clones" do
+    klone = SingletonSpecs::MyClassChild.clone
+    klone.instance.should equal(klone.instance)
+  end
+end

data/spec/instantiate_spec.rb

@@ -0,0 +1,20 @@
+require File.expand_path('../fixtures/classes', __FILE__)
+
+describe "Singleton._instantiate?" do
+
+  it "is private" do
+    lambda { SingletonSpecs::MyClass._instantiate? }.should raise_error(NoMethodError)
+  end
+
+  ruby_version_is "" ... "1.9" do
+    # JRuby doesn't support "_instantiate?" intentionally (JRUBY-2239)
+    not_compliant_on :jruby do
+      it "returns nil until it is instantiated" do
+        SingletonSpecs::NotInstantiated.send(:_instantiate?).should == nil
+        SingletonSpecs::NotInstantiated.instance
+        inst = SingletonSpecs::NotInstantiated.send(:_instantiate?)
+        inst.should eql(SingletonSpecs::NotInstantiated.instance)
+      end
+    end
+  end
+end

data/spec/load_spec.rb

@@ -0,0 +1,22 @@
+require File.expand_path('../fixtures/classes', __FILE__)
+
+# TODO: change to a.should be_equal(b)
+# TODO: write spec for cloning classes and calling private methods
+# TODO: write spec for private_methods not showing up via extended
+describe "Singleton._load" do
+  ruby_version_is "1.8.7".."1.9" do
+    it "returns the singleton instance for anything passed in" do
+      klass = SingletonSpecs::MyClass
+      klass._load("").should equal(klass.instance)
+      klass._load("42").should equal(klass.instance)
+      klass._load(42).should equal(klass.instance)
+    end
+
+    it "returns the singleton instance for anything passed in to subclass" do
+      subklass = SingletonSpecs::MyClassChild
+      subklass._load("").should equal(subklass.instance)
+      subklass._load("42").should equal(subklass.instance)
+      subklass._load(42).should equal(subklass.instance)
+    end
+  end
+end

data/spec/new_spec.rb

@@ -0,0 +1,7 @@
+require File.expand_path('../fixtures/classes', __FILE__)
+
+describe "Singleton.new" do
+  it "is a private method" do
+    lambda { SingletonSpecs::NewSpec.new }.should raise_error(NoMethodError)
+  end
+end

metadata

@@ -0,0 +1,130 @@
+--- !ruby/object:Gem::Specification
+name: rubysl-singleton
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Brian Shirai
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-09-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: mspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rubysl-prettyprint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Ruby standard library singleton.
+email:
+- brixen@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .travis.yml
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/rubysl/singleton.rb
+- lib/rubysl/singleton/singleton.rb
+- lib/rubysl/singleton/version.rb
+- lib/singleton.rb
+- rubysl-singleton.gemspec
+- spec/allocate_spec.rb
+- spec/clone_spec.rb
+- spec/dump_spec.rb
+- spec/dup_spec.rb
+- spec/fixtures/classes.rb
+- spec/instance_spec.rb
+- spec/instantiate_spec.rb
+- spec/load_spec.rb
+- spec/new_spec.rb
+homepage: https://github.com/rubysl/rubysl-singleton
+licenses:
+- BSD
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: Ruby standard library singleton.
+test_files:
+- spec/allocate_spec.rb
+- spec/clone_spec.rb
+- spec/dump_spec.rb
+- spec/dup_spec.rb
+- spec/fixtures/classes.rb
+- spec/instance_spec.rb
+- spec/instantiate_spec.rb
+- spec/load_spec.rb
+- spec/new_spec.rb
+has_rdoc: