Package generic.concurrent

Class ConcurrentQBuilder<I,R>

java.lang.Object
generic.concurrent.ConcurrentQBuilder<I,R>
Type Parameters:
I - The type of the items to be processed.
R - The type of objects resulting from processing an item
public class ConcurrentQBuilder<I,R> extends Object
A helper class to build up the potentially complicated ConcurrentQ.

Note: you must supply either a GThreadPool instance or a thread pool name. Further, if you supply the name of a thread pool, then a private, non-shared pool will be used. If you wish to make use of a shared pool, then you need to create that thread pool yourself. See GThreadPool.getSharedThreadPool(String).

Examples: 

 QCallback<I, R> callback = new AbstractQCallback<I, R>() {
     public R process(I item, TaskMonitor monitor) {
         // do work here...
     }
 };

 ConcurrentQBuilder<I, R> builder = new ConcurrentQBuilder<I, R>();
 builder.setThreadPoolName("Thread Pool Name");
 builder.setQueue(new PriorityBlockingQueue());
 concurrentQ = builder.build(callback);

 // OR, you can chain the builder calls:
 ConcurrentQBuilder<I, R> builder = new ConcurrentQBuilder<I, R>();
 queue = builder.setThreadPoolName("Thread Pool Name").
 				setQueue(new PriorityBlockingQueue()).
 				setMaxInProgress(1).
 				build(callback);

Note: if you wish to take advantage of blocking when adding items to the ConcurrentQ, see setQueue(Queue).

  • Constructor Details

    • ConcurrentQBuilder

      public ConcurrentQBuilder()

  • Method Details

    • setQueue

      public ConcurrentQBuilder<I,R> setQueue(Queue<I> queue)
      Sets the queue to be used by the ConcurrentQ. If you would like advanced features, like a queue that blocks when too many items have been placed in it, then use an advanced queue here, such as a LinkedBlockingQueue.

      Note: if you wish to take advantage of blocking when adding items to the ConcurrentQ, then be sure to call the appropriate method, such as ConcurrentQ.offer(java.util.Iterator).

      Parameters:
      queue - the queue to be used by the ConcurrentQ
      Returns:
      this builder

    • setMaxInProgress

      public ConcurrentQBuilder<I,R> setMaxInProgress(int max)
      Specifies the maximum number of items that can be process at a time. If this is set to 0, then the concurrent queue will attempt to execute as many items at a time as there are threads in the given threadPool. Setting this parameter to 1 will have the effect of guaranteeing that all times are processed one at a time in the order they were submitted. Any other positive value will run that many items concurrently, up to the number of available threads.
      Parameters:
      max - the max number of items to execute at one time; defaults to 0
      Returns:
      this builder instance

    • setThreadPoolName

      public ConcurrentQBuilder<I,R> setThreadPoolName(String name)
      Sets the name to be used when creating a private thread pool. If you wish to use a shared thread pool, then you need to create that thread pool yourself and call setThreadPool(GThreadPool).
      Parameters:
      name - the name of the thread pool.
      Returns:
      this builder instance
      See Also:

    • setThreadPool

      public ConcurrentQBuilder<I,R> setThreadPool(GThreadPool threadPool)
      Use the given thread pool for processing the work items. If you do not care to configure the thread pool used and you do not wish to make use of shared thread pools, then you can call setThreadPoolName(String) instead of this method.
      Parameters:
      threadPool - the thread pool to use
      Returns:
      this builder instance
      See Also:

    • setCollectResults

      public ConcurrentQBuilder<I,R> setCollectResults(boolean collectResults)
      Specifies if the concurrent queue should collect the results as items are processed so they can be returned in a ConcurrentQ.waitForResults() or ConcurrentQ.waitForNextResult() call.
      Parameters:
      collectResults - true signals to collect the generated results; defaults to false
      Returns:
      this builder instance

    • setJobsReportProgress

      public ConcurrentQBuilder<I,R> setJobsReportProgress(boolean reportsProgress)
      True signals that the jobs run by the client wish to report progress. The default value is false.

      The default of false is good for clients that have a known amount of work to be processed. In this case, a total count of work jobs is maintained by the queue. As items are completed, the queue will update the monitor provided to it at construction time to reflect the number of jobs completed as work is done. On the other hand, some clients have known known number of jobs to complete, but simply add work to the queue as it arrives. In that case, the client should update its monitor for progress, as the queue cannot do so in a meaningful way.

      Parameters:
      reportsProgress - true signals that the client will update progress; false signals that the queue should do so
      Returns:
      this builder instance

    • setListener

      public ConcurrentQBuilder<I,R> setListener(QItemListener<I,R> listener)

    • setMonitor

      public ConcurrentQBuilder<I,R> setMonitor(TaskMonitor monitor)

    • setCancelClearsAllJobs

      public ConcurrentQBuilder<I,R> setCancelClearsAllJobs(boolean clearAllJobs)
      Sets whether a cancel will clear all jobs (current and pending) or just the current jobs being processed. The default value is true.
      Parameters:
      clearAllJobs - if true, cancelling the monitor will cancel all items currently being processed by a thread and clear the scheduled items that haven't yet run. If false, only the items currently being processed will be cancelled.
      Returns:
      this builder
      See Also:

    • build

      public ConcurrentQ<I,R> build(QCallback<I,R> callback)
      Builds the final ConcurrentQ.
      Parameters:
      callback - the callback for processing each job
      Returns:
      the new queue