edu.ucla.sspace.util

Class WorkQueue

java.lang.Object

edu.ucla.sspace.util.WorkQueue

public class WorkQueue
extends Object

A utility class that receives a collection of tasks to execute internally and then distributes the tasks among a thread pool. This class offers to methods of use. In the first, a user can pass in a collection of tasks to run and then wait until the tasks are finished.

Collection tasks = new LinkedList();
WorkQueue q = new WorkQueue();
for (int i = 0; i < numTasks; ++i)
    tasks.add(new Runnable() { }); // job to do goes here
q.run(tasks);

Alternately, a use may register a task group identifier and then iteratively add new tasks associated with that identifier. At some point in the future, the user can then wait for all the tasks associated with that identifier to finish. This second method allows for the iterative construction of tasks, or for cases where not all of the data for the tasks is availabe at once (although the number of tasks is known).

WorkQueue q = new WorkQueue();
Object taskGroupId = Thread.currentThread(); // a unique id
q.registerTaskGroup(taskGroupId, numTasks);
for (int i = 0; i < numTasks; ++i)
    q.add(taskGroupId, new Runnable() { }); // job to do goes here
q.await(taskGroupId);

In the above example, the current thread is used as the group identifier, which ensures that any other thread executing the same code won't use the same identifier, which could result in either thread returning prematurely before its tasks have finished. However, a shared group identifier can allow multiple threads to add tasks for a common goal, with each being able await until all the tasks are finished.

Author:

David Jurgens

Method Summary

Methods

Modifier and Type	Method and Description
void	add(Object taskGroupId, Runnable task) Adds the provided task to the work queue on behalf of the task group identifier.
int	availableThreads() Returns the number of threads that are available to this WorkQueue for processing the enqueued tasks.
void	await(Object taskGroupId) Waits until all the tasks associated with the group identifier have finished.
boolean	await(Object taskGroupId, long timeout, TimeUnit unit) Waits until all the tasks associated with the group identifier have finished.
long	getRemainingTasks(Object taskGroupId) Returns the number of tasks that need to be completed before the group associated with the key is complete.
static WorkQueue	getWorkQueue() Returns the canonical instance of the WorkQueue to be used in running concurrent tasks.
static WorkQueue	getWorkQueue(int numThreads) Returns the canonical instance of the WorkQueue to be used in running concurrent tasks, ensuring the at least the specified number of threads are available.
Object	registerTaskGroup(int numTasks) Registers a new task group with the specified number of tasks to execute and returns a task group identifier to use when registering its tasks.
boolean	registerTaskGroup(Object taskGroupId, int numTasks) Registers a new task group with the specified number of tasks to execute, or returns false if a task group with the same identifier has already been registered.
void	run(Collection<Runnable> tasks) Executes the tasks using a thread pool and returns once all tasks have finished.
void	run(Runnable... tasks) Executes the tasks using a thread pool and returns once all tasks have finished.

Methods inherited from class java.lang.Object

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

Method Detail

add

public void add(Object taskGroupId,
       Runnable task)

Adds the provided task to the work queue on behalf of the task group identifier. Note that unlike the run method, this method returns immediately without waiting for the task to finish.

Parameters:

taskGroupId - an identifier associated with a set of tasks.

task - a task to run

Throws:

IllegalArgumentException - if the taskGroupId is not currently associated with any active taskGroup

await

public void await(Object taskGroupId)

Waits until all the tasks associated with the group identifier have finished. Once a task group has been successfully waited upon, the group identifier is removed from the queue and is valid to be reused for a new task group.

Throws:

IllegalArgumentException - if the taskGroupId is not currently associated with any active taskGroup

await

public boolean await(Object taskGroupId,
            long timeout,
            TimeUnit unit)

Waits until all the tasks associated with the group identifier have finished. Once a task group has been successfully waited upon, the group identifier is removed from the queue and is valid to be reused for a new task group.

Throws:

IllegalArgumentException - if the taskGroupId is not currently associated with any active taskGroup

getRemainingTasks

public long getRemainingTasks(Object taskGroupId)

Returns the number of tasks that need to be completed before the group associated with the key is complete. Note that this number includes both those tasks running and not yet completed, as well as tasks that have yet to be enqueued on behalf of this id.

Parameters:

taskGroupId - the key associated with a task group

Returns:

the number of tasks remaining or 0 if no group is associated with that task key

getWorkQueue

public static WorkQueue getWorkQueue()

Returns the canonical instance of the WorkQueue to be used in running concurrent tasks.

getWorkQueue

public static WorkQueue getWorkQueue(int numThreads)

Returns the canonical instance of the WorkQueue to be used in running concurrent tasks, ensuring the at least the specified number of threads are available.

registerTaskGroup

public Object registerTaskGroup(int numTasks)

Registers a new task group with the specified number of tasks to execute and returns a task group identifier to use when registering its tasks.

Parameters:

numTasks - the number of tasks that will be eventually run as a part of this group.

registerTaskGroup

public boolean registerTaskGroup(Object taskGroupId,
                        int numTasks)

Registers a new task group with the specified number of tasks to execute, or returns false if a task group with the same identifier has already been registered. This identifier will remain valid in the queue until await has been called.

Parameters:

taskGroupId - an identifier to be associated with a group of tasks

numTasks - the number of tasks that will be eventually run as a part of this group.

run

public void run(Runnable... tasks)

Executes the tasks using a thread pool and returns once all tasks have finished.

Throws:

IllegalStateException - if interrupted while waiting for the tasks to finish

run

public void run(Collection<Runnable> tasks)

Executes the tasks using a thread pool and returns once all tasks have finished.

Throws:

IllegalStateException - if interrupted while waiting for the tasks to finish

availableThreads

public int availableThreads()

Returns the number of threads that are available to this WorkQueue for processing the enqueued tasks.