0001-enhanced-monitor-doc.patch

Sandor Szücs, 06/04/2011 06:36 AM

Download (4.93 KB)

View differences:

lib/monitor.rb
1
=begin
2

  
3
= monitor.rb
4

  
5
Copyright (C) 2001  Shugo Maeda <shugo@ruby-lang.org>
6

  
7
This library is distributed under the terms of the Ruby license.
8
You can freely distribute/modify this library.
9

  
10
== example
11

  
12
This is a simple example.
13

  
14
  require 'monitor.rb'
15

  
16
  buf = []
17
  buf.extend(MonitorMixin)
18
  empty_cond = buf.new_cond
19

  
20
  # consumer
21
  Thread.start do
22
    loop do
23
      buf.synchronize do
24
        empty_cond.wait_while { buf.empty? }
25
        print buf.shift
26
      end
27
    end
28
  end
29

  
30
  # producer
31
  while line = ARGF.gets
32
    buf.synchronize do
33
      buf.push(line)
34
      empty_cond.signal
35
    end
36
  end
37

  
38
The consumer thread waits for the producer thread to push a line
39
to buf while buf.empty?, and the producer thread (main thread)
40
reads a line from ARGF and push it to buf, then call
41
empty_cond.signal.
42

  
43
=end
1
# = monitor.rb
2
# 
3
# Copyright (C) 2001  Shugo Maeda <shugo@ruby-lang.org>
4
# 
5
# This library is distributed under the terms of the Ruby license.
6
# You can freely distribute/modify this library.
7
#
44 8

  
45 9
require 'thread'
46 10

  
47
#
48
# Adds monitor functionality to an arbitrary object by mixing the module with
49
# +include+.  For example:
50
#
51
#    require 'monitor'
52
#
53
#    buf = []
54
#    buf.extend(MonitorMixin)
55
#    empty_cond = buf.new_cond
56
#
57
#    # consumer
58
#    Thread.start do
59
#      loop do
60
#        buf.synchronize do
61
#          empty_cond.wait_while { buf.empty? }
62
#          print buf.shift
63
#        end
64
#      end
65
#    end
66
#
67
#    # producer
68
#    while line = ARGF.gets
69
#      buf.synchronize do
70
#        buf.push(line)
71
#        empty_cond.signal
72
#      end
73
#    end
74
#
11
# 
12
# In concurrent programming, a monitor is an object or module intended
13
# to be used safely by more than one thread. The defining
14
# characteristic of a monitor is that its methods are executed with
15
# mutual exclusion. That is, at each point in time, at most one thread
16
# may be executing any of its methods. This mutual exclusion greatly
17
# simplifies reasoning about the implementation of monitors compared
18
# to reasoning about parallel code that updates a data structure. Read
19
# more about the general principle at
20
# Wikimedia[https://secure.wikimedia.org/wikipedia/en/wiki/Monitor_%28synchronization%29].
21
# 
22
# == Examples
23
# 
24
# === Simple object.extend
25
# 
26
#   require 'monitor.rb'
27
# 
28
#   buf = []
29
#   buf.extend(MonitorMixin)
30
#   empty_cond = buf.new_cond
31
# 
32
#   # consumer
33
#   Thread.start do
34
#     loop do
35
#       buf.synchronize do
36
#         empty_cond.wait_while { buf.empty? }
37
#         print buf.shift
38
#       end
39
#     end
40
#   end
41
# 
42
#   # producer
43
#   while line = ARGF.gets
44
#     buf.synchronize do
45
#       buf.push(line)
46
#       empty_cond.signal
47
#     end
48
#   end
49
# 
75 50
# The consumer thread waits for the producer thread to push a line
76 51
# to buf while buf.empty?, and the producer thread (main thread)
77 52
# reads a line from ARGF and push it to buf, then call
78 53
# empty_cond.signal.
54
# 
55
# === Simple Class include
56
#
57
#   require 'monitor'
58
# 
59
#   class SynchronizedArray < Array
60
#
61
#     include MonitorMixin
62
#
63
#     def initialize(*args)
64
#       super(*args)
65
#     end
66
#     
67
#     alias :old_shift :shift
68
#     alias :old_unshift :unshift
69
#     
70
#     def shift(n=1)
71
#       self.synchronize do
72
#         self.old_shift(n)
73
#       end
74
#     end
75
#   
76
#     def unshift(item)
77
#       self.synchronize do
78
#         self.old_unshift(item)
79
#       end
80
#     end
81
#     
82
#     # other methods ...
83
#   end
84
#
85
# +SynchronizedArray+ implements an +Array+ with synchronized access
86
# to items. This +Class+ is implemented as subclass of +Array+ mixin
87
# the +MonitorMixin+ module. 
79 88
#
80 89
module MonitorMixin
81 90
  #
......
215 224

  
216 225
  private
217 226

  
227
  # Use <tt>Object#extend(MonitorMixin)</tt> or
228
  # <tt>Object#include</tt> instead of this constructor. Have look at
229
  # the examples above to understand how to use this module.
218 230
  def initialize(*args)
219 231
    super
220 232
    mon_initialize
221 233
  end
222 234

  
235
  # Initialize the <tt>MonitorMixin</tt> within an <tt>Object</tt>.
223 236
  def mon_initialize
224 237
    @mon_owner = nil
225 238
    @mon_count = 0
......
245 258
  end
246 259
end
247 260

  
261
# Create a +Monitor+ class if you want to have a lock object for
262
# blocks with mutual exclusion. 
263
#
264
#   require 'monitor'
265
#
266
#   lock = Monitor.new
267
#   lock.synchronize do
268
#     # exclusive access
269
#   end
270
#
248 271
class Monitor
249 272
  include MonitorMixin
250 273
  alias try_enter try_mon_enter
251
-