Java Doc for FJTaskRunnerGroup.java in  » Database-JDBC-Connection-Pool » proxool » org » logicalcobwebs » concurrent » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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 Java 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);
 }
 // ...
 }
 

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.

[ Introduction to this package. ]

See Also:   FJTask
See Also:   FJTaskRunner

This is not treated as a user-tunable parameter because good values do not appear to vary much across JVMs or applications.

• For each FJTaskRunner thread (labeled as Tn, for n from zero to group size - 1):
  • A star "*" is printed if the thread is currently active; that is, not sleeping while waiting for work.

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.

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.

• For each FJTaskRunner thread (labeled as Tn, for n from zero to group size - 1):
  • A star "*" is printed if the thread is currently active; that is, not sleeping while waiting for work. Because threads gradually enter sleep modes, an active thread may in fact be about to sleep (or wake up).
  • Q Cap The current capacity of its task queue.
  • Run The total number of tasks that have been run.
  • New The number of these tasks that were taken from either the entry queue or from other thread queues; that is, the number of tasks run that were not forked by the thread itself.
  • Scan The number of times other task queues or the entry queue were polled for tasks.
• Execute The total number of tasks entered (but not necessarily yet run) via execute or invoke.
• Time Time in seconds since construction of this FJTaskRunnerGroup.
• Rate The total number of tasks processed per second across all threads. This may be useful as a simple throughput indicator if all processed tasks take approximately the same time to run.

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:

• High numbers of scans may mean that there is insufficient parallelism to keep threads busy. However, high scan rates are expected if the number of Executes is also high or there is a lot of global synchronization in the application, and the system is not otherwise busy. Threads may scan for work hundreds of times upon startup, shutdown, and global synch points of task sets.
• Large imbalances in tasks run across different threads might just reflect contention with unrelated threads on a system (possibly including JVM threads such as GC), but may also indicate some systematic bias in how you generate tasks.
• Large task queue capacities may mean that too many tasks are being generated before they can be run. Capacities are reported rather than current numbers of tasks in queues because they are better indicators of the existence of these kinds of possibly-transient problems. Queue capacities are resized on demand from their initial value of 4096 elements, which is much more than sufficient for the kinds of applications that this framework is intended to best support.