/usr/lib/ruby/2.5.0/singleton.rb is in libruby2.5 2.5.1-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 | # frozen_string_literal: false
# The Singleton module implements the Singleton pattern.
#
# == Usage
#
# To use Singleton, include the module in your class.
#
# class Klass
# include Singleton
# # ...
# end
#
# This ensures that only one instance of Klass can be created.
#
# a,b = Klass.instance, Klass.instance
#
# a == b
# # => true
#
# Klass.new
# # => NoMethodError - new is private ...
#
# The instance is created at upon the first call of Klass.instance().
#
# class OtherKlass
# include Singleton
# # ...
# end
#
# ObjectSpace.each_object(OtherKlass){}
# # => 0
#
# OtherKlass.instance
# ObjectSpace.each_object(OtherKlass){}
# # => 1
#
#
# This behavior is preserved under inheritance and cloning.
#
# == Implementation
#
# 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)
# end
#
# def self._load(str)
# instance.keep = Marshal.load(str)
# instance
# end
# end
#
# a = Example.instance
# a.keep = "keep this"
# a.strip = "get rid of this"
# a.taint
#
# 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
#
module Singleton
# Raises a TypeError to prevent cloning.
def clone
raise TypeError, "can't clone instance of singleton #{self.class}"
end
# Raises a TypeError to prevent duping.
def dup
raise TypeError, "can't dup instance of singleton #{self.class}"
end
# By default, do not retain any state when marshalling.
def _dump(depth = -1)
''
end
module SingletonClassMethods # :nodoc:
def clone # :nodoc:
Singleton.__init__(super)
end
# By default calls instance(). Override to retain singleton state.
def _load(str)
instance
end
private
def inherited(sub_klass)
super
Singleton.__init__(sub_klass)
end
end
class << Singleton # :nodoc:
def __init__(klass) # :nodoc:
klass.instance_eval {
@singleton__instance__ = nil
@singleton__mutex__ = Thread::Mutex.new
}
def klass.instance # :nodoc:
return @singleton__instance__ if @singleton__instance__
@singleton__mutex__.synchronize {
return @singleton__instance__ if @singleton__instance__
@singleton__instance__ = new()
}
@singleton__instance__
end
klass
end
private
# extending an object with Singleton is a bad idea
undef_method :extend_object
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
end
def included(klass)
super
klass.private_class_method :new, :allocate
klass.extend SingletonClassMethods
Singleton.__init__(klass)
end
end
##
# :singleton-method: _load
# By default calls instance(). Override to retain singleton state.
end
|