ruby-core

Mutexes and so-on were being discussed and while poking around in  
thread.rb, I noticed a few FIXMEs in the documentation, so I fixed them.

There is one non-doc change, I changed Queue#size to an alias.

Doc changes include:

Updated RDoc style to match the std lib (+Mutex+ -> Mutex).

Documented Thread::exclusive

Documented Mutex#exclusive_unlock.  Please review this one, because  
I'm not sure it is correct/clear.  Nothing comes to mind about how it  
would be used, so an example would be nice.

Removed Pickaxe page reference from ConditionVariable.  (I think the  
example is sufficient, and a full explanation would take too much  
space.)

Provided an example of how to use a Queue to communicate between  
threads and mentioned the example in SizedQueue.

Documented several aliases.

Cleaned out all but one of the "Documentation comments" at the end of  
thread.rb.  I imagine the last of them could be removed as well.


-- 
Eric Hodel - drbrain@segment7.net - http://segment7.net
FEC2 57F1 D465 EB15 5D6E  7C11 332A 551C 796C 9F04

Attachments (1)

thread.rb.doc.patch (4.76 KB, text/x-diff)

Index: lib/thread.rb
===================================================================
RCS file: /src/ruby/lib/thread.rb,v
retrieving revision 1.16.2.1
diff -u -r1.16.2.1 thread.rb
--- lib/thread.rb	27 May 2004 07:50:04 -0000	1.16.2.1
+++ lib/thread.rb	3 Jun 2005 22:00:54 -0000
@@ -23,7 +23,8 @@
 
 class Thread
   #
-  # FIXME: not documented in Pickaxe or Nutshell.
+  # Wraps a block in Thread.critical, restoring the original value upon exit
+  # from the critical section.
   #
   def Thread.exclusive
     _old = Thread.critical
@@ -37,7 +38,7 @@
 end
 
 #
-# +Mutex+ implements a simple semaphore that can be used to coordinate access to
+# Mutex implements a simple semaphore that can be used to coordinate access to
 # shared data from multiple concurrent threads.
 #
 # Example:
@@ -58,6 +59,9 @@
 #   }
 #
 class Mutex
+  #
+  # Creates a new Mutex
+  #
   def initialize
     @waiting = []
     @locked = false;
@@ -123,7 +127,7 @@
 
   #
   # Obtains a lock, runs the block, and releases the lock when the block
-  # completes.  See the example under +Mutex+.
+  # completes.  See the example under Mutex.
   #
   def synchronize
     lock
@@ -135,7 +139,8 @@
   end
 
   #
-  # FIXME: not documented in Pickaxe/Nutshell.
+  # If the mutex is locked, unlocks the mutex, wakes one waiting thread, and
+  # yields in a critical section.
   #
   def exclusive_unlock
     return unless @locked
@@ -154,9 +159,9 @@
 end
 
 # 
-# +ConditionVariable+ objects augment class +Mutex+. Using condition variables,
+# ConditionVariable objects augment class Mutex. Using condition variables,
 # it is possible to suspend while in the middle of a critical section until a
-# resource becomes available (see the discussion on page 117).
+# resource becomes available.
 #
 # Example:
 #
@@ -181,6 +186,9 @@
 #   }
 #
 class ConditionVariable
+  #
+  # Creates a new ConditionVariable
+  #
   def initialize
     @waiters = []
   end
@@ -230,10 +238,31 @@
 end
 
 #
-# This class provides a way to communicate data between threads.
+# This class provides a way to synchronize communication between threads.
+#
+# Example:
 #
-# TODO: an example (code or English) would really help here.  How do you set up
-# a queue between two threads?
+#   require 'thread'
+#   
+#   queue = Queue.new
+#   
+#   producer = Thread.new do
+#     5.times do |i|
+#       sleep rand(i) # simulate expense
+#       queue << i
+#       puts "#{i} produced"
+#     end
+#   end
+#   
+#   consumer = Thread.new do
+#     5.times do |i|
+#       value = queue.pop
+#       sleep rand(i/2) # simulate expense
+#       puts "consumed #{value}"
+#     end
+#   end
+#   
+#   consumer.join
 #
 class Queue
   #
@@ -266,7 +295,15 @@
     rescue ThreadError
     end
   end
+
+  #
+  # Alias of push
+  #
   alias << push
+
+  #
+  # Alias of push
+  #
   alias enq push
 
   #
@@ -284,7 +321,15 @@
   ensure
     Thread.critical = false
   end
+
+  #
+  # Alias of pop
+  #
   alias shift pop
+
+  #
+  # Alias of pop
+  #
   alias deq pop
 
   #
@@ -311,9 +356,7 @@
   #
   # Alias of length.
   #
-  def size
-    length
-  end
+  alias size length
 
   #
   # Returns the number of threads waiting on the queue.
@@ -324,9 +367,11 @@
 end
 
 #
-# This class represents queues of specified size capacity.  The +push+ operation
+# This class represents queues of specified size capacity.  The push operation
 # may be blocked if the capacity is full.
 #
+# See Queue for an example of how a SizedQueue works.
+#
 class SizedQueue<Queue
   #
   # Creates a fixed-length queue with a maximum size of +max+.
@@ -370,6 +415,10 @@
     max
   end
 
+  #
+  # Pushes +obj+ to the queue.  If there is no space left in the queue, waits
+  # until space becomes available.
+  #
   def push(obj)
     Thread.critical = true
     while @que.length >= @max
@@ -379,9 +428,20 @@
     end
     super
   end
+
+  #
+  # Alias of push
+  #
   alias << push
+
+  #
+  # Alias of push
+  #
   alias enq push
 
+  #
+  # Retrieves data from the queue and runs a waiting thread, if any.
+  #
   def pop(*args)
     retval = super
     Thread.critical = true
@@ -401,20 +461,24 @@
     end
     retval
   end
+
+  #
+  # Alias of pop
+  #
   alias shift pop
+
+  #
+  # Alias of pop
+  #
   alias deq pop
 
+  #
+  # Returns the number of threads waiting on the queue.
+  #
   def num_waiting
     @waiting.size + @queue_wait.size
   end
 end
 
 # Documentation comments:
-#  - SizedQueue #push and #pop deserve some documentation, as they are different
-#    from the Queue implementations.
-#  - Some methods are not documented in Pickaxe/Nutshell, and are therefore not
-#    documented here.  See FIXME notes.
-#  - Reference to Pickaxe page numbers should be replaced with either a section
-#    name or a summary.
-#  - How do you document aliases?
 #  - How do you make RDoc inherit documentation from superclass?

Thread

Prev Next

In This Thread

Prev Next