From: Eric Hodel Date: 2005-06-04T07:06:16+09:00 Subject: [PATCH] thread.rb documentation --Apple-Mail-3--57264098 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed 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. --Apple-Mail-3--57264098 Content-Transfer-Encoding: 7bit Content-Type: application/octet-stream; x-unix-mode=0644; name="thread.rb.doc.patch" Content-Disposition: attachment; filename=thread.rb.doc.patch 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= @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? --Apple-Mail-3--57264098 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset=US-ASCII; format=flowed -- Eric Hodel - drbrain@segment7.net - http://segment7.net FEC2 57F1 D465 EB15 5D6E 7C11 332A 551C 796C 9F04 --Apple-Mail-3--57264098--