The Singleton module implements the Singleton pattern.


To use Singleton, include the module in your class.

class Klass
   include Singleton
   # ...

This ensures that only one instance of Klass can be created.

a,b = Klass.instance, Klass.instance

a == b
# => true
# => NoMethodError - new is private ...

The instance is created at upon the first call of Klass.instance().

class OtherKlass
  include Singleton
  # ...

# => 0

# => 1

This behavior is preserved under inheritance and cloning.


This above is achieved by:

  • Making and Klass.allocate private.

  • Overriding Klass.inherited(sub_klass) and Klass.clone() to ensure that the Singleton properties are kept when inherited and cloned.

  • Providing the Klass.instance() method that returns the same object each time it is called.

  • Overriding Klass._load(str) to call Klass.instance().

  • Overriding Klass#clone and Klass#dup to raise TypeErrors to prevent cloning or duping.

Singleton and Marshal

By default Singleton’s #_dump(depth) returns the empty string. Marshalling by default will strip state information, e.g. instance variables from the instance. Classes using Singleton can provide custom _load(str) and _dump(depth) methods to retain some of the previous state of the instance.

require 'singleton'

class Example
  include Singleton
  attr_accessor :keep, :strip
  def _dump(depth)
    # this strips the @strip information from the instance
    Marshal.dump(@keep, depth)

  def self._load(str)
    instance.keep = Marshal.load(str)

a = Example.instance
a.keep = "keep this"
a.strip = "get rid of this"

stored_state = Marshal.dump(a)

a.keep = nil
a.strip = nil
b = Marshal.load(stored_state)
p a == b  #  => true
p a.keep  #  => "keep this"
p a.strip #  => nil
No documentation available
Class Methods

By default calls instance(). Override to retain singleton state.

No documentation available
No documentation available

Returns the singleton instance.

Instance Methods

By default, do not retain any state when marshalling.

Raises a TypeError to prevent cloning.

Raises a TypeError to prevent duping.