From: Gavin Sinclair <gsinclair@...>
Date: 2003-01-17T03:28:05+09:00
Subject: Documentation for thread.rb

Hi ruby-core,

Below is a patch for thread.rb [1], containing RDoc comments.  These
comments are taken directly from Pickaxe.  Here are the rules I
followed when commenting (I made them up):

  I'm using +word+ to put things in fixed-width font when:
   - "word" appear in such font in Pickaxe
   - "word" is a parameter to a method (note that these typically
     appear in [...] in ri)

  I include page references, because they are currently in ri.

  If a method is not documented in Pickaxe, I mark that in the code
  with a FIXME.

  I don't include class examples from the Pickaxe, but should I?


If people on this list have established some rules about commenting
the standard libraries, please let me know what they are, as I intend
to document several more files. Please comment on the rules above and
the code below.

Note especially that Queue and SizedQueue are not documented in
Pickaxe (online version).  At least I can't find them.  I've therefore
made a comment in the code asking if "Ruby in a Nutshell" should be
used as a source instead.

Regards,
Gavin

[1] I'm inexperienced in creating patches - I just used cvs diff -u.
I don't expect this to be treated as a patch just yet anyway.


------------------------------ O< ------------------------------

RCS file: /src/ruby/lib/thread.rb,v
retrieving revision 1.14
diff -u -r1.14 thread.rb
--- thread.rb   27 Aug 2002 08:31:08 -0000      1.14
+++ thread.rb   16 Jan 2003 18:23:04 -0000
@@ -21,6 +21,9 @@
   Thread.abort_on_exception = true
 end
 
+#
+# FIXME: not documented in Pickaxe.
+#
 def Thread.exclusive
   _old = Thread.critical
   begin
@@ -31,6 +34,12 @@
   end
 end
 
+#
+# +Mutex+ implements a simple semaphore that can be used to coordinate access to
+# shared data from multiple concurrent threads.
+#
+# TODO: include example from Pickaxe?
+#
 class Mutex
   def initialize
     @waiting = []
@@ -39,10 +48,17 @@
     self.taint
   end
 
+  #
+  # Returns +true+ if this lock is currently held by some thread.
+  #
   def locked?
     @locked
   end
 
+  #
+  # Attempts to obtain the lock and returns immediately. Returns +true+ if the
+  # lock was granted.
+  #
   def try_lock
     result = false
     Thread.critical = true
@@ -54,6 +70,9 @@
     result
   end
 
+  #
+  # Attempts to grab the lock and waits if it isn't available.
+  #
   def lock
     while (Thread.critical = true; @locked)
       @waiting.push Thread.current
@@ -64,6 +83,9 @@
     self
   end
 
+  #
+  # Releases the lock. Returns +nil+ if ref wasn't locked.
+  #
   def unlock
     return unless @locked
     Thread.critical = true
@@ -82,6 +104,10 @@
     self
   end
 
+  #
+  # Obtains a lock (using +Mutex#lock+), runs the block, and releases the lock
+  # when the block completes.
+  #
   def synchronize
     lock
     begin
@@ -91,6 +117,9 @@
     end
   end
 
+  #
+  # FIXME: not documented in Pickaxe.
+  #
   def exclusive_unlock
     return unless @locked
     Thread.exclusive do
@@ -107,11 +136,21 @@
   end
 end
 
+# 
+# +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).
+#
+# TODO: include example from Pickaxe?
+#
 class ConditionVariable
   def initialize
     @waiters = []
   end
   
+  #
+  # Releases the lock held in +aMutex+ and waits; reacquires the lock on wakeup.
+  #
   def wait(mutex)
     mutex.exclusive_unlock do
       @waiters.push(Thread.current)
@@ -120,6 +159,9 @@
     mutex.lock
   end
   
+  #
+  # Wakes up the first thread in line waiting for this lock.
+  #
   def signal
     begin
       t = @waiters.shift
@@ -129,6 +171,9 @@
     end
   end
     
+  #
+  # Wakes up all threads waiting for this lock.
+  #
   def broadcast
     waiters0 = nil
     Thread.exclusive do
@@ -144,6 +189,9 @@
   end
 end
 
+#
+# FIXME: not documented in Pickaxe.  Should RiaN be used?
+#
 class Queue
   def initialize
     @que = []
@@ -205,6 +253,9 @@
   end
 end
 
+#
+# FIXME: not documented in Pickaxe.  Should RiaN be used?
+#
 class SizedQueue<Queue
   def initialize(max)
     raise ArgumentError, "queue size must be positive" unless max > 0