lava.thread
Class ThreadToolbox

java.lang.Object
  |
  +--lava.thread.ThreadToolbox

public class ThreadToolbox

extends java.lang.Object

Thread-related idioms.

Details: ThreadToolbox is a collection of functions (static methods) that perform common thread-related operations. Many of these functions are designed to replace common thread-related idioms, at the minor cost of a function call, for the gain of not having to type as much. An optimizing JIT compiler may actually inline these functions, and this class is deliberately coded to help the compiler recognize that inlining is acceptable.

Since:

1999.04.05

Constructor Summary

ThreadToolbox()

Method Summary

static boolean	join(java.lang.Thread t) Joins with thread.
static void	notifyAll(java.lang.Object o) Notifies all threads waiting on the given object.
static boolean	sleep(long millis) Sleeps for a specified time.
static boolean	sleepUntil(long deadline) Sleeps until a specified time.
static boolean	wait(java.lang.Object o) Waits on an object's monitor indefinitely.
static boolean	wait(java.lang.Object o, long timeout) Waits on an object's monitor for a maximum amount of time.
static void	waitNoInterrupt(java.lang.Object o) Waits on object ignoring interrupts.
static boolean	waitUntil(java.lang.Object o, long when) Waits on an object's monitor until a deadline.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ThreadToolbox

public ThreadToolbox()

Method Detail

wait

public static final boolean wait(java.lang.Object o,
                                 long timeout)

Waits on an object's monitor for a maximum amount of time.

Details: This method acquires o's monitor and then waits for another thread to call o's notify or notifyAll method, or for the timeout period to elapse, whichever comes sooner. If the calling thread is interrupted before either of these events, the InterruptedException is caught and discarded. true is returned if the calling thread was not interrupted, false otherwise.

Setting timeout to 0 indicates an infinite timeout period.

Parameters:

o - the object containing the monitor to wait on

timeout - the timeout period, in millis

wait

public static final boolean wait(java.lang.Object o)

Waits on an object's monitor indefinitely.

Details: This method acquires o's monitor and then waits for another thread to call o's notify or notifyAll method. If the calling thread is interrupted, the InterruptedException is caught and discarded. true is returned if an InterruptedException was not caught, false otherwise.

Parameters:

o - the object containing the monitor to wait on

waitNoInterrupt

public static final void waitNoInterrupt(java.lang.Object o)

Waits on object ignoring interrupts.

Details: waitNoInterrupt waits on the given object (o) and ignores all thread interrupts.

Parameters:

o - object to wait on

Since:

1999.09.08

waitUntil

public static final boolean waitUntil(java.lang.Object o,
                                      long when)

Waits on an object's monitor until a deadline.

Details: This method is similar to wait(Object,long), except that a deadline is specified instead of a timeout period. The deadline is given in milliseconds, in the same format as used by System.currentTimeMillis. If the deadline has already passed, no waiting will occur and true will be returned. Otherwise, a timeout period is computed and used in a deferring call to wait(Object,long), whose return value is returned by this function.

Parameters:

o - the object containing the monitor to wait on

sleep

public static final boolean sleep(long millis)

Sleeps for a specified time.

Details: This method causes the calling thread to sleep for the specified number of milliseconds, or return immediately if that number is not positive. If this thread is interrupted while sleeping, the InterruptedException will be caught and discarded. true is returned if the sleep was not interrupted, false otherwise.

Parameters:

millis - the number of milliseconds to sleep

sleepUntil

public static final boolean sleepUntil(long deadline)

Sleeps until a specified time.

Details: sleepUntil is the same as sleep(long), except that the sleep time is given not as a length of time, but rather as a deadline. The deadline value must be expressed using the same time-coordinate system as System.currentTimeMillis. If the deadline has passed, no sleep occurs and true is returned. Otherwise, true is returned if and only if the sleep completed without interruption.

Parameters:

deadline - the deadline

notifyAll

public static final void notifyAll(java.lang.Object o)

Notifies all threads waiting on the given object.

Details: notifyAll acquires o's monitor and then calls o's notifyAll method.

Parameters:

o - the object

join

public static final boolean join(java.lang.Thread t)

Joins with thread.

Details: This method suspends the current thread and does not return until the given thread (t) has died, unless the current thread is interrupted first. false is returned if the current thread was interrupted before the join operation could complete. true is returned if the join was successful.

Parameters:

t - the thread to join

Returns:

true iff the join was successful

Since:

1999.09.01