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”.