Methods
A
The return values of navigation methods may be ambiguous in implementations
that permit
If
The returned set must throw an
The returned set is backed by this set, so changes in the returned set are reflected in this set, and vice-versa. The returned set supports all optional set operations that this set supports.
The returned set must throw an
The returned set is backed by this set, so changes in the returned set are reflected in this set, and vice-versa. The returned set supports all optional set operations that this set supports.
The returned set will throw an
bool[1] holder;
object reference = v.GetobjectReference(holder);
int[1] holder;
object reference = v.GetobjectReference(holder);
class Producer : IRunnable {
private IBlockingQueue queue;
Producer(IBlockingQueue q) { queue = q; }
public void Run() {
try {
while (true) {
queue.Put(produce());
}
} catch (InterruptedException ex) {
... handle ...
}
}
Object Produce() { ... }
}
class Consumer : IRunnable {
private IBlockingQueue queue;
Consumer(IBlockingQueue q) { queue = q; }
public void Run() {
try {
while (true) { Consume(queue.Take()); }
} catch (InterruptedException ex) { ... handle ...}
}
void Consume(object x) { ... }
}
class Setup {
void Main() {
IBlockingQueue q = new SomeQueueImplementation();
Producer p = new Producer(q);
Consumer c1 = new Consumer(q);
Consumer c2 = new Consumer(q);
new Thread(new ThreadStart(p.Run)).Start();
new Thread(new ThreadStart(c1.Run)).Start();
new Thread(new ThreadStart(c2.Run)).Start();
}
}
string[] y = x.ToArray(new string[0]);
Note that The queue will be empty after this call returns.
This implementation repeatedly invokes
if (!dictionary.Contains(key))
return dictionary.Add(key, keyValue);
else
return dictionary[key[;
except that the action is performed atomically.
if (dictionary.Contains(key) && dictionary[key].Equals(keyValue)) {
dictionary.Remove(key);
return true;
} else {
return false;
}
except that the action is performed atomically.
if (dictionary.Contains(key) && dictionary[key].Equals(oldValue)) {
dictionary.Add(key, newValue);
return true;
} else {
return false;
}
except that the action is performed atomically.
if (dictionary.Contains(key)) {
return dictionar.Add(key, keyValue);
} else {
return null;
}
except that the action is performed atomically.
When using a capacity-restricted queue, this method is generally
preferable to
string[] y = x.ToArray(new string[0]);
Note that toArray(new object[0]) is identical in function to
The queue will be empty after this call returns.
This implementation repeatedly invokes
When using a capacity-restricted queue, this method is generally
preferable to
This method differs from
This method differs from
public class CustomThreadPoolExecutor : ThreadPoolExecutor {
static class CustomTask : IRunnableFuture {...}
protected IRunnableFuture newTaskFor(ICallable c) {
return new CustomTask(c);
}
protected IRunnableFuture newTaskFor(IRunnable r) {
return new CustomTask(r);
}
// ... add constructors, etc.
}
class DirectExecutor : IExecutor {
public void Execute(IRunnable r) {
r.Run();
}
}
More typically, tasks are executed in some thread other
than the caller's thread. The executor below spawns a new thread
for each task.
class ThreadPerTaskExecutor : IExecutor {
public void Execute(IRunnable r) {
new Thread(new ThreadStart(r.Run)).Start();
}
}
Many
result = exec.Submit(aCallable).GetResult();
Note: The
result = exec.Submit(aCallable).GetResult();
Note: The
Future f = new FutureTask(runnable, null)
Interface for runnable actions that bear results and/or throw Exceptions. This interface is designed to provide a common protocol for result-bearing actions that can be run independently in threads, in which case they are ordinarily used as the bases of Runnables that set FutureResults
class SimpleThreadFactory : IThreadFactory {
public Thread NewThread(IRunnable r) {
return new Thread(new ThreadStart(r.Run));
}
}
The
public class PausableThreadPoolExecutor : ThreadPoolExecutor {
private boolean isPaused;
private ReentrantLock pauseLock = new ReentrantLock();
private ICondition unpaused = pauseLock.NewCondition();
public PausableThreadPoolExecutor(...) { super(...); }
protected override void beforeExecute(Thread t, IRunnable r) {
super.beforeExecute(t, r);
pauseLock.Lock();
try {
while (isPaused) unpaused.Await();
} catch (ThreadInterruptedException ie) {
t.Interrupt();
} finally {
pauseLock.Unlock();
}
}
public void Pause() {
pauseLock.Lock();
try {
isPaused = true;
} finally {
pauseLock.Unlock();
}
}
public void Resume() {
pauseLock.Lock();
try {
isPaused = false;
unpaused.SignalAll();
} finally {
pauseLock.Unlock();
}
}
}
result = exec.Submit(aCallable).GetResult();
Note: The FJTasks are lightweight, stripped-down analogs of Threads. Many FJTasks share the same pool of Java threads. This is supported by the FJTaskRunnerGroup and FJTaskRunner classes, that mainly contain methods called only internally by FJTasks. FJTasks support versions of the most common methods found in class Thread, including start(), yield() and join(). However, they don't support priorities, ThreadGroups or other bookkeeping or control methods of class Thread.
FJTasks should normally be defined by subclassing and adding a run() method.
Alternatively, inner class
There are three different ways to run a FJTask, with different scheduling semantics:
The main economies of FJTasks stem from the fact that FJTasks do not support blocking operations of any kind. FJTasks should just run to completion without issuing waits or performing blocking IO. There are several styles for creating the run methods that execute as tasks, including event-style methods, and pure computational methods. Generally, the best kinds of FJTasks are those that in turn generate other FJTasks.
There is nothing actually
preventing you from blocking within a FJTask, and very short waits/blocks are
completely well behaved. But FJTasks are not designed
to support arbitrary synchronization
since there is no way to suspend and resume individual tasks
once they have begun executing. FJTasks should also be finite
in duration -- they should not contain infinite loops.
FJTasks that might need to perform a blocking
action, or hold locks for extended periods, or
loop forever can instead create normal
FJTasks, and the FJTaskRunners that execute them are not
intrinsically robust with respect to exceptions.
A FJTask that aborts via an exception does not automatically
have its completion flag (
The overhead differences between FJTasks and Threads are substantial,
especially when using
Given these overhead savings, you might be tempted to use FJTasks for everything you would use a normal Thread to do. Don't. Threads remain better for general purpose thread-based programming. Remember that FJTasks cannot be used for designs involving arbitrary blocking synchronization or I/O. Extending FJTasks to support such capabilities would amount to re-inventing the Thread class, and would make them less optimal in the contexts that they were designed for.
Fork() is noticeably faster than start(). However, it may only be used for strictly dependent tasks -- generally, those that could logically be issued as straight method calls without changing the logic of the program. The method is optimized for use in parallel fork/join designs in which the thread that issues one or more forks cannot continue until at least some of the forked threads terminate and are joined.
Spinloops based on yield() are well behaved so long as the event or condition being waited for is produced via another FJTask. Additionally, you must never hold a lock while performing a yield or join. (This is because multiple FJTasks can be run by the same Thread during a yield. Since java locks are held per-thread, the lock would not maintain the conceptual exclusion you have in mind.)
Otherwise, spinloops using yield are the main construction of choice when a task must wait for a condition that it is sure will eventually occur because it is being produced by some other FJTask. The most common such condition is built-in: join() repeatedly yields until a task has terminated after producing some needed results. You can also use yield to wait for callbacks from other FJTasks, to wait for status flags to be set, and so on. However, in all these cases, you should be confident that the condition being waited for will occur, essentially always because it is produced by a FJTask generated by the current task, or one of its subtasks.
while(!isDone()) yield();
task1.fork(); task2.fork(); task2.join(); task1.join();
As a simple classic example, here is
a class that computes the Fibonacci function:
public class Fib extends FJTask {
// Computes fibonacci(n) = fibonacci(n-1) + fibonacci(n-2); for n> 1
// fibonacci(0) = 0;
// fibonacci(1) = 1.
// Value to compute fibonacci function for.
// It is replaced with the answer when computed.
private volatile int number;
public Fib(int n) { number = n; }
public int getAnswer() {
if (!isDone()) throw new Error("Not yet computed");
return number;
}
public void run() {
int n = number;
if (n > 1) {
Fib f1 = new Fib(n - 1);
Fib f2 = new Fib(n - 2);
coInvoke(f1, f2); // run these in parallel
// we know f1 and f2 are computed, so just directly access numbers
number = f1.number + f2.number;
}
}
public static void main(String[] args) { // sample driver
try {
int groupSize = 2; // 2 worker threads
int num = 35; // compute fib(35)
FJTaskRunnerGroup group = new FJTaskRunnerGroup(groupSize);
Fib f = new Fib(num);
group.invoke(f);
int result = f.getAnswer();
System.out.println(" Answer: " + result);
}
catch (InterruptedException ex) {
System.out.println("Interrupted");
}
}
}
for (int i = 0; i < tasks.length; ++i) tasks[i].fork();
for (int i = 0; i < tasks.length; ++i) tasks[i].join();
new Seq, when executed,
invokes each task provided in the constructor, in order.
The class is a simple utility
that makes it easier to create composite FJTasks.
new Par, when executed,
runs the tasks provided in the constructor in parallel using
coInvoke(tasks).
The class is a simple utility
that makes it easier to create composite FJTasks.
new Seq2(task1, task2), when executed,
invokes task1 and then task2, in order.
The class is a simple utility
that makes it easier to create composite Tasks.
new Par(task1, task2), when executed,
runs task1 and task2 in parallel using coInvoke(task1, task2).
The class is a simple utility
that makes it easier to create composite Tasks.
Each FJTaskRunner keeps FJTasks in a double-ended queue (DEQ). Double-ended queues support stack-based operations push and pop, as well as queue-based operations put and take. Normally, threads run their own tasks. But they may also steal tasks from each others DEQs.
The algorithms are minor variants of those used in Cilk and Hood, and to a lesser extent Filaments, but are adapted to work in Java.
The two most important capabilities are:
Push task onto DEQ
If DEQ is not empty,
Pop a task and run it.
Else if any other DEQ is not empty,
Take ("steal") a task from it and run it.
Else if the entry queue for our group is not empty,
Take a task from it and run it.
Else if current thread is otherwise idling
If all threads are idling
Wait for a task to be put on group entry queue
Else
Yield or Sleep for a while, and then retry
The push, pop, and put are designed to only ever called by the
current thread, and take (steal) is only ever called by
other threads.
All other operations are composites and variants of these,
plus a few miscellaneous bookkeeping methods.
Implementations of the underlying representations and operations are geared for use on JVMs operating on multiple CPUs (although they should of course work fine on single CPUs as well).
A possible snapshot of a FJTaskRunner's DEQ is:
0 1 2 3 4 5 6 ...
+-----+-----+-----+-----+-----+-----+-----+--
| | t | t | t | t | | | ... deq array
+-----+-----+-----+-----+-----+-----+-----+--
^ ^
base top
(incremented (incremented
on take, on push
decremented decremented
on put) on pop)
FJTasks are held in elements of the DEQ.
They are maintained in a bounded array that
works similarly to a circular bounded buffer. To ensure
visibility of stolen FJTasks across threads, the array elements
must be volatile.
Using volatile rather than synchronizing suffices here since
each task accessed by a thread is either one that it
created or one that has never seen before. Thus we cannot
encounter any staleness problems executing run methods,
although FJTask programmers must be still sure to either synch or use
volatile for shared data within their run methods.
However, since there is no way to declare an array of volatiles in Java, the DEQ elements actually hold VolatileTaskRef objects, each of which in turn holds a volatile reference to a FJTask. Even with the double-indirection overhead of volatile refs, using an array for the DEQ works out better than linking them since fewer shared memory locations need to be touched or modified by the threads while using the DEQ. Further, the double indirection may alleviate cache-line sharing effects (which cannot otherwise be directly dealt with in Java).
The indices for the base and top of the DEQ
are declared as volatile. The main contention point with
multiple FJTaskRunner threads occurs when one thread is trying
to pop its own stack while another is trying to steal from it.
This is handled via a specialization of Dekker's algorithm,
in which the popping thread pre-decrements top,
and then checks it against base.
To be conservative in the face of JVMs that only partially
honor the specification for volatile, the pop proceeds
without synchronization only if there are apparently enough
items for both a simultaneous pop and take to succeed.
It otherwise enters a
synchronized lock to check if the DEQ is actually empty,
if so failing. The stealing thread
does almost the opposite, but is set up to be less likely
to win in cases of contention: Steals always run under synchronized
locks in order to avoid conflicts with other ongoing steals.
They pre-increment base, and then check against
top. They back out (resetting the base index
and failing to steal) if the
DEQ is empty or is about to become empty by an ongoing pop.
A push operation can normally run concurrently with a steal. A push enters a synch lock only if the DEQ appears full so must either be resized or have indices adjusted due to wrap-around of the bounded DEQ. The put operation always requires synchronization.
When a FJTaskRunner thread has no tasks of its own to run, it tries to be a good citizen. Threads run at lower priority while scanning for work.
If the task is currently waiting via yield, the thread alternates scans (starting at a randomly chosen victim) with Thread.yields. This is well-behaved so long as the JVM handles Thread.yield in a sensible fashion. (It need not. Thread.yield is so underspecified that it is legal for a JVM to treat it as a no-op.) This also keeps things well-behaved even if we are running on a uniprocessor JVM using a simple cooperative threading model.
If a thread needing work is is otherwise idle (which occurs only in the main runloop), and there are no available tasks to steal or poll, it instead enters into a sleep-based (actually timed wait(msec)) phase in which it progressively sleeps for longer durations (up to a maximum of FJTaskRunnerGroup.MAX_SLEEP_TIME, currently 100ms) between scans. If all threads in the group are idling, they further progress to a hard wait phase, suspending until a new task is entered into the FJTaskRunnerGroup entry queue. A sleeping FJTaskRunner thread may be awakened by a new task being put into the group entry queue or by another FJTaskRunner becoming active, but not merely by some DEQ becoming non-empty. Thus the MAX_SLEEP_TIME provides a bound for sleep durations in cases where all but one worker thread start sleeping even though there will eventually be work produced by a thread that is taking a long time to place tasks in DEQ. These sleep mechanics are handled in the FJTaskRunnerGroup class.
Composite operations such as taskJoin include heavy manual inlining of the most time-critical operations (mainly FJTask.invoke). This opens up a few opportunities for further hand-optimizations. Until Java compilers get a lot smarter, these tweaks improve performance significantly enough for task-intensive programs to be worth the poorer maintainability and code duplication.
Because they are so fragile and performance-sensitive, nearly all methods are declared as final. However, nearly all fields and methods are also declared as protected, so it is possible, with much care, to extend functionality in subclasses. (Normally you would also need to subclass FJTaskRunnerGroup.)
None of the normal java.lang.Thread class methods should ever be called on FJTaskRunners. For this reason, it might have been nicer to declare FJTaskRunner as a Runnable to run within a Thread. However, this would have complicated many minor logistics. And since no FJTaskRunner methods should normally be called from outside the FJTask and FJTaskRunnerGroup classes either, this decision doesn't impact usage.
You might think that layering this kind of framework on top of Java threads, which are already several levels removed from raw CPU scheduling on most systems, would lead to very poor performance. But on the platforms tested, the performance is quite good.
0 ... deq.length though.
The current top element is always at top & (deq.length-1).
To avoid integer overflow, top is reset down
within bounds whenever it is noticed to be out out bounds;
at worst when it is at 2 * deq.length.
This is not usually called directly but is instead inlined in callers. This version differs from the cilk algorithm in that pop does not fully back down and retry in the case of potential conflict with take. It simply rechecks under synch lock. This gives a preference for threads to run their own tasks, which seems to reduce flailing a bit when there are few tasks to run.
Since there are no good, portable alternatives, we rely here on a mixture of Thread.yield and priorities to reduce wasted spinning, even though these are not well defined. We are hoping here that the JVM does something sensible.
This differs from scan mainly in that since there is no reason to return to recheck any condition, we iterate until a task is found, backing off via sleeps if necessary.
while(!w.isDone()) taskYield();
w.fork(); invoke(v); w.join();
By intent, this class does not subclass java.lang.ThreadGroup, and does not support most methods found in ThreadGroups, since they would make no sense for FJTaskRunner threads. In fact, the class does not deal with ThreadGroups at all. If you want to restrict a FJTaskRunnerGroup to a particular ThreadGroup, you can create it from within that ThreadGroup.
The main contextual parameter for a FJTaskRunnerGroup is the group size, established in the constructor. Groups must be of a fixed size. There is no way to dynamically increase or decrease the number of threads in an existing group.
In general, the group size should be equal to the number
of CPUs on the system. (Unfortunately, there is no portable
means of automatically detecting the number of CPUs on a JVM, so there is
no good way to automate defaults.) In principle, when
FJTasks are used for computation-intensive tasks, having only
as many threads as CPUs should minimize bookkeeping overhead
and contention, and so maximize throughput. However, because
FJTaskRunners lie atop CLR threads, and in turn operating system
thread support and scheduling policies,
it is very possible that using more threads
than CPUs will improve overall throughput even though it adds
to overhead. This will always be so if FJTasks are I/O bound.
So it may pay to experiment a bit when tuning on particular platforms.
You can also use setRunPriorities to either
increase or decrease the priorities of active threads, which
may interact with group size choice.
In any case, overestimating group sizes never seriously degrades performance (at least within reasonable bounds). You can also use a value less than the number of CPUs in order to reserve processing for unrelated threads.
There are two general styles for using a FJTaskRunnerGroup. You can create one group per entire program execution, for example as a static singleton, and use it for all parallel tasks:
class Tasks {
static FJTaskRunnerGroup group;
public void initialize(int groupsize) {
group = new FJTaskRunnerGroup(groupSize);
}
// ...
}
Alternatively, you can make new groups on the fly and use them only for
particular task sets. This is more flexible,,
and leads to more controllable and deterministic execution patterns,
but it encounters greater overhead on startup. Also, to reclaim
system resources, you should
call FJTaskRunnerGroup.interruptAll when you are done
using one-shot groups. Otherwise, because FJTaskRunners set
Thread.isDaemon
status, they will not normally be reclaimed until program termination.
The main supported methods are execute,
which starts a task processed by FJTaskRunner threads,
and invoke, which starts one and waits for completion.
For example, you might extend the above FJTasks
class to support a task-based computation, say, the
Fib class from the FJTask documentation:
class Tasks { // continued
// ...
static int fib(int n) {
try {
Fib f = new Fib(n);
group.invoke(f);
return f.getAnswer();
}
catch (InterruptedException ex) {
throw new Error("Interrupted during computation");
}
}
}
Method stats() can be used to monitor performance.
Both FJTaskRunnerGroup and FJTaskRunner may be compiled with
the compile-time constant COLLECT_STATS set to false. In this
case, various simple counts reported in stats() are not collected.
On platforms tested,
this leads to such a tiny performance improvement that there is
very little motivation to bother.
This is not treated as a user-tunable parameter because good values do not appear to vary much across JVMs or applications. Its main role is to help avoid some useless spinning and contention during task startup.
The threads in a FJTaskRunnerGroup are created with their isDaemon status set, so do not normally need to be shut down manually upon program termination.
FJTask.Wrap.
Cautions: Some statistics are updated and gathered without synchronization, so may not be accurate. However, reported counts may be considered as lower bounds of actual values. Some values may be zero if classes are compiled with COLLECT_STATS set to false. (FJTaskRunner and FJTaskRunnerGroup classes can be independently compiled with different values of COLLECT_STATS.) Also, the counts are maintained as ints so could overflow in exceptionally long-lived applications.
These statistics can be useful when tuning algorithms or diagnosing problems. For example:
The main underlying reason for these mechanics is that threads do not signal each other when they add elements to their queues. (This would add to task overhead, reduce locality. and increase contention.) So we must rely on a tamed form of polling. However, tasks inserted into the entry queue do result in signals, so tasks can wait on these if all of them are otherwise idle.
public class Driver { // ...
void Main() {
CountDownLatch startSignal = new CountDownLatch(1);
CountDownLatch doneSignal = new CountDownLatch(N);
for (int i = 0; i < N; ++i)
new Thread(new ThreadStart(new Worker(startSignal, doneSignal).Run).Start();
doSomethingElse(); // don't let run yet
startSignal.CountDown(); // let all threads proceed
doSomethingElse();
doneSignal.Await(); // wait for all to finish
}
}
public class Worker : IRunnable {
private CountDownLatch startSignal;
private CountDownLatch doneSignal;
Worker(CountDownLatch startSignal, CountDownLatch doneSignal) {
this.startSignal = startSignal;
this.doneSignal = doneSignal;
}
public void Run() {
try {
startSignal.Await();
doWork();
doneSignal.CountDown();
} catch (ThreadInterruptedException ex) {} // return;
}
void doWork() { ... }
}
Another typical usage would be to divide a problem into N parts,
describe each part with a
public class Driver2 { // ...
void Main() {
CountDownLatch doneSignal = new CountDownLatch(N);
Executor e = ...
for (int i = 0; i < N; ++i) // create and start threads
e.execute(new WorkerRunnable(doneSignal, i));
doneSignal.await(); // wait for all to finish
}
}
public class WorkerRunnable : IRunnable {
private CountDownLatch doneSignal;
private int i;
WorkerRunnable(CountDownLatch doneSignal, int i) {
this.doneSignal = doneSignal;
this.i = i;
}
public void Run() {
try {
doWork(i);
doneSignal.CountDown();
} catch (ThreadInterruptedException ex) {} // return;
}
void doWork() { ... }
}
ILock l = ...;
l.Lock();
try {
// access the resource protected by this lock
} finally {
l.Unlock();
}
When locking and unlocking occur in different scopes, care must be
taken to ensure that all code that is executed while the lock is
held is protected by try-finally or try-catch to ensure that the
lock is released when necessary.
ILock lock = ...;
if (lock.TryLock()) {
try {
// manipulate protected state
} finally {
lock.Unlock();
}
} else {
// perform alternative actions
}
This usage ensures that the lock is unlocked if it was acquired, and
doesn't try to unlock if the lock was not acquired.
ILock lock = ...;
if (lock.TryLock()) {
try {
// manipulate protected state
} finally {
lock.Unlock();
}
} else {
// perform alternative actions
}
This usage ensures that the lock is unlocked if it was acquired, and
doesn't try to unlock if the lock was not acquired.
class BoundedBuffer {
final ILock lock = new ReentrantLock();
final ICondition notFull = lock.NewCondition();
final ICondition notEmpty = lock.NewCondition();
final object[] items = new object[100];
int putptr, takeptr, count;
public void Put(object x) throws InterruptedException {
lock.Lock();
try {
while (count == items.length) {
notFull.Await();
items[putptr] = x;
if (++putptr == items.length) putptr = 0;
++count;
notEmpty.Signal();
}
} finally {
lock.Unlock();
}
}
public object Take() throws InterruptedException {
lock.Lock();
try {
while (count == 0) {
notEmpty.Await();
Object x = items[takeptr];
if (++takeptr == items.length) takeptr = 0;
--count;
notFull.Signal();
return x;
} finally {
lock.unlock();
}
}
}
(The
bool aMethod(DateTime deadline) {
bool stillWaiting = true;
while (!conditionBeingWaitedFor) {
if (stillWaiting)
stillWaiting = theCondition.AwaitUntil(deadline);
else
return false;
}
// ...
}
}
Implementation Considerations
The current thread is assumed to hold the lock associated with this
if (lock.TryLock() || lock.TryLock(timespan) ) { ... }
If the write lock is held by another thread then the
current thread becomes disabled for thread scheduling
purposes and lies dormant until one of three things happens:
class X {
private ReentrantLock lock = new ReentrantLock();
// ...
public void m() {
lock.Lock(); // block until condition holds
try {
// ... method body
} finally {
lock.Unlock()
}
}
}
In addition to implementing the
if (lock.TryLock() || lock.TryLock(timeSpan) ) { ... }
If the current thread
already holds this lock then the hold count is incremented by one and
the method returns
class X {
ReentrantLock lock = new ReentrantLock();
// ...
public void m() {
Debug.Assert( lock.HoldCount() == 0 );
lock.Lock();
try {
// ... method body
} finally {
lock.Unlock();
}
}
}
class X {
ReentrantLock lock = new ReentrantLock();
// ...
public void m() {
Debug.Assert( lock.HeldByCurrentThread );
// ... method body
}
}
It can also be used to ensure that a reentrant lock is used
in a non-reentrant manner, for example:
class X {
ReentrantLock lock = new ReentrantLock();
// ...
public void m() {
Debug.Assert( !lock.HeldByCurrentThread );
lock.Lock();
try {
// ... method body
} finally {
lock.Unlock();
}
}
}
class CachedData {
object data;
volatile bool cacheValid;
ReentrantReadWriteLock rwl = new ReentrantReadWriteLock();
void processCachedData() {
rwl.ReadLock.Lock();
if (!cacheValid) {
rwl.ReadLock.Unlock();
rwl.WriteLock.Lock();
if (!cacheValid) {
data = ...
cacheValid = true;
}
// downgrade lock
rwl.ReadLock.Lock(); // reacquire read without giving up write lock
rwl.WriteLock.Unlock(); // unlock write, still hold read
}
use(data);
rwl.ReadLock.Unlock();
}
}
class RWDictionary {
private final IDictionary m = new Hashtable();
private final ReentrantReadWriteLock rwl = new ReentrantReadWriteLock();
private final Lock r = rwl.ReadLock;
private final Lock w = rwl.WriteLock;
public object Get(string key) {
r.Lock(); try { return m[key]; } finally { r.Unlock(); }
}
public ICollection AllKeys() {
r.Lock(); try { return m.Keys; } finally { r.Unlock(); }
}
public object Put(string key, object value) {
w.Lock(); try { return m.Add(key, value); } finally { w.Unlock(); }
}
public void clear() {
w.Lock(); try { m.Clear(); } finally { w.Unlock(); }
}
}
if (lock.TryLock() || lock.tryLock(timeSpan) ) { ... }
If the current thread already holds this lock then the
hold count is incremented by one and the method returns
An
To aid in efforts to use
A given channel implementation might or might not have bounded
capacity or other insertion constraints, so in general, you cannot tell if
a given put will block. However, channels that are designed to
have an element capacity (and so always block when full)
should implement the
Channels may hold any kind of item. However,
insertion of null is not in general supported. Implementations
may (all currently do) throw
By design, the
However, it is possible to determine whether an item
exists in a
When appropriate, you can define an
Also, as a compromise, even though it does not appear in interface,
implementation classes that can readily compute the number
of elements support a
All channels allow multiple producers and/or consumers.
They do not support any kind of Close method
to shut down operation or indicate completion of particular
producer or consumer threads.
If you need to signal completion, one way to do it is to
create a class such as
In time-out based methods (
Interruptions are in general handled as early as possible
in all methods. Normally,
If a put returns normally, an offer returns true, or a put or poll returns non-null, the operation completed successfully. In all other cases, the operation fails cleanly: the element is not put or taken.
Full method descriptions appear in the
Full method descriptions appear in the
true if the object has been inserted, false otherwiseThis class may be
preferable to
Also, it may be preferable to
The counts represent permits to do a put. (The queue is full when zero). Invariant: putSidePutPermits_ + takeSidePutPermits_ = capacity_ - length. (The length is never separately recorded, so this cannot be checked explicitly.)
To minimize contention between puts and takes, the put side uses up all of its permits before transfering them from the take side.
The take side just increments the count upon each take. Thus, most puts and take can run independently of each other unless the queue is empty or full.
Initial value is queue capacity.Put and take operations may throw ClassCastException if elements are not Comparable, or not comparable using the supplied comparator. Since not all elements are compared on each operation it is possible that an exception will not be thrown during insertion of non-comparable element, but will later be encountered during another insertion or extraction.
at
(and the associated crond) in Unix.
Objects of this class maintain a single thread and a task queue
that may be used to execute Runnable commands in any of three modes --
absolute (run at a given time), relative (run after a given delay),
and periodic (cyclically run with a given delay).
All commands are executed by the single background thread.
The thread is not actually started until the first
request is encountered. Also, if the
thread is stopped for any reason, one is started upon encountering
the next request, or restart() is invoked.
If you would instead like commands run in their own threads, you can use as arguments Runnable commands that start their own threads (or perhaps wrap within ThreadedExecutors).
You can also use multiple daemon objects, each using a different background thread. However, one of the reasons for using a time daemon is to pool together processing of infrequent tasks using a single background thread.
Background threads are created using a ThreadFactory. The
default factory does not
automatically setDaemon status.
The class uses Java timed waits for scheduling. These can vary in precision across platforms, and provide no real-time guarantees about meeting deadlines.
Sample Usage.
You can use a
class X { ...
ClockDaemon timer = ...
Thread readerThread;
FileInputStream datafile;
void startReadThread() {
datafile = new FileInputStream("data", ...);
readerThread = new Thread(new Runnable() {
public void run() {
for(;;) {
// try to gracefully exit before blocking
if (Thread.currentThread().isInterrupted()) {
quietlyWrapUpAndReturn();
}
else {
try {
int c = datafile.read();
if (c == -1) break;
else process(c);
}
catch (IOException ex) {
cleanup();
return;
}
}
} };
readerThread.start();
// establish callback to cancel after 60 seconds
timer.executeAfterDelay(60000, new Runnable() {
readerThread.interrupt(); // try to interrupt thread
datafile.close(); // force thread to lose its input file
});
}
}
Sample Usage. Here is one way
to update Swing components acting as progress indicators for
long-running actions.
class X {
Label statusLabel = ...;
int percentComplete = 0;
int getPercentComplete() { lock(this) { return percentComplete; } }
void setPercentComplete(int p) { lock(this) { percentComplete = p; } }
ClockDaemon cd = ...;
void startWorking() {
Runnable showPct = new Runnable() {
public void run() {
SwingUtilities.invokeLater(new Runnable() {
public void run() {
statusLabel.setText(getPercentComplete() + "%");
}
}
}
};
final Object updater = cd.executePeriodically(500, showPct, true);
Runnable action = new Runnable() {
public void run() {
for (int i = 0; i < 100; ++i) {
work();
setPercentComplete(i);
}
cd.cancel(updater);
}
};
new Thread(action).start();
}
}
period milliseconds.
Sample usage. Here are a set of classes in which a group of worker threads use a countdown to notify a driver when all threads are complete.
class Worker implements Runnable {
private final CountDown done;
Worker(CountDown d) { done = d; }
public void run() {
doWork();
done.release();
}
}
class Driver { // ...
void main() {
CountDown done = new CountDown(N);
for (int i = 0; i < N; ++i)
new Thread(new Worker(done)).start();
doSomethingElse();
done.acquire(); // wait for all to finish
}
}
if (barrier.Await() == 0) {
// log the completion of this iteration
}
The
public class Solver {
int N;
float[][] data;
CyclicBarrier barrier;
internal class Worker : IRunnable {
int myRow;
Worker(int row) { myRow = row; }
public void Run() {
while (!IsDone) {
processRow(myRow);
try {
barrier.Await();
} catch (ThreadInterruptedException ex) {
return;
} catch (BrokenBarrierException ex) {
return;
}
}
}
private void processRow(int myRow ) {
// Process row....
}
private bool IsDone { get { ..... } }
}
internal class DataMerger : IRunnable {
public void Run() {
// Merge Rows.....
}
}
public Solver(float[][] matrix) {
data = matrix;
N = matrix.length;
barrier = new CyclicBarrier(N, new DataMerger());
for (int i = 0; i < N; ++i)
new Thread(new ThreadStart(new Worker(i).Run)).Start();
WaitUntilDone();
}
}
Here, each worker thread processes a row of the matrix then waits at the
barrier until all rows have been processed. When all rows are processed
the supplied parties -- the number of threads
that must meet at the barrier point. (In all current
implementations, this
value is fixed upon construction of the Barrier.)
broken if
one or more threads leave a barrier point prematurely,
generally due to interruption or timeout. Corresponding
synchronization methods in barriers fail, throwing
BrokenBarrierException for other threads
when barriers are in broken states.
A class maintaining a single reference variable serving as the result of an operation. The result cannot be accessed until it has been set.
Sample Usage
class ImageRenderer { Image render(byte[] raw); }
class App {
Executor executor = ...
ImageRenderer renderer = ...
void display(byte[] rawimage) {
try {
FutureResult futureImage = new FutureResult();
Runnable command = futureImage.setter(new Callable() {
public Object call() { return renderer.render(rawImage); }
});
executor.execute(command);
drawBorders(); // do other things while executing
drawCaption();
drawImage((Image)(futureImage.get())); // use future
}
catch (InterruptedException ex) { return; }
catch (InvocationTargetException ex) { cleanup(); return; }
}
}
The class currently uses a standard array-based heap, as described in, for example, Sedgewick's Algorithms text. All methods are fully synchronized. In the future, it may instead use structures permitting finer-grained locking.
LayeredSyncs can be used to compose arbitrary chains by arranging that either of the managed Syncs be another LayeredSync.
true if there are no items in the queueMutex,
but, for example, a Semaphore initialized to 1 also works.
On the other hand, many other ISync implementations would not
work here, so some care is required to supply a sensible
synchronization object.
This implementation makes no attempt to provide any fairness or ordering guarantees. If you need them, consider using one of the Semaphore implementations as a locking mechanism.
Sample usage
Mutex can be useful in constructions that cannot be expressed using java synchronized blocks because the acquire/release pairs do not occur in the same method or code block. For example, you can use them for hand-over-hand locking across the nodes of a linked list. This allows extremely fine-grained locking, and so increases potential concurrency, at the cost of additional complexity and overhead that would normally make this worthwhile only in cases of extreme contention.
class Node {
Object item;
Node next;
Mutex lock = new Mutex(); // each node keeps its own lock
Node(Object x, Node n) { item = x; next = n; }
}
class List {
protected Node head; // pointer to first node of list
// Use plain java synchronization to protect head field.
// (We could instead use a Mutex here too but there is no
// reason to do so.)
protected synchronized Node getHead() { return head; }
boolean search(Object x) throws InterruptedException {
Node p = getHead();
if (p == null) return false;
// (This could be made more compact, but for clarity of illustration,
// all of the cases that can arise are handled separately.)
p.lock.acquire(); // Prime loop by acquiring first lock.
// (If the acquire fails due to
// interrupt, the method will throw
// InterruptedException now,
// so there is no need for any
// further cleanup.)
for (;;) {
if (x.equals(p.item)) {
p.lock.release(); // release current before return
return true;
}
else {
Node nextp = p.next;
if (nextp == null) {
p.lock.release(); // release final lock that was held
return false;
}
else {
try {
nextp.lock.acquire(); // get next lock before releasing current
}
catch (InterruptedException ex) {
p.lock.release(); // also release current if acquire fails
throw ex;
}
p.lock.release(); // release old lock now that new one held
p = nextp;
}
}
}
}
synchronized void add(Object x) { // simple prepend
// The use of `synchronized' here protects only head field.
// The method does not need to wait out other traversers
// who have already made it past head.
head = new Node(x, head);
}
// ... other similar traversal and update methods ...
}
Please be aware that there exists a race condition when you use
the
Thread pools can be useful for several, usually intertwined reasons:
These goals introduce a number of policy parameters that are encapsulated in this class. All of these parameters have defaults and are tunable, either via get/set methods, or, in cases where decisions should hold across lifetimes, via methods that can be easily overridden in subclasses. The main, most commonly set parameters can be established in constructors. Policy choices across these dimensions can and do interact. Be careful, and please read this documentation completely before using! See also the usage examples below.
Queueing
By default, this pool uses queueless synchronous channels to to hand off work to threads. This is a safe, conservative policy that avoids lockups when handling sets of requests that might have internal dependencies. (In these cases, queuing one task could lock up another that would be able to continue if the queued task were to run.) If you are sure that this cannot happen, then you can instead supply a queue of some sort (for example, a BoundedBuffer or LinkedQueue) in the constructor. This will cause new commands to be queued in cases where all MaximumPoolSize threads are busy. Queues are sometimes appropriate when each task is completely independent of others, so tasks cannot affect each others execution. For example, in an http server.
When given a choice, this pool always prefers adding a new thread rather than queueing if there are currently fewer than the current getMinimumPoolSize threads running, but otherwise always prefers queuing a request rather than adding a new thread. Thus, if you use an unbounded buffer, you will never have more than getMinimumPoolSize threads running. (Since the default minimumPoolSize is one, you will probably want to explicitly setMinimumPoolSize.)
While queuing can be useful in smoothing out transient bursts of requests, especially in socket-based services, it is not very well behaved when commands continue to arrive on average faster than they can be processed. Using bounds for both the queue and the pool size, along with run-when-blocked policy is often a reasonable response to such possibilities.
Queue sizes and maximum pool sizes can often be traded off for each other. Using large queues and small pools minimizes CPU usage, OS resources, and context-switching overhead, but can lead to artifically low throughput. Especially if tasks frequently block (for example if they are I/O bound), a JVM and underlying OS may be able to schedule time for more threads than you otherwise allow. Use of small queues or queueless handoffs generally requires larger pool sizes, which keeps CPUs busier but may encounter unacceptable scheduling overhead, which also decreases throughput.
Maximum Pool size
The maximum number of threads to use, when needed. The pool
does not by default preallocate threads. Instead, a thread is
created, if necessary and if there are fewer than the maximum,
only when an
Minimum Pool size
The minimum number of threads to use, when needed (default 1). When a new request is received, and fewer than the minimum number of threads are running, a new thread is always created to handle the request even if other worker threads are idly waiting for work. Otherwise, a new thread is created only if there are fewer than the maximum and the request cannot immediately be queued.
Preallocation
You can override lazy thread construction policies via
method
Keep-alive time
If the pool maintained references to a fixed set of threads in the pool, then it would impede garbage collection of otherwise idle threads. This would defeat the resource-management aspects of pools. One solution would be to use weak references. However, this would impose costly and difficult synchronization issues. Instead, threads are simply allowed to terminate and thus be GCable if they have been idle for the given keep-alive time. The value of this parameter represents a trade-off between GCability and construction time. The default keep-alive value is one minute, which means that the time needed to construct and then GC a thread is expended at most once per minute.
To establish worker threads permanently, use a negative
argument to
Blocked execution policy
If the maximum pool size or queue size is bounded, then it
is possible for incoming
Other plausible policies include raising the maximum pool size after checking with some other objects that this is OK.
These cases can never occur if the maximum pool size is unbounded
or the queue is unbounded. In these cases you instead face
potential resource exhaustion.) The execute method does not
throw any checked exceptions in any of these cases since any
errors associated with them must normally be dealt with via
handlers or callbacks. (Although in some cases, these might be
associated with throwing unchecked exceptions.) You may wish to
add special implementations even if you choose one of the listed
policies. For example, the supplied Discard policy does not
inform the caller of the drop. You could add your own version
that does so. Since choice of policies is normally a system-wide
decision, selecting a policy affects all calls to
Thread construction parameters
A settable ThreadFactory establishes each new thread. By default, it merely generates a new instance of class Thread, but can be changed to use a Thread subclass, to set priorities, ThreadLocals, etc.
Interruption policy
Worker threads check for interruption after processing each command, and terminate upon interruption. Fresh threads will replace them if needed. Thus, new tasks will not start out in an interrupted state due to an uncleared interruption in a previous task. Also, unprocessed commands are never dropped upon interruption. It would conceptually suffice simply to clear interruption between tasks, but implementation characteristics of interruption-based methods are uncertain enough to warrant this conservative strategy. It is a good idea to be equally conservative in your code for the tasks running within pools.
Shutdown policy
The interruptAll method interrupts, but does not disable the pool. Two different shutdown methods are supported for use when you do want to (permanently) stop processing tasks. Method shutdownAfterProcessingCurrentlyQueuedTasks waits until all current tasks are finished. The shutDownNow method interrupts current threads and leaves other queued requests unprocessed.
Handling requests after shutdown
When the pool is shutdown, new incoming requests are handled by the blockedExecutionHandler. By default, the handler is set to discard new requests, but this can be set with an optional argument to method shutdownAfterProcessingCurrentlyQueuedTasks.
Also, if you are using some form of queuing, you may wish to call method drain() to remove (and return) unprocessed commands from the queue after shutting down the pool and its clients. If you need to be sure these commands are processed, you can then run() each of the commands in the list returned by drain().
Usage examples.
Probably the most common use of pools is in statics or singletons accessible from a number of classes in a package; for example:
class MyPool {
// initialize to use a maximum of 8 threads.
static PooledExecutor pool = new PooledExecutor(8);
}
Here are some sample variants in initialization:
pool = new PooledExecutor(new BoundedBuffer(10), 100);
pool.MinimumPoolSize = 4;
pool = new PooledExecutor(new BoundedBuffer(10), 100);
pool.MinimumPoolSize = 4;
pool.KeepAliveTime = 1000 * 60 * 5;
pool.CreateThreads(9);
pool = new PooledExecutor(new BoundedBuffer(10), 100);
pool.MinimumPoolSize = 4;
pool.KeepAliveTime = 1000 * 60 * 5;
pool.AbortWhenBlocked();
pool.CreateThreads(9);
pool = new PooledExecutor(new LinkedQueue());
pool.KeepAliveTime = -1; // live forever
pool.CreateThreads(5);
Usage notes.
Pools do not mesh well with using thread-specific storage
via
If you need a policy not handled by the parameters in this class consider writing a subclass.
List tasks = pool.Drain();
foreach (IRunnable r in tasks)
r.Run();
The thread is not actually started until the first
execute request is encountered. Also, if the
thread is stopped for any reason (for example, after hitting
an unrecoverable exception in an executing task), one is started
upon encountering a new request, or if restart() is
invoked.
Beware that, especially in situations where command objects themselves invoke execute, queuing can sometimes lead to lockups, since commands that might allow other threads to terminate do not run at all when they are in the queue.
This class does not support any methods that reveal this queue. If you need to access it independently (for example to invoke any special status monitoring operations), you should record a reference to it separately.
If the background thread does not exist, it is created and started.
This method uses Thread.Interrupt, so relies on tasks themselves responding appropriately to interruption.
If the current tasks does not terminate on interruption, then the thread will not terminate until processing current task.
A shut down thread cannot be restarted.
Rendezvous use an all-or-none breakage model
for failed synchronization attempts: If threads
leave a rendezvous point prematurely because of timeout
or interruption, others will also leave abnormally
(via BrokenBarrierException), until
the rendezvous is restarted. This is usually
the simplest and best strategy for sharing knowledge
about failures among cooperating threads in the most
common usages contexts of Rendezvous.
While any positive number (including 1) of parties can be handled, the most common case is to have two parties.
Sample Usage
Here are the highlights of a class that uses a Rendezvous to swap buffers between threads so that the thread filling the buffer gets a freshly emptied one when it needs it, handing off the filled one to the thread emptying the buffer.
class FillAndEmpty {
Rendezvous exchanger = new Rendezvous(2);
Buffer initialEmptyBuffer = ... a made-up type
Buffer initialFullBuffer = ...
class FillingLoop implements Runnable {
public void run() {
Buffer currentBuffer = initialEmptyBuffer;
try {
while (currentBuffer != null) {
addToBuffer(currentBuffer);
if (currentBuffer.full())
currentBuffer = (Buffer)(exchanger.rendezvous(currentBuffer));
}
}
catch (BrokenBarrierException ex) {
return;
}
catch (InterruptedException ex) {
Thread.currentThread().interrupt();
}
}
}
class EmptyingLoop implements Runnable {
public void run() {
Buffer currentBuffer = initialFullBuffer;
try {
while (currentBuffer != null) {
takeFromBuffer(currentBuffer);
if (currentBuffer.empty())
currentBuffer = (Buffer)(exchanger.rendezvous(currentBuffer));
}
}
catch (BrokenBarrierException ex) {
return;
}
catch (InterruptedException ex) {
Thread.currentThread().interrupt();
}
}
}
void start() {
new Thread(new FillingLoop()).start();
new Thread(new EmptyingLoop()).start();
}
}
restart
operation left the barrier
prematurely due to interruption or time-out. (If so,
the broken status is also set.)
Also returns as
broken if the RendezvousFunction encountered a run-time exception.
Threads that are noticed to have been
interrupted after being released are not considered
to have broken the barrier.
In all cases, the interruption
status of the current thread is preserved, so can be tested
by checking Thread.interrupted.
broken status is also set.
restart
operation left the barrier
prematurely due to interruption or time-out. (If so,
the broken status is also set.)
Also returns as
broken if the RendezvousFunction encountered a run-time exception.
Threads that are noticed to have been
interrupted after being released are not considered
to have broken the barrier.
In all cases, the interruption
status of the current thread is preserved, so can be tested
by checking Thread.interrupted.
broken status is also set.
broken status is also set.
Among other applications, Slots can be convenient in token-passing designs: Here. the Slot holds a some object serving as a token, that can be obtained and returned by various threads.
Each put must wait for a take, and vice versa.
Synchronous channels are well suited for handoff designs, in which an object running in one thread must synch up with an object running in another thread in order to hand it some information, event, or task.
Note: TimedCallable will always return within the given time limit (modulo timer inaccuracies), but whether or not the worker thread stops in a timely fashion depends on the interrupt handling in the Callable function's implementation.
Its main use is to wait for object executed by an executor using a secondary thread.
While this class conforms to the full Channel interface, only the
put and poll methods are useful in most
applications. Because the queue does not support blocking
operations, take relies on spin-loops, which can be
extremely wasteful.
This class is adapted from the algorithm described in Simple, Fast, and Practical Non-Blocking and Blocking Concurrent Queue Algorithms by Maged M. Michael and Michael L. Scott. This implementation is not strictly wait-free since it relies on locking for basic atomicity and visibility requirements. Locks can impose unbounded waits, although this should not be a major practical concern here since each lock is held for the duration of only a few statements. (However, the overhead of using so many locks can make it less attractive than other Channel implementations on JVMs where locking operations are very slow.)