ORG.hd.d.par
Class ParTasks

java.lang.Object
  |
  +--ORG.hd.d.par.ParTasks

public final class ParTasks
extends java.lang.Object

The parallel-task handler. This class attempts to run tasks in parallel in a simple way and to make best use of available CPUs.

This is meant to be in sympathy with my proposal of late 1998 to Sun with their bug ID 4186261.

When runTask() or runTasks() is called, the current predicted utilisation for the current thread (if any) is stacked and is replaced, in effect, by those of the new tasks, to be restored when the new tasks complete, successfully or unsuccessfully.

Version:
1.41 00/10/03
Author:
Damon Hart-Davis

Inner Class Summary
static interface ParTasks.ParTasksException
          Exception thrown as a result of a failed Task.
static class ParTasks.RepeatingIteratorCollection
          Wraps a Collection to return a repeating iterator.
static interface ParTasks.TaskFilter
          Functor for filtering objects.
static interface ParTasks.TaskMapper
          Functor for mapping one object to another.
static interface ParTasks.TaskProc
          Functor for getting side-effects only.
 
Field Summary
static java.lang.String SYS_PROP_PAR
          The system property name for the stipulated number of CPUs to use.
static int UTILISATION_ABSMAX
          The absolute maximum utilisation a single task can have, ie many CPUs to 100%.
static int UTILISATION_ABSMIN
          The absolute minimum utilisation a single task can have, eg 0% CPU.
static int UTILISATION_MAX
          The maximum utilisation a simple single-threaded task can have, eg largely CPU-bound.
static int UTILISATION_MIN
          The minimum believable utilisation a single task can have, largely I/O-bound.
 
Method Summary
static void apply(java.util.Collection cin, ParTasks.TaskFilter f, int maxThreads, int utilisation, java.util.Collection result)
          Apply a TaskFilter to a Collection of objects, copying suitable objects to the result Collection.
static void apply(java.util.Collection cin, ParTasks.TaskProc f, int maxThreads, int utilisation)
          Apply a TaskProc to a Collection of objects.
static void apply(java.util.Set cin, ParTasks.TaskMapper f, int maxThreads, int utilisation, java.util.Map result)
          Apply a TaskMap to a Set of objects, adding mappings from input to output objects to the result Map.
static int availableConcurrency()
          Get current estimate of count of system CPUs available.
static int getPropLevel()
          Get user-specified (in properties) level of paralleism.
static boolean noParallelism()
          If true, the user has explictly turned off parallelism.
static void runTask(java.lang.Runnable r, int utilisation)
          Runs a single task.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

UTILISATION_ABSMAX

public static final int UTILISATION_ABSMAX
The absolute maximum utilisation a single task can have, ie many CPUs to 100%.

UTILISATION_MAX

public static final int UTILISATION_MAX
The maximum utilisation a simple single-threaded task can have, eg largely CPU-bound.

UTILISATION_MIN

public static final int UTILISATION_MIN
The minimum believable utilisation a single task can have, largely I/O-bound.

UTILISATION_ABSMIN

public static final int UTILISATION_ABSMIN
The absolute minimum utilisation a single task can have, eg 0% CPU.

SYS_PROP_PAR

public static final java.lang.String SYS_PROP_PAR
The system property name for the stipulated number of CPUs to use. This must be positive.

If set to 1, this explicitly excludes parallism.

Method Detail

getPropLevel

public static int getPropLevel()
Get user-specified (in properties) level of paralleism.

noParallelism

public static boolean noParallelism()
If true, the user has explictly turned off parallelism.

availableConcurrency

public static int availableConcurrency()
Get current estimate of count of system CPUs available. Always strictly positive; units are whole CPUs.

runTask

public static void runTask(java.lang.Runnable r,
                           int utilisation)
                    throws ParTasks.ParTasksException
Runs a single task. The predicted CPU utilisation of the task is specified.

If the task r throws an exception it will not be propagated, and this routine will throw a ParTasksException.

Whatever the current estimated CPU utilisation this will run the task in the current thread.

The removes the old utilisation for this thread, if any, from the total load estimate, adds in the new utilisation and pushes it on the ThreadLocal stack of such utilisation.

This is effectively a base case.

It can also be used by some external spawner of tasks to inform the ParTasks system about other activity in the system.


apply

public static void apply(java.util.Collection cin,
                         ParTasks.TaskProc f,
                         int maxThreads,
                         int utilisation)
                  throws ParTasks.ParTasksException
Apply a TaskProc to a Collection of objects. The Collection must not be altered while this routine is running. The TaskProc is applied to all of the objects in the collection.

apply

public static void apply(java.util.Collection cin,
                         ParTasks.TaskFilter f,
                         int maxThreads,
                         int utilisation,
                         java.util.Collection result)
Apply a TaskFilter to a Collection of objects, copying suitable objects to the result Collection. The Collection must not be altered while this routine is running. The TaskFilter is applied to all of the objects in the collection, and all input items in cin that cause f.fn() to return a boolean are added to result. The result is wrapped in a synchronizing wrapper...

The result might typically be a Set or a Vector.


apply

public static void apply(java.util.Set cin,
                         ParTasks.TaskMapper f,
                         int maxThreads,
                         int utilisation,
                         java.util.Map result)
Apply a TaskMap to a Set of objects, adding mappings from input to output objects to the result Map. The Collection must not be altered while this routine is running. The TaskMap is applied to all of the objects in the collection.

This applies to a Set to ensure that the input collection has unique keys to use as the key set for the Map result.


(c) Damon Hart-Davis 1999--2000