2002-01-29 10:16:09 +03:00
|
|
|
# The Singleton module implements the Singleton pattern.
|
2001-11-27 13:00:35 +03:00
|
|
|
#
|
2002-01-29 10:16:09 +03:00
|
|
|
# Usage:
|
|
|
|
# class Klass
|
|
|
|
# include Singleton
|
|
|
|
# # ...
|
|
|
|
# end
|
2001-11-27 13:00:35 +03:00
|
|
|
#
|
2002-01-29 10:16:09 +03:00
|
|
|
# * this ensures that only one instance of Klass lets call it
|
|
|
|
# ``the instance'' can be created.
|
2001-11-27 13:00:35 +03:00
|
|
|
#
|
2009-01-01 01:43:41 +03:00
|
|
|
# a,b = Klass.instance, Klass.instance
|
|
|
|
# a == b # => true
|
|
|
|
# a.new # NoMethodError - new is private ...
|
2001-11-27 13:00:35 +03:00
|
|
|
#
|
2004-03-29 11:54:38 +04:00
|
|
|
# * ``The instance'' is created at instantiation time, in other
|
2003-08-02 22:05:02 +04:00
|
|
|
# words the first call of Klass.instance(), thus
|
2001-11-27 13:00:35 +03:00
|
|
|
#
|
2005-03-15 17:52:59 +03:00
|
|
|
# class OtherKlass
|
2001-11-27 13:00:35 +03:00
|
|
|
# include Singleton
|
|
|
|
# # ...
|
2005-03-15 17:52:59 +03:00
|
|
|
# end
|
|
|
|
# ObjectSpace.each_object(OtherKlass){} # => 0.
|
2001-11-27 13:00:35 +03:00
|
|
|
#
|
2002-01-29 10:16:09 +03:00
|
|
|
# * This behavior is preserved under inheritance and cloning.
|
2001-11-27 13:00:35 +03:00
|
|
|
#
|
|
|
|
#
|
2003-08-02 22:05:02 +04:00
|
|
|
#
|
2002-01-29 10:16:09 +03:00
|
|
|
# This is achieved by marking
|
|
|
|
# * Klass.new and Klass.allocate - as private
|
2003-08-02 22:05:02 +04:00
|
|
|
#
|
|
|
|
# Providing (or modifying) the class methods
|
2008-05-28 10:18:18 +04:00
|
|
|
# * Klass.inherited(sub_klass) and Klass.clone() -
|
2002-01-29 10:16:09 +03:00
|
|
|
# to ensure that the Singleton pattern is properly
|
|
|
|
# inherited and cloned.
|
2001-11-27 13:00:35 +03:00
|
|
|
#
|
2003-08-02 22:05:02 +04:00
|
|
|
# * Klass.instance() - returning ``the instance''. After a
|
|
|
|
# successful self modifying (normally the first) call the
|
|
|
|
# method body is a simple:
|
|
|
|
#
|
|
|
|
# def Klass.instance()
|
2007-02-14 19:50:16 +03:00
|
|
|
# return @singleton__instance__
|
2003-08-02 22:05:02 +04:00
|
|
|
# end
|
|
|
|
#
|
|
|
|
# * Klass._load(str) - calling Klass.instance()
|
|
|
|
#
|
2004-03-29 11:54:38 +04:00
|
|
|
# * Klass._instantiate?() - returning ``the instance'' or
|
2003-08-02 22:05:02 +04:00
|
|
|
# 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
|
2004-03-29 11:54:38 +04:00
|
|
|
# of the first, or more generally, current "instantiation thread".
|
2003-08-02 22:05:02 +04:00
|
|
|
#
|
|
|
|
#
|
|
|
|
# The instance method of Singleton are
|
|
|
|
# * clone and dup - raising TypeErrors to prevent cloning or duping
|
2001-11-27 13:00:35 +03:00
|
|
|
#
|
2002-01-29 10:16:09 +03:00
|
|
|
# * _dump(depth) - returning the empty string. Marshalling strips
|
2003-08-02 22:05:02 +04:00
|
|
|
# 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''.
|
|
|
|
|
2006-12-31 18:02:22 +03:00
|
|
|
require 'thread'
|
2002-01-28 11:44:45 +03:00
|
|
|
|
1999-08-13 09:45:20 +04:00
|
|
|
module Singleton
|
2003-08-02 22:05:02 +04:00
|
|
|
# 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
|
2008-05-28 10:18:18 +04:00
|
|
|
|
2003-08-02 22:05:02 +04:00
|
|
|
# default marshalling strategy
|
2008-05-28 10:18:18 +04:00
|
|
|
def _dump(depth = -1)
|
2003-08-02 22:05:02 +04:00
|
|
|
''
|
|
|
|
end
|
|
|
|
|
2008-05-28 10:18:18 +04:00
|
|
|
module SingletonClassMethods
|
2003-08-02 22:05:02 +04:00
|
|
|
# properly clone the Singleton pattern - did you know
|
2008-05-28 10:18:18 +04:00
|
|
|
# that duping doesn't copy class methods?
|
2003-08-02 22:05:02 +04:00
|
|
|
def clone
|
|
|
|
Singleton.__init__(super)
|
|
|
|
end
|
2006-12-31 18:02:22 +03:00
|
|
|
|
2008-05-28 10:18:18 +04:00
|
|
|
def _load(str)
|
|
|
|
instance
|
|
|
|
end
|
|
|
|
|
2003-08-02 22:05:02 +04:00
|
|
|
private
|
2008-05-28 10:18:18 +04:00
|
|
|
|
|
|
|
# ensure that the Singleton pattern is properly inherited
|
2003-08-02 22:05:02 +04:00
|
|
|
def inherited(sub_klass)
|
|
|
|
super
|
|
|
|
Singleton.__init__(sub_klass)
|
|
|
|
end
|
2006-12-31 18:02:22 +03:00
|
|
|
end
|
|
|
|
|
|
|
|
class << Singleton
|
|
|
|
def __init__(klass)
|
|
|
|
klass.instance_eval {
|
2007-02-14 19:50:16 +03:00
|
|
|
@singleton__instance__ = nil
|
|
|
|
@singleton__mutex__ = Mutex.new
|
2006-12-31 18:02:22 +03:00
|
|
|
}
|
|
|
|
def klass.instance
|
2007-02-14 19:50:16 +03:00
|
|
|
return @singleton__instance__ if @singleton__instance__
|
|
|
|
@singleton__mutex__.synchronize {
|
|
|
|
return @singleton__instance__ if @singleton__instance__
|
|
|
|
@singleton__instance__ = new()
|
2006-12-31 18:02:22 +03:00
|
|
|
}
|
2007-02-14 19:50:16 +03:00
|
|
|
@singleton__instance__
|
2003-08-02 22:05:02 +04:00
|
|
|
end
|
2006-12-31 18:02:22 +03:00
|
|
|
klass
|
2001-11-27 13:00:35 +03:00
|
|
|
end
|
2008-05-28 10:18:18 +04:00
|
|
|
|
2006-12-31 18:02:22 +03:00
|
|
|
private
|
|
|
|
|
|
|
|
# extending an object with Singleton is a bad idea
|
|
|
|
undef_method :extend_object
|
2008-05-28 10:18:18 +04:00
|
|
|
|
2006-12-31 18:02:22 +03:00
|
|
|
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
|
2003-08-02 22:05:02 +04:00
|
|
|
end
|
2008-05-28 10:18:18 +04:00
|
|
|
|
2006-12-31 18:02:22 +03:00
|
|
|
def included(klass)
|
|
|
|
super
|
|
|
|
klass.private_class_method :new, :allocate
|
|
|
|
klass.extend SingletonClassMethods
|
|
|
|
Singleton.__init__(klass)
|
2003-08-02 22:05:02 +04:00
|
|
|
end
|
|
|
|
end
|
2008-05-28 10:18:18 +04:00
|
|
|
|
1999-08-13 09:45:20 +04:00
|
|
|
end
|
2002-01-29 10:16:09 +03:00
|
|
|
|
|
|
|
|
1999-08-13 09:45:20 +04:00
|
|
|
if __FILE__ == $0
|
2001-11-27 13:00:35 +03:00
|
|
|
|
2002-01-29 10:16:09 +03:00
|
|
|
def num_of_instances(klass)
|
|
|
|
"#{ObjectSpace.each_object(klass){}} #{klass} instance(s)"
|
2008-05-28 10:18:18 +04:00
|
|
|
end
|
2002-01-29 10:16:09 +03:00
|
|
|
|
2003-08-02 22:05:02 +04:00
|
|
|
# The basic and most important example.
|
2002-01-29 10:16:09 +03:00
|
|
|
|
2001-11-27 13:00:35 +03:00
|
|
|
class SomeSingletonClass
|
2003-08-02 22:05:02 +04:00
|
|
|
include Singleton
|
2001-11-27 13:00:35 +03:00
|
|
|
end
|
2008-05-28 10:18:18 +04:00
|
|
|
puts "There are #{num_of_instances(SomeSingletonClass)}"
|
2002-01-29 10:16:09 +03:00
|
|
|
|
2001-11-27 13:00:35 +03:00
|
|
|
a = SomeSingletonClass.instance
|
|
|
|
b = SomeSingletonClass.instance # a and b are same object
|
2002-01-29 10:16:09 +03:00
|
|
|
puts "basic test is #{a == b}"
|
|
|
|
|
2001-11-27 13:00:35 +03:00
|
|
|
begin
|
2003-08-02 22:05:02 +04:00
|
|
|
SomeSingletonClass.new
|
2001-11-27 13:00:35 +03:00
|
|
|
rescue NoMethodError => mes
|
2003-08-02 22:05:02 +04:00
|
|
|
puts mes
|
2001-11-27 13:00:35 +03:00
|
|
|
end
|
|
|
|
|
2002-01-29 10:16:09 +03:00
|
|
|
|
|
|
|
|
2004-03-29 11:54:38 +04:00
|
|
|
puts "\nThreaded example with exception and customized #_instantiate?() hook"; p
|
2001-11-28 17:56:32 +03:00
|
|
|
Thread.abort_on_exception = false
|
2001-11-27 13:00:35 +03:00
|
|
|
|
2001-11-28 17:56:32 +03:00
|
|
|
class Ups < SomeSingletonClass
|
2003-08-02 22:05:02 +04:00
|
|
|
def initialize
|
|
|
|
self.class.__sleep
|
|
|
|
puts "initialize called by thread ##{Thread.current[:i]}"
|
|
|
|
end
|
|
|
|
end
|
2008-05-28 10:18:18 +04:00
|
|
|
|
2003-08-02 22:05:02 +04:00
|
|
|
class << Ups
|
2004-03-29 11:54:38 +04:00
|
|
|
def _instantiate?
|
2003-08-02 22:05:02 +04:00
|
|
|
@enter.push Thread.current[:i]
|
2007-02-14 19:50:16 +03:00
|
|
|
while false.equal?(@singleton__instance__)
|
|
|
|
@singleton__mutex__.unlock
|
2008-05-28 10:18:18 +04:00
|
|
|
sleep 0.08
|
2007-02-14 19:50:16 +03:00
|
|
|
@singleton__mutex__.lock
|
2001-11-27 13:00:35 +03:00
|
|
|
end
|
2003-08-02 22:05:02 +04:00
|
|
|
@leave.push Thread.current[:i]
|
2007-02-14 19:50:16 +03:00
|
|
|
@singleton__instance__
|
2003-08-02 22:05:02 +04:00
|
|
|
end
|
2008-05-28 10:18:18 +04:00
|
|
|
|
2003-08-02 22:05:02 +04:00
|
|
|
def __sleep
|
|
|
|
sleep(rand(0.08))
|
|
|
|
end
|
2008-05-28 10:18:18 +04:00
|
|
|
|
2003-08-02 22:05:02 +04:00
|
|
|
def new
|
|
|
|
begin
|
|
|
|
__sleep
|
|
|
|
raise "boom - thread ##{Thread.current[:i]} failed to create instance"
|
|
|
|
ensure
|
|
|
|
# simple flip-flop
|
|
|
|
class << self
|
|
|
|
remove_method :new
|
|
|
|
end
|
2001-11-27 13:00:35 +03:00
|
|
|
end
|
2003-08-02 22:05:02 +04:00
|
|
|
end
|
2008-05-28 10:18:18 +04:00
|
|
|
|
2004-03-29 11:54:38 +04:00
|
|
|
def instantiate_all
|
2003-08-02 22:05:02 +04:00
|
|
|
@enter = []
|
|
|
|
@leave = []
|
2008-05-28 10:18:18 +04:00
|
|
|
1.upto(9) {|i|
|
|
|
|
Thread.new {
|
2003-08-02 22:05:02 +04:00
|
|
|
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
|
2001-11-27 13:00:35 +03:00
|
|
|
end
|
|
|
|
|
2003-08-02 22:05:02 +04:00
|
|
|
|
2004-03-29 11:54:38 +04:00
|
|
|
Ups.instantiate_all
|
2003-08-02 22:05:02 +04:00
|
|
|
# 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
|
|
|
|
|
2001-11-28 17:56:32 +03:00
|
|
|
|
2002-01-29 10:16:09 +03:00
|
|
|
puts "\nLets see if class level cloning really works"
|
|
|
|
Yup = Ups.clone
|
2003-08-02 22:05:02 +04:00
|
|
|
def Yup.new
|
|
|
|
begin
|
2002-01-29 10:16:09 +03:00
|
|
|
__sleep
|
2003-08-02 22:05:02 +04:00
|
|
|
raise "boom - thread ##{Thread.current[:i]} failed to create instance"
|
|
|
|
ensure
|
|
|
|
# simple flip-flop
|
|
|
|
class << self
|
|
|
|
remove_method :new
|
|
|
|
end
|
|
|
|
end
|
2002-01-29 10:16:09 +03:00
|
|
|
end
|
2004-03-29 11:54:38 +04:00
|
|
|
Yup.instantiate_all
|
2002-01-29 10:16:09 +03:00
|
|
|
|
2001-11-27 13:00:35 +03:00
|
|
|
|
2003-08-02 22:05:02 +04:00
|
|
|
puts "\n\n","Customized marshalling"
|
2001-11-27 13:00:35 +03:00
|
|
|
class A
|
2003-08-02 22:05:02 +04:00
|
|
|
include Singleton
|
|
|
|
attr_accessor :persist, :die
|
|
|
|
def _dump(depth)
|
|
|
|
# this strips the @die information from the instance
|
|
|
|
Marshal.dump(@persist,depth)
|
|
|
|
end
|
2001-11-27 13:00:35 +03:00
|
|
|
end
|
2003-08-02 22:05:02 +04:00
|
|
|
|
2001-11-27 13:00:35 +03:00
|
|
|
def A._load(str)
|
2003-08-02 22:05:02 +04:00
|
|
|
instance.persist = Marshal.load(str)
|
|
|
|
instance
|
2001-11-27 13:00:35 +03:00
|
|
|
end
|
|
|
|
|
|
|
|
a = A.instance
|
|
|
|
a.persist = ["persist"]
|
|
|
|
a.die = "die"
|
2002-01-29 10:16:09 +03:00
|
|
|
a.taint
|
2001-11-27 13:00:35 +03:00
|
|
|
|
|
|
|
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"]
|
2002-01-29 10:16:09 +03:00
|
|
|
p a.die # => nil
|
|
|
|
|
2003-08-02 22:05:02 +04:00
|
|
|
|
2002-01-29 10:16:09 +03:00
|
|
|
puts "\n\nSingleton with overridden default #inherited() hook"
|
|
|
|
class Up
|
2003-08-02 22:05:02 +04:00
|
|
|
end
|
|
|
|
def Up.inherited(sub_klass)
|
|
|
|
puts "#{sub_klass} subclasses #{self}"
|
2002-01-29 10:16:09 +03:00
|
|
|
end
|
|
|
|
|
|
|
|
|
|
|
|
class Middle < Up
|
2003-08-02 22:05:02 +04:00
|
|
|
include Singleton
|
2002-01-29 10:16:09 +03:00
|
|
|
end
|
|
|
|
|
2003-08-02 22:05:02 +04:00
|
|
|
class Down < Middle; end
|
2002-01-29 10:16:09 +03:00
|
|
|
|
2003-08-02 22:05:02 +04:00
|
|
|
puts "and basic \"Down test\" is #{Down.instance == Down.instance}\n
|
2008-05-28 10:18:18 +04:00
|
|
|
Various exceptions"
|
2002-01-29 10:16:09 +03:00
|
|
|
|
|
|
|
begin
|
2003-08-02 22:05:02 +04:00
|
|
|
module AModule
|
|
|
|
include Singleton
|
|
|
|
end
|
2002-01-29 10:16:09 +03:00
|
|
|
rescue TypeError => mes
|
2003-08-02 22:05:02 +04:00
|
|
|
puts mes #=> Inclusion of the OO-Singleton module in module AModule
|
2002-01-29 10:16:09 +03:00
|
|
|
end
|
|
|
|
|
|
|
|
begin
|
2003-08-02 22:05:02 +04:00
|
|
|
'aString'.extend Singleton
|
2002-01-29 10:16:09 +03:00
|
|
|
rescue NoMethodError => mes
|
2003-08-02 22:05:02 +04:00
|
|
|
puts mes #=> undefined method `extend_object' for Singleton:Module
|
2002-01-29 10:16:09 +03:00
|
|
|
end
|
1999-08-13 09:45:20 +04:00
|
|
|
|
|
|
|
end
|