summaryrefslogtreecommitdiff
path: root/lib/singleton.rb
blob: 0ab8517275b426663272707d46fe5c23f6234416 (plain)
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
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
# 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''.



module Singleton
  #  disable build-in copying methods
  def clone
    raise TypeError, "can't clone instance of singleton #{self.class}"
  end
  def dup
    raise TypeError, "can't dup instance of singleton #{self.class}"
  end
  
  private 
  #  default marshalling strategy
  def _dump(depth=-1) 
    ''
  end
end


class << Singleton
  #  Method body of first instance call.
  FirstInstanceCall = proc do
    #  @__instance__ takes on one of the following values
    #  * nil     -  before and after a failed creation
    #  * false  -  during creation
    #  * sub_class instance  -  after a successful creation
    #  the form makes up for the lack of returns in progs
    Thread.critical = true
    if  @__instance__.nil?
      @__instance__  = false
      Thread.critical = false
      begin
        @__instance__ = new
      ensure
        if @__instance__
          class <<self
            remove_method :instance
            def instance; @__instance__ end
          end
        else
          @__instance__ = nil #  failed instance creation
        end
      end
    elsif  _instantiate?()
      Thread.critical = false    
    else
      @__instance__  = false
      Thread.critical = false
      begin
        @__instance__ = new
      ensure
        if @__instance__
          class <<self
            remove_method :instance
            def instance; @__instance__ end
          end
        else
          @__instance__ = nil
        end
      end
    end
    @__instance__
  end
  
  module SingletonClassMethods  
    # properly clone the Singleton pattern - did you know
    # that duping doesn't copy class methods?  
    def clone
      Singleton.__init__(super)
    end
    
    private
    
    #  ensure that the Singleton pattern is properly inherited   
    def inherited(sub_klass)
      super
      Singleton.__init__(sub_klass)
    end
    
    def _load(str) 
      instance 
    end
    
    # waiting-loop hook
    def _instantiate?()
      while false.equal?(@__instance__)
        Thread.critical = false
        sleep(0.08)   # timeout
        Thread.critical = true
      end
      @__instance__
    end
  end
  
  def __init__(klass)
    klass.instance_eval { @__instance__ = nil }
    class << klass
      define_method(:instance,FirstInstanceCall)
    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
 


if __FILE__ == $0

def num_of_instances(klass)
    "#{ObjectSpace.each_object(klass){}} #{klass} instance(s)"
end 

# The basic and most important example.

class SomeSingletonClass
  include Singleton
end
puts "There are #{num_of_instances(SomeSingletonClass)}" 

a = SomeSingletonClass.instance
b = SomeSingletonClass.instance # a and b are same object
puts "basic test is #{a == b}"

begin
  SomeSingletonClass.new
rescue  NoMethodError => mes
  puts mes
end



puts "\nThreaded example with exception and customized #_instantiate?() hook"; p
Thread.abort_on_exception = false

class Ups < SomeSingletonClass
  def initialize
    self.class.__sleep
    puts "initialize called by thread ##{Thread.current[:i]}"
  end
end
  
class << Ups
  def _instantiate?
    @enter.push Thread.current[:i]
    while false.equal?(@__instance__)
      Thread.critical = false
      sleep 0.08 
      Thread.critical = true
    end
    @leave.push Thread.current[:i]
    @__instance__
  end
  
  def __sleep
    sleep(rand(0.08))
  end
  
  def new
    begin
      __sleep
      raise  "boom - thread ##{Thread.current[:i]} failed to create instance"
    ensure
      # simple flip-flop
      class << self
        remove_method :new
      end
    end
  end
  
  def instantiate_all
    @enter = []
    @leave = []
    1.upto(9) {|i|  
      Thread.new { 
        begin
          Thread.current[:i] = i
          __sleep
          instance
        rescue RuntimeError => mes
          puts mes
        end
      }
    }
    puts "Before there were #{num_of_instances(self)}"
    sleep 3
    puts "Now there is #{num_of_instances(self)}"
    puts "#{@enter.join '; '} was the order of threads entering the waiting loop"
    puts "#{@leave.join '; '} was the order of threads leaving the waiting loop"
  end
end


Ups.instantiate_all
# results in message like
# Before there were 0 Ups instance(s)
# boom - thread #6 failed to create instance
# initialize called by thread #3
# Now there is 1 Ups instance(s)
# 3; 2; 1; 8; 4; 7; 5 was the order of threads entering the waiting loop
# 3; 2; 1; 7; 4; 8; 5 was the order of threads leaving the waiting loop


puts "\nLets see if class level cloning really works"
Yup = Ups.clone
def Yup.new
  begin
    __sleep
    raise  "boom - thread ##{Thread.current[:i]} failed to create instance"
  ensure
    # simple flip-flop
    class << self
      remove_method :new
    end
  end
end
Yup.instantiate_all


puts "\n\n","Customized marshalling"
class A
  include Singleton
  attr_accessor :persist, :die
  def _dump(depth)
    # this strips the @die information from the instance
    Marshal.dump(@persist,depth)
  end
end

def A._load(str)
  instance.persist = Marshal.load(str)
  instance
end

a = A.instance
a.persist = ["persist"]
a.die = "die"
a.taint

stored_state = Marshal.dump(a)
# change state
a.persist = nil
a.die = nil
b = Marshal.load(stored_state)
p a == b  #  => true
p a.persist  #  => ["persist"]
p a.die      #  => nil


puts "\n\nSingleton with overridden default #inherited() hook"
class Up
end
def Up.inherited(sub_klass)
  puts "#{sub_klass} subclasses #{self}"
end


class Middle < Up
  include Singleton
end

class Down < Middle; end

puts  "and basic \"Down test\" is #{Down.instance == Down.instance}\n
Various exceptions"  

begin
  module AModule
    include Singleton
  end
rescue TypeError => mes
  puts mes  #=> Inclusion of the OO-Singleton module in module AModule
end

begin
  'aString'.extend Singleton
rescue NoMethodError => mes
  puts mes  #=> undefined method `extend_object' for Singleton:Module
end

end