# 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 # a.new # NoMethodError - new is private ... # # * ``The instance'' is created at instanciation 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 # * removing #clone and #dup and modifying # * Klass.inherited(sub_klass) and Klass.clone() - # to ensure that the Singleton pattern is properly # inherited and cloned. # # In addition Klass is providing the additional class methods # * Klass.instance() - returning ``the instance''. After a successful # self modifying instanciating first call the method body is a simple # def Klass.instance() # return @__instance__ # end # * Klass._load(str) - calls instance() # * Klass._instanciate?() - 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 instanciating thread. # # The sole instance method of Singleton is # * _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''. module Singleton private # default marshalling strategy def _dump(depth=-1) '' end class << self # extending an object with Singleton is a bad idea undef_method :extend_object private def append_features(mod) # This catches ill advisted inclusions of Singleton in # singletons types (sounds like an oxymoron) and # helps out people counting on transitive mixins unless mod.instance_of?(Class) raise TypeError, "Inclusion of the OO-Singleton module in module #{mod}" end unless (class << mod; self end) <= (class << Object; self end) raise TypeError, "Inclusion of the OO-Singleton module in singleton type" end super end def included(klass) # remove build in copying methods klass.class_eval do define_method(:clone) {raise TypeError, "can't clone singleton #{self.class}"} end # initialize the ``klass instance variable'' @__instance__ to nil klass.instance_eval do @__instance__ = nil end class << klass # a main point of the whole exercise - make # new and allocate private private :new, :allocate # declare the self modifying klass#instance method define_method(:instance, Singleton::FirstInstanceCall) # simple waiting loop hook - should do in most cases # note the pre/post-conditions of a thread-critical state private def _instanciate?() while false.equal?(@__instance__) Thread.critical = false sleep(0.08) Thread.critical = true end @__instance__ end # default Marshalling strategy def _load(str) instance end # ensure that the Singleton pattern is properly inherited def inherited(sub_klass) super sub_klass.instance_eval do @__instance__ = nil end class << sub_klass define_method(:instance, Singleton::FirstInstanceCall) end end public # properly clone the Singleton pattern. Question - Did # you know that duping doesn't copy class methods? def clone res = super res.instance_eval do @__instance__ = nil end class << res define_method(:instance, Singleton::FirstInstanceCall) end res end end # of << klass end # of included end # of << Singleton FirstInstanceCall = proc do # @__instance__ takes on one of the following values # * nil - before and after a failed creation # * false - during creation # * sub_class instance - after a successful creation # the form makes up for the lack of returns in progs Thread.critical = true if @__instance__.nil? @__instance__ = false Thread.critical = false begin @__instance__ = new ensure if @__instance__ define_method(:instance) {@__instance__} else @__instance__ = nil # failed instance creation end end elsif _instanciate?() Thread.critical = false else @__instance__ = false Thread.critical = false begin @__instance__ = new ensure if @__instance__ define_method(:instance) {@__instance__} else @__instance__ = nil end end end @__instance__ end end if __FILE__ == $0 def num_of_instances(klass) "#{ObjectSpace.each_object(klass){}} #{klass} instance(s)" end # The basic and most important example. The latter examples demonstrate # advanced features that have no relevance for the general usage 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 #_instanciate?() hook"; p Thread.abort_on_exception = false class Ups < SomeSingletonClass def initialize self.class.__sleep puts "initialize called by thread ##{Thread.current[:i]}" end class << self def _instanciate? @enter.push Thread.current[:i] while false.equal?(@__instance__) Thread.critical = false sleep 0.04 Thread.critical = true end @leave.push Thread.current[:i] @__instance__ end def __sleep sleep(rand(0.08)) end def allocate __sleep def self.allocate; __sleep; super() end raise "boom - allocation in thread ##{Thread.current[:i]} aborted" end def instanciate_all @enter = [] @leave = [] 1.upto(9) do |i| Thread.new do begin Thread.current[:i] = i __sleep instance rescue RuntimeError => mes puts mes end end end puts "Before there were #{num_of_instances(self)}" sleep 5 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 end Ups.instanciate_all # results in message like # Before there were 0 Ups instances # boom - allocation in thread #8 aborted # initialize called by thread #3 # Now there is 1 Ups instance # 2; 3; 6; 1; 7; 5; 9; 4 was the order of threads entering the waiting loop # 3; 2; 1; 7; 6; 5; 4; 9 was the order of threads leaving the waiting loop puts "\nLets see if class level cloning really works" Yup = Ups.clone def Yup.allocate __sleep def self.allocate; __sleep; super() end raise "boom - allocation in thread ##{Thread.current[:i]} aborted" end Yup.instanciate_all puts "\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 def Up.inherited(sub_klass) puts "#{sub_klass} subclasses #{self}" end end class Middle < Up undef_method :dup include Singleton end class Down < Middle; end puts "basic test is #{Down.instance == Down.instance}" puts "\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 class << 'aString' include Singleton end rescue TypeError => mes puts mes # => Inclusion of the OO-Singleton module in singleton type end begin 'aString'.extend Singleton rescue NoMethodError => mes puts mes #=> undefined method `extend_object' for Singleton:Module end end