mandala.util
Class ThreadPool

java.lang.Object
  java.lang.ThreadGroup
      mandala.util.ThreadPool

public class ThreadPool

extends java.lang.ThreadGroup

Threads pool implementation.

A threads pool usually prevent the non-negligeable cost of threads creation using a pool of already pre-allocated threads.

The behaviour of an instance of this class is defined by many parameters.

• min: the minimum amount of threads this pool must contain;
• max: the maximum amount of threads this pool may contain;
• reactivity: the timeout of the thread-balancer sleep;
• priority the priority of the threads in the pool;
• daemonStatus: the daemon status of the threads in the pool.

.

This pool has a thread-balancer suplementary thread which is responsible of the creation of more threads when needed up to the max limits. If this instance is given more tasks than it contains threads, the thread-balancer will starts the necessary amount of threads, up to the max limit, to run the given number of tasks. To prevent a yoyo-effect, threads in the pool are destroyed one by one, while they are created n at a time. The thread-balancer is awaken each reactivity to balance the pool size related to the tasks size.

WARNING : You really must take care of code which insert Runnable task which insert others Runnable task and wait for their termination: deadlocks may occurs !

Version:

$Revision: 1.20 $

Author:

eipi

See Also:

ThreadGroup

Nested Class Summary

class

ThreadPool.ThreadPoolCancelable

Field Summary

protected boolean	daemonStatus Daemon status given to new threads in this pool.
static boolean	DEFAULT_DAEMON_STATUS Deamon status given to new threads in the pool.
static int	DEFAULT_MAX_THREADS_NB Default maximum of threads in a ThreadPool.
static java.lang.String	DEFAULT_MAX_THREADS_NB_PROPERTY
static int	DEFAULT_MIN_THREADS_NB Default minimum of threads in a ThreadPool.
static java.lang.String	DEFAULT_MIN_THREADS_NB_PROPERTY
static int	DEFAULT_PRIORITY Priority given to new threads in the pool.
static java.lang.String	DEFAULT_PRIORITY_PROPERTY
static long	DEFAULT_REACTIVITY_TIMER Time in milliseconds of the thread-balancer reactivity.
static java.lang.String	DEFAULT_REACTIVITY_TIMER_PROPERTY
static Syslog	DEFAULT_SYSLOG The Syslog used for logging when none are specified using the setSyslog() method.
static int	DELTA_PRIORITY Default priority is set to Thread.NORM_PRIORITY + DELTA_PRIORITY.
protected static int	instancesNumber Number of ThreadPool instances used for automatic name generation in ThreadPool(int min, int max).
protected int	max Maximum amount of pre-allocated threads in this thread pool.
protected int	min Minimum amount of pre-allocated threads in this thread pool.
protected int	priority Priority given to new threads in this pool.
protected long	reactivity Reactivity of the thread-balancer.
protected Syslog	syslog The Syslog object facility.

Constructor Summary

ThreadPool()
Creates a new ThreadPool instance.

ThreadPool(int min, int max)
Creates a new ThreadPool instance.

ThreadPool(java.lang.String name)
Creates a new ThreadPool instance.

ThreadPool(java.lang.String name, int min, int max)
Creates a new ThreadPool instance.

ThreadPool(java.lang.ThreadGroup parent, java.lang.String name, int min, int max)
Creates a new ThreadPool instance.

ThreadPool(java.lang.ThreadGroup parent, java.lang.String name, int min, int max, int priority, boolean daemonStatus, long reactivity)
Creates a new ThreadPool instance.

Method Summary

void	cancel() Cancel the execution of all tasks in this threadpool.
boolean	cancel(ThreadPool.ThreadPoolCancelable cancelable) Cancel the execution of a previously given task.
boolean[]	cancel(ThreadPool.ThreadPoolCancelable[] cancelables) Cancel the execution of previously given tasks.
void	delete() Destroy this threadpool and all of its related threads.
ThreadPool.ThreadPoolCancelable	execute(java.lang.Runnable task) Request the execution of the specified task.
protected void	finalize()
boolean	getDaemonStatus() Get the daemon status given to new threads in this pool.
int	getMax() Get the maximum amount of pre-allocated threads in this thread pool.
int	getMin() Get the minimum amount of pre-allocated threads in this thread pool.
int	getPriority() Get the priority given to new threads in this pool.
long	getReactivity() Get the reactivity of the thread-balancer.
Syslog	getSyslog() Returns the Syslog instance used for logging.
boolean	interrupt(ThreadPool.ThreadPoolCancelable cancelable) Interrupt the execution of a task currently executed by a thread of this thread pool.
boolean[]	interrupt(ThreadPool.ThreadPoolCancelable[] cancelables) Interrupt the execution of tasks currently executed by some threads of this thread pool.
boolean	isStarted() Returns true if this thread pool has been started, false otherwize.
void	setSyslog(Syslog syslog) Set the Syslog instance to use for logging.
void	start() Starts the ThreadPool.
java.lang.String	toString()

Methods inherited from class java.lang.ThreadGroup

activeCount, activeGroupCount, allowThreadSuspension, checkAccess, destroy, enumerate, enumerate, enumerate, enumerate, getMaxPriority, getName, getParent, interrupt, isDaemon, isDestroyed, list, parentOf, resume, setDaemon, setMaxPriority, stop, suspend, uncaughtException

Methods inherited from class java.lang.Object

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

Field Detail

instancesNumber

protected static int instancesNumber

Number of ThreadPool instances used for automatic name generation in ThreadPool(int min, int max).

DEFAULT_SYSLOG

public static Syslog DEFAULT_SYSLOG

The Syslog used for logging when none are specified using the setSyslog() method.

See Also:

Syslog, setSyslog(Syslog)

syslog

protected Syslog syslog

The Syslog object facility.

Each message (debug, log, warning, error, ...) are wrote to this message logger.

Default value is set to DEFAULT_SYSLOG.

See Also:

Syslog

DEFAULT_MIN_THREADS_NB

public static final int DEFAULT_MIN_THREADS_NB

Default minimum of threads in a ThreadPool.

The value of this field can be customized by the mandala.util.ThreadPool.min property. Default is new Double(Math.ceil(Runtime.availableProcessors() * 1.5)).intValue().

DEFAULT_MIN_THREADS_NB_PROPERTY

public static final java.lang.String DEFAULT_MIN_THREADS_NB_PROPERTY

DEFAULT_MAX_THREADS_NB

public static final int DEFAULT_MAX_THREADS_NB

Default maximum of threads in a ThreadPool.

The value of this field can be customized by the mandala.util.ThreadPool.max property. Default is Integer.MAX_VALUE.

DEFAULT_MAX_THREADS_NB_PROPERTY

public static final java.lang.String DEFAULT_MAX_THREADS_NB_PROPERTY

DELTA_PRIORITY

public static final int DELTA_PRIORITY

Default priority is set to Thread.NORM_PRIORITY + DELTA_PRIORITY.

See Also:

Constant Field Values

DEFAULT_PRIORITY

public static final int DEFAULT_PRIORITY

Priority given to new threads in the pool.

The value of this field can be customized by the mandala.util.ThreadPool.priority property. Default is Thread.NORM_PRIORITY + DELTA_PRIORITY.

DEFAULT_PRIORITY_PROPERTY

public static final java.lang.String DEFAULT_PRIORITY_PROPERTY

DEFAULT_DAEMON_STATUS

public static final boolean DEFAULT_DAEMON_STATUS

Deamon status given to new threads in the pool.

Default is always true.

See Also:

Constant Field Values

DEFAULT_REACTIVITY_TIMER

public static final long DEFAULT_REACTIVITY_TIMER

Time in milliseconds of the thread-balancer reactivity.

The value of this field can be customized by the mandala.util.ThreadPool.reactivity property. Default is 5 seconds.

DEFAULT_REACTIVITY_TIMER_PROPERTY

public static final java.lang.String DEFAULT_REACTIVITY_TIMER_PROPERTY

min

protected int min

Minimum amount of pre-allocated threads in this thread pool.

max

protected int max

Maximum amount of pre-allocated threads in this thread pool.

priority

protected int priority

Priority given to new threads in this pool.

daemonStatus

protected boolean daemonStatus

Daemon status given to new threads in this pool.

reactivity

protected long reactivity

Reactivity of the thread-balancer.

Constructor Detail

ThreadPool

public ThreadPool(java.lang.String name)

Creates a new ThreadPool instance.

Equivalent to ThreadPool(name, DEFAULT_MIN_THREADS_NB, DEFAULT_MAX_THREADS_NB).

Parameters:

name - the name of the new thread pool.

ThreadPool

public ThreadPool()

Creates a new ThreadPool instance.

Equivalent to ThreadPool(DEFAULT_MIN_THREADS_NB, DEFAULT_MAX_THREADS_NB).

ThreadPool

public ThreadPool(int min,
                  int max)

Creates a new ThreadPool instance.

Equivalent to ThreadPool(gname, min, max). where gname is where gname is a newly generated name. Automatically generated names are of the form ThreadPool.class.getName() + "#" + n, where n is an integer.

ThreadPool

public ThreadPool(java.lang.String name,
                  int min,
                  int max)

Creates a new ThreadPool instance.

Equivalent to ThreadPool(Thread.currentThread().getThreadGroup(), name, min, max).

ThreadPool

public ThreadPool(java.lang.ThreadGroup parent,
                  java.lang.String name,
                  int min,
                  int max)

Creates a new ThreadPool instance.

Equivalent to ThreadPool(parent, name, min, max, DEFAULT_PRIORITY, DEFAULT_DAEMON_STATUS, DEFAULT_REACTIVITY_TIMER).

ThreadPool

public ThreadPool(java.lang.ThreadGroup parent,
                  java.lang.String name,
                  int min,
                  int max,
                  int priority,
                  boolean daemonStatus,
                  long reactivity)

Creates a new ThreadPool instance.

The created instance has parent as parent's thread group, name as name and an initial pool of min threads. It may allocate a maximum of max threads if needed. The threads in the pool will be assigned to the given priority and daemonStatus. The thread-balancer will have the given reactivity

Parameters:

parent - the parent thread group.

name - the name of the new thread pool.

min - the minimum amount of pre-allocated threads in this thread pool.

max - the maximum amount of pre-allocated threads in this thread pool.

priority - the priority given to new threads in this pool.

daemonStatus - the daemon status given to new threads in this pool.

reactivity - the reactivity given to the thread-balancer of this pool.

Method Detail

getSyslog

public Syslog getSyslog()

Returns the Syslog instance used for logging.

Returns:

the Syslog instance used for logging.

setSyslog

public void setSyslog(Syslog syslog)

Set the Syslog instance to use for logging.

Parameters:

syslog - the Syslog instance to use for logging.

See Also:

Syslog

getMin

public int getMin()

Get the minimum amount of pre-allocated threads in this thread pool.

Returns:

the minimum amount of pre-allocated threads in this thread pool.

getMax

public int getMax()

Get the maximum amount of pre-allocated threads in this thread pool.

Returns:

the maximum amount of pre-allocated threads in this thread pool.

getPriority

public int getPriority()

Get the priority given to new threads in this pool.

Returns:

the priority given to new threads in this pool.

getDaemonStatus

public boolean getDaemonStatus()

Get the daemon status given to new threads in this pool.

Returns:

the daemon status given to new threads in this pool.

getReactivity

public long getReactivity()

Get the reactivity of the thread-balancer.

Returns:

the reactivity of the thread-balancer.

toString

public java.lang.String toString()

isStarted

public boolean isStarted()

Returns true if this thread pool has been started, false otherwize.

Returns:

true if this thread pool has been started, false otherwize.

start

public void start()

Starts the ThreadPool.

This method also start min threads, sets their priority to priority, their daemon status to daemonStatus and start the thread-balancer.

After this invocation, isStarted() always returns true and further call to this method does nothing.

delete

public void delete()

Destroy this threadpool and all of its related threads.

execute

public ThreadPool.ThreadPoolCancelable execute(java.lang.Runnable task)

Request the execution of the specified task.

Parameters:

task - the Runnable to execute in a separate thread.

Returns:

a handle that may be used for cancellation or interruption.

cancel

public boolean cancel(ThreadPool.ThreadPoolCancelable cancelable)

Cancel the execution of a previously given task.

This method does nothing if the task related to the specified cancelable has already been executed, or if it is currently executed by a thread of the pool.

Parameters:

cancelable - the ThreadPoolCancelable instance returned by execute().

Returns:

true if the given task has been succesfully cancelled, false otherwise.

See Also:

execute(Runnable task)

cancel

public boolean[] cancel(ThreadPool.ThreadPoolCancelable[] cancelables)

Cancel the execution of previously given tasks.

Parameters:

cancelables - the Cancelable instances returned by execute().

Returns:

the boolean status array where the boolean value at index i is the value that may have been returned by cancel(cancelables[i]).

See Also:

cancel(ThreadPool.ThreadPoolCancelable cancelable)

cancel

public void cancel()

Cancel the execution of all tasks in this threadpool.

When this method returns, any previous tasks given for execution has been canceled. Note however some tasks may still be executed by threads in this pool.

interrupt

public boolean interrupt(ThreadPool.ThreadPoolCancelable cancelable)

Interrupt the execution of a task currently executed by a thread of this thread pool.

This method does nothing if the task related to the specified cancelable has already been executed, or if it is not yet executed by a thread of this thread pool.

Parameters:

cancelable - the Cancelable instance returned by execute().

Returns:

true if the given task has been succesfully interrupted, false otherwise.

See Also:

execute(Runnable task)

interrupt

public boolean[] interrupt(ThreadPool.ThreadPoolCancelable[] cancelables)

Interrupt the execution of tasks currently executed by some threads of this thread pool.

Parameters:

cancelables - the Cancelable instances returned by execute().

Returns:

the boolean status array where the boolean value at index i is the value that may have been returned by interrupt(cancelables[i]).

See Also:

interrupt(ThreadPool.ThreadPoolCancelable cancelable)

finalize

protected void finalize()
                 throws java.lang.Throwable

Throws:

java.lang.Throwable