summaryrefslogtreecommitdiff
path: root/lib/thwait.rb
diff options
context:
space:
mode:
authorgsinclair <gsinclair@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2003-01-17 15:17:20 +0000
committergsinclair <gsinclair@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2003-01-17 15:17:20 +0000
commitb1e4030244ddbaadd22f4ca01512cb22fba1771b (patch)
treeb9d483b20dab29107827214ac34e74ca566028f5 /lib/thwait.rb
parent99a3e3fdfa4fdeb9c72af7bddebc13fbb7a4c1ff (diff)
Added RDoc comments. See comments at EOF for TODOs.
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@3354 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'lib/thwait.rb')
-rw-r--r--lib/thwait.rb81
1 files changed, 57 insertions, 24 deletions
diff --git a/lib/thwait.rb b/lib/thwait.rb
index 00c8a8d..d9b134d 100644
--- a/lib/thwait.rb
+++ b/lib/thwait.rb
@@ -39,6 +39,18 @@
require "thread.rb"
require "e2mmap.rb"
+#
+# This class watches for termination of multiple threads. Basic functionality
+# (wait until specified threads have terminated) can be accessed through the
+# class method ThreadsWait::all_waits. Finer control can be gained using
+# instance methods.
+#
+# Example:
+#
+# ThreadsWait.all_wait(thr1, thr2, ...) do |t|
+# STDERR.puts "Thread #{t} has terminated."
+# end
+#
class ThreadsWait
RCS_ID='-$Id: thwait.rb,v 1.3 1998/06/26 03:19:34 keiju Exp keiju $-'
@@ -46,7 +58,11 @@ class ThreadsWait
def_exception("ErrNoWaitingThread", "No threads for waiting.")
def_exception("ErrNoFinishedThread", "No finished threads.")
- def ThreadsWait.all_waits(*threads)
+ #
+ # Waits until all specified threads have terminated. If a block is provided,
+ # it is executed for each thread termination.
+ #
+ def ThreadsWait.all_waits(*threads) # :yield: thread
tw = ThreadsWait.new(*threads)
if block_given?
tw.all_waits do |th|
@@ -57,43 +73,45 @@ class ThreadsWait
end
end
+ #
+ # Creates a ThreadsWait object, specifying the threads to wait on.
+ # Non-blocking.
+ #
def initialize(*threads)
@threads = []
@wait_queue = Queue.new
join_nowait(*threads) unless threads.empty?
end
- # accessing
- # threads - list threads to be synchronized
+ # Returns the array of threads in the wait queue.
attr :threads
- # testing
- # empty?
- # finished?
-
- # is there any thread to be synchronized.
+ #
+ # Returns true if there are no threads to be synchronized.
+ #
def empty?
@threads.empty?
end
- # is there already terminated thread.
+ #
+ # Returns true if any thread has terminated.
+ #
def finished?
!@wait_queue.empty?
end
- # main process:
- # join
- # join_nowait
- # next_wait
- # all_wait
-
- # adds thread(s) to join, waits for any of waiting threads to terminate.
+ #
+ # Waits for specified threads to terminate.
+ #
def join(*threads)
join_nowait(*threads)
next_wait
end
- # adds thread(s) to join, no wait.
+ #
+ # Specifies the threads that this object will wait for, but does not actually
+ # wait.
+ #
def join_nowait(*threads)
threads.flatten!
@threads.concat threads
@@ -105,10 +123,13 @@ class ThreadsWait
end
end
- # waits for any of waiting threads to terminate
- # if there is no thread to wait, raises ErrNoWaitingThread.
- # if `nonblock' is true, and there is no terminated thread,
- # raises ErrNoFinishedThread.
+ #
+ # Waits until any of the specified threads has terminated, and returns the one
+ # that does.
+ #
+ # If there is no thread to wait, raises +ErrNoWaitingThread+. If +nonblock+
+ # is true, and there is no terminated thread, raises +ErrNoFinishedThread+.
+ #
def next_wait(nonblock = nil)
ThreadsWait.fail ErrNoWaitingThread if @threads.empty?
begin
@@ -119,9 +140,12 @@ class ThreadsWait
end
end
- # waits until all of specified threads are terminated.
- # if a block is supplied for the method, evaluates it for
- # each thread termination.
+ #
+ # Waits until all of the specified threads are terminated. If a block is
+ # supplied for the method, it is executed for each thread termination.
+ #
+ # Raises exceptions in the same manner as +next_wait+.
+ #
def all_waits
until @threads.empty?
th = next_wait
@@ -131,3 +155,12 @@ class ThreadsWait
end
ThWait = ThreadsWait
+
+
+# Documentation comments:
+# - Source of doumentation is evenly split between Nutshell, existing
+# comments, and my own rephrasing.
+# - I'm not particularly confident that the comments are all exactly correct.
+# - The history, etc., up the top appears in the RDoc output. Perhaps it would
+# be better to direct that not to appear, and put something else there
+# instead.