Extended maintenance of Ruby 1.9.3 ended on February 23, 2015. Read more

In Files

  • singleton.rb

Class/Module Index [+]



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 Klass.new 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 and taint state, 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

Public Class Methods

_load click to toggle source

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

               # File singleton.rb, line 172


Public Instance Methods

_dump(depth = -1) click to toggle source

By default, do not retain any state when marshalling.

               # File singleton.rb, line 108
def _dump(depth = -1)
clone() click to toggle source

Raises a TypeError to prevent cloning.

               # File singleton.rb, line 98
def clone
  raise TypeError, "can't clone instance of singleton #{self.class}"
dup() click to toggle source

Raises a TypeError to prevent duping.

               # File singleton.rb, line 103
def dup
  raise TypeError, "can't dup instance of singleton #{self.class}"

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.