singleton.rb

Path: lib/singleton.rb
Last Update: Thu Jul 11 05:43:10 +0000 2013

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 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 @__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’’.

Methods

Public Instance methods

[Source]

     # File lib/singleton.rb, line 156
156:   def __init__(klass)
157:     klass.instance_eval { @__instance__ = nil }
158:     class << klass
159:       define_method(:instance,FirstInstanceCall)
160:     end
161:     klass
162:   end

Private Instance methods

[Source]

     # File lib/singleton.rb, line 168
168:   def append_features(mod)
169:     #  help out people counting on transitive mixins
170:     unless mod.instance_of?(Class)
171:       raise TypeError, "Inclusion of the OO-Singleton module in module #{mod}"
172:     end
173:     super
174:   end

[Source]

     # File lib/singleton.rb, line 176
176:   def included(klass)
177:     super
178:     klass.private_class_method  :new, :allocate
179:     klass.extend SingletonClassMethods
180:     Singleton.__init__(klass)
181:   end

[Validate]