org.gjt.rec.thread
Class Workforce

java.lang.Object
  |
  +--org.gjt.rec.thread.Workforce

public final class Workforce

extends Object

This is a thread pool, which could be useful if you have lots of work to do that involves blocking for data and want to keep a cap on the number of threads running. No actual threads are loaned to client code by this class. Instead, client code gives this class units of work to do, which are executed by the threads.

The jobs supplied to a workforce are implementations of the Runnable interface. They should catch all their own exceptions, although if they do not, the listener will be notified and supplied with the exception thrown by the job.

It is possible to give jobs to a workforce that has been stopped. The API allows client code to determine if a workforce has unfinished jobs that have not been given to a worker thread and allows the code to recall those jobs.

Nested Class Summary

static class	Workforce.JobNotWaitingException Thrown to indicate that a job that was supposed to be on the list of waiting jobs is not on the list.
static interface	Workforce.Listener An implementation of this interface may listen to a Workforce object and be notified when certain notable events occur within it.
static class	Workforce.State Enumerated type representing the possible states of a Workforce.

Field Summary

static String	COPYRIGHT
static String	LICENSE
static String	REVISION

Constructor Summary

Workforce()

Method Summary

int	getCapacity()
List	getJobsWaiting() Returns a read-only list of jobs that are waiting to be completed.
Object	getJobsWaitingLock() Returns the lock on the waiting jobs list.
Workforce.State	getState() Any modifications to the state field are synchronized on this workforce, so client code should do the same if it wishes to perform an atomic state check followed by startup request.
void	recallJob(Runnable job) Takes a job off the list of jobs that are waiting to be completed.
void	scheduleJob(Runnable newJob) Schedules a new job to be completed by this workforce.
void	scheduleStop() Schedules this workforce to stop.
void	setCapacity(int newCapacity) Sets the maximum number of threads that will run concurrently in order to complete the jobs that are waiting.
void	setListener(Workforce.Listener newListener) Sets the only listener that may listen to events on this workforce.
void	start() Starts this workforce.

Methods inherited from class java.lang.Object

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

Field Detail

COPYRIGHT

public static final String COPYRIGHT

See Also:

Constant Field Values

LICENSE

public static final String LICENSE

See Also:

Constant Field Values

REVISION

public static final String REVISION

See Also:

Constant Field Values

Constructor Detail

Workforce

public Workforce()

Method Detail

getCapacity

public int getCapacity()

Returns:

the maximum number of threads that will run concurrently in order to complete the jobs that are waiting

setCapacity

public void setCapacity(int newCapacity)

Sets the maximum number of threads that will run concurrently in order to complete the jobs that are waiting. Note that if the capacity is reduced, only idle threads will be stopped until some of the active ones complete their current jobs.

Parameters:

newCapacity - the new capacity

Throws:

IllegalArgumentException - if newCapacity is less than one

getJobsWaiting

public List getJobsWaiting()

Returns a read-only list of jobs that are waiting to be completed. This list may be inaccurate unless the calling thread has first synchronized on the lock for this list.

Returns:

a list of objects implementing the Runnable interface

See Also:

getJobsWaitingLock()

getJobsWaitingLock

public Object getJobsWaitingLock()

Returns the lock on the waiting jobs list. The lock can be synchronized on to gain mutual exclusion to the list of waiting jobs. No jobs may be started or added to the list by other threads while this lock is held. Its primary use is to find a job in the waiting job list and recall it in one atomic operation.

Returns:

an Object that is used as a mutex

scheduleJob

public void scheduleJob(Runnable newJob)

Schedules a new job to be completed by this workforce.

Parameters:

newJob - the job to schedule

Throws:

NullPointerException - if newJob is null

recallJob

public void recallJob(Runnable job)

Takes a job off the list of jobs that are waiting to be completed.

Parameters:

job - the job to recall

Throws:

Workforce.JobNotWaitingException - if the job was not found on the list of jobs waiting to be completed

getState

public Workforce.State getState()

Any modifications to the state field are synchronized on this workforce, so client code should do the same if it wishes to perform an atomic state check followed by startup request.

NOTE: Even when the state is State.STOPPED, some jobs may yet be incomplete. This detail of the API may change in future.

Returns:

the state of this workforce

start

public void start()

Starts this workforce. Jobs may be scheduled in any state, although no work will happen unless the state of this workforce is in the state State.STARTED.

Throws:

IllegalStateException - if this workforce is not stopped

scheduleStop

public void scheduleStop()

Schedules this workforce to stop. It is stopped when getState() returns State.STOPPED.

Throws:

IllegalStateException - if this workforce is not started

setListener

public void setListener(Workforce.Listener newListener)

Sets the only listener that may listen to events on this workforce. The old listener (if any) will be notified of its loss. The new listener will be notified of its new status.

Parameters:

newListener - the new object that will receive events from this workforce or null if no object is to receive such events