org.openide.util
Class RequestProcessor

java.lang.Object
  org.openide.util.RequestProcessor

All Implemented Interfaces:

Executor

public final class RequestProcessor
extends Object
implements Executor

Request processor is Executor (since version 7.16) capable to perform asynchronous requests in a dedicated thread pool. There are several use cases for RequestProcessor, most of them start with creating own RequestProcessor instance (which by itself is quite lightweight).

Do something later

In case you want something to be done later in some background thread, create an instance of RequestProcessor and post tasks to it.

 private static final RequestProcessor RP = new RequestProcessor("My tasks");
 // later
 RP.post(runnable, delay)
 

The above example guarantees that there is at most one runnable being processed in parallel. All your requests are serialized and processed one by one. RP works here like a simple mutex.

In case you want more tasks to run in parallel (not very often use case) you can specify higher throughput via RequestProcessor(java.lang.String, int). Then the RP works like a queue of requests passing through a semafore with predefined number of DOWN()s.

You can wait for your tasks to be processed by keeping a reference to the last one and using waitFinished():

 private static final RequestProcessor RP = new RequestProcessor("My tasks");
 private volatile RequestProcessor.Task last;

 // when posting update the task
 last = RP.post(runnable, delay)

 // later wait
 last.waitFinished()
 

Periodic task

It is also possible to do something periodically. Use the schedule method:

 class Periodic implements Runnable {
   private static final RequestProcessor RP = new RequestProcessor("My tasks");
   private final RequestProcessor.Task CLEANER = RP.create(this);
   public void run() {
     doTheWork();
     CLEANER.schedule(DELAY);
   }
 }
 

Please think twice before using such periodic background activity. It is generally considered evil if some code runs without any user action. Your code shall respect the application's state, and for example when the application is minimized, do nothing.

Sliding task

Often you want to perform an update of your object internals based on changes in some model. However your update may be costly and you want to do it just once, regardless of how many changes are reported by the model. This can be achieved with a sliding task:

 class Updater implements PropertyChangeListener, Runnable {
   private static final RequestProcessor RP = new RequestProcessor("My tasks");
   private final RequestProcessor.Task UPDATE = RP.create(this);

   public void propertyChange(PropertyChangeEvent ev) {
     UPDATE.schedule(1000);
   }

   public void run() {
     doTheWork();
   }
 }
 

The above code coaleases all events that arrive in 1s and for all of them does doTheWork just once.

Interruption of tasks

Since version 6.3 there is a conditional support for interruption of long running tasks. There always was a way to cancel not yet running task using RequestProcessor.Task.cancel() but if the task's run() method was already running, one was out of luck. Since version 6.3 the thread running the task is interrupted and the Runnable can check for that and terminate its execution sooner. In the runnable one shall check for thread interruption (done from RequestProcessor.Task.cancel()) and if true, return immediatelly as in this example:

 private static final RequestProcessor RP = new RequestProcessor("Interruptible", 1, true);
 public void run () {
     while (veryLongTimeLoop) {
       doAPieceOfIt ();

       if (Thread.interrupted ()) return;
     }
 }
 

Nested Class Summary

class

RequestProcessor.Task The task describing the request sent to the processor.

Constructor Summary

RequestProcessor()
Creates new RequestProcessor with automatically assigned unique name.

RequestProcessor(String name)
Creates a new named RequestProcessor with throughput 1.

RequestProcessor(String name, int throughput)
Creates a new named RequestProcessor with defined throughput.

RequestProcessor(String name, int throughput, boolean interruptThread)
Creates a new named RequestProcessor with defined throughput which can support interruption of the thread the processor runs in.

RequestProcessor(String name, int throughput, boolean interruptThread, boolean enableStackTraces)
Creates a new named RequestProcessor that allows to disable stack trace filling.

Method Summary

RequestProcessor.Task	create(Runnable run) Creates request that can be later started by setting its delay.
RequestProcessor.Task	create(Runnable run, boolean initiallyFinished) Creates request that can be later started by setting its delay.
static RequestProcessor.Task	createRequest(Runnable run) Deprecated. Sharing of one singlethreaded RequestProcessor among different users and posting even blocking requests is inherently deadlock-prone. See use cases.
void	execute(Runnable command) Implements contract of Executor.
static RequestProcessor	getDefault() The getter for the shared instance of the RequestProcessor.
boolean	isRequestProcessorThread() Tests if the current thread is request processor thread.
RequestProcessor.Task	post(Runnable run) This methods asks the request processor to start given runnable immediately.
RequestProcessor.Task	post(Runnable run, int timeToWait) This methods asks the request processor to start given runnable after timeToWait milliseconds.
RequestProcessor.Task	post(Runnable run, int timeToWait, int priority) This methods asks the request processor to start given runnable after timeToWait milliseconds.
static RequestProcessor.Task	postRequest(Runnable run) Deprecated. Sharing of one singlethreaded RequestProcessor among different users and posting even blocking requests is inherently deadlock-prone. See use cases.
static RequestProcessor.Task	postRequest(Runnable run, int timeToWait) Deprecated. Sharing of one singlethreaded RequestProcessor among different users and posting even blocking requests is inherently deadlock-prone. See use cases.
static RequestProcessor.Task	postRequest(Runnable run, int timeToWait, int priority) Deprecated. Sharing of one singlethreaded RequestProcessor among different users and posting even blocking requests is inherently deadlock-prone. See use cases.
void	stop() Stops processing of runnables processor.

Methods inherited from class java.lang.Object

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

Constructor Detail

RequestProcessor

public RequestProcessor()

Creates new RequestProcessor with automatically assigned unique name.

RequestProcessor

public RequestProcessor(String name)

Creates a new named RequestProcessor with throughput 1.

Parameters:

name - the name to use for the request processor thread

RequestProcessor

public RequestProcessor(String name,
                        int throughput)

Creates a new named RequestProcessor with defined throughput.

Parameters:

name - the name to use for the request processor thread

throughput - the maximal count of requests allowed to run in parallel

Since:

OpenAPI version 2.12

RequestProcessor

public RequestProcessor(String name,
                        int throughput,
                        boolean interruptThread)

Creates a new named RequestProcessor with defined throughput which can support interruption of the thread the processor runs in. There always was a way how to cancel not yet running task using RequestProcessor.Task.cancel() but if the task was already running, one was out of luck. With this constructor one can create a RequestProcessor which threads thread running tasks are interrupted and the Runnable can check for that and terminate its execution sooner. In the runnable one shall check for thread interruption (done from RequestProcessor.Task.cancel()) and if true, return immediatelly as in this example:

 public void run () {
     while (veryLongTimeLook) {
       doAPieceOfIt ();

       if (Thread.interrupted ()) return;
     }
 }
 

Parameters:

name - the name to use for the request processor thread

throughput - the maximal count of requests allowed to run in parallel

interruptThread - true if RequestProcessor.Task.cancel() shall interrupt the thread

Since:

6.3

RequestProcessor

public RequestProcessor(String name,
                        int throughput,
                        boolean interruptThread,
                        boolean enableStackTraces)

Creates a new named RequestProcessor that allows to disable stack trace filling. By default, when assertions are on, each task posted on RequestProcessor stores the stack trace at the time of posting. When an exception is later thrown from the task, it allows to print not only stack trace of the task but also stack trace of the code that posted it. However this may be a performance bottleneck in cases when hundreds of short task are scheduled. This constructor then allows to create RequestProcessor which never stores stack traces at the time of posting.

See constructor RequestProcessor(String, int, boolean) for details of interruptThread parameter.

Parameters:

name - the name to use for the request processor thread

throughput - the maximal count of requests allowed to run in parallel

interruptThread - true if RequestProcessor.Task.cancel() shall interrupt the thread

enableStackTraces - false when request processor should not fill stack traces when task is posted. Default is true when assertions are enabled, false otherwise.

Since:

7.24

Method Detail

getDefault

public static RequestProcessor getDefault()

The getter for the shared instance of the RequestProcessor. This instance is shared by anybody who needs a way of performing sporadic or repeated asynchronous work. Tasks posted to this instance may be canceled until they start their execution. If a there is a need to cancel a task while it is running a seperate request processor needs to be created via RequestProcessor(String, int, boolean) constructor.

Returns:

an instance of RequestProcessor that is capable of performing "unlimited" (currently limited to 50, just for case of misuse) number of requests in parallel.

Since:

version 2.12

See Also:

RequestProcessor(String, int, boolean), RequestProcessor.Task.cancel()

execute

public void execute(Runnable command)

Implements contract of Executor. Simply delegates to post(java.lang.Runnable).

Specified by:

execute in interface Executor

Parameters:

command - the runnable to execute

Since:

7.16

post

public RequestProcessor.Task post(Runnable run)

This methods asks the request processor to start given runnable immediately. The default priority is Thread.MIN_PRIORITY.

Parameters:

run - class to run

Returns:

the task to control the request

post

public RequestProcessor.Task post(Runnable run,
                                  int timeToWait)

This methods asks the request processor to start given runnable after timeToWait milliseconds. The default priority is Thread.MIN_PRIORITY.

Parameters:

run - class to run

timeToWait - to wait before execution

Returns:

the task to control the request

post

public RequestProcessor.Task post(Runnable run,
                                  int timeToWait,
                                  int priority)

This methods asks the request processor to start given runnable after timeToWait milliseconds. Given priority is assigned to the request.

For request relaying please consider:

    post(run, timeToWait, Thread.currentThread().getPriority());
 

Parameters:

run - class to run

timeToWait - to wait before execution

priority - the priority from Thread.MIN_PRIORITY to Thread.MAX_PRIORITY

Returns:

the task to control the request

create

public RequestProcessor.Task create(Runnable run)

Creates request that can be later started by setting its delay. The request is not immediatelly put into the queue. It is planned after setting its delay by schedule method. By default the initial state of the task is !isFinished() so doing waitFinished() will block on and wait until the task is scheduled.

Parameters:

run - action to run in the process

Returns:

the task to control execution of given action

create

public RequestProcessor.Task create(Runnable run,
                                    boolean initiallyFinished)

Creates request that can be later started by setting its delay. The request is not immediatelly put into the queue. It is planned after setting its delay by schedule method.

Parameters:

run - action to run in the process

initiallyFinished - should the task be marked initially finished? If so the RequestProcessor.Task.waitFinished() on the task will succeeded immediatelly even the task has not yet been RequestProcessor.Task.schedule(int)d.

Returns:

the task to control execution of given action

Since:

6.8

isRequestProcessorThread

public boolean isRequestProcessorThread()

Tests if the current thread is request processor thread. This method could be used to prevent the deadlocks using waitFinished method. Any two tasks created by request processor must not wait for themself.

Returns:

true if the current thread is request processor thread, otherwise false

stop

public void stop()

Stops processing of runnables processor. The currently running runnable is finished and no new is started.

postRequest

@Deprecated
public static RequestProcessor.Task postRequest(Runnable run)

Deprecated. Sharing of one singlethreaded RequestProcessor among different users and posting even blocking requests is inherently deadlock-prone. See use cases.

This methods asks the request processor to start given runnable after timeToWait milliseconds. The default priority is Thread.MIN_PRIORITY.

Parameters:

run - class to run

Returns:

the task to control the request

postRequest

@Deprecated
public static RequestProcessor.Task postRequest(Runnable run,
                                                           int timeToWait)

Deprecated. Sharing of one singlethreaded RequestProcessor among different users and posting even blocking requests is inherently deadlock-prone. See use cases.

This methods asks the request processor to start given runnable after timeToWait milliseconds. The default priority is Thread.MIN_PRIORITY.

Parameters:

run - class to run

timeToWait - to wait before execution

Returns:

the task to control the request

postRequest

@Deprecated
public static RequestProcessor.Task postRequest(Runnable run,
                                                           int timeToWait,
                                                           int priority)

Deprecated. Sharing of one singlethreaded RequestProcessor among different users and posting even blocking requests is inherently deadlock-prone. See use cases.

This methods asks the request processor to start given runnable after timeToWait milliseconds. Given priority is assigned to the request.

Parameters:

run - class to run

timeToWait - to wait before execution

priority - the priority from Thread.MIN_PRIORITY to Thread.MAX_PRIORITY

Returns:

the task to control the request

createRequest

@Deprecated
public static RequestProcessor.Task createRequest(Runnable run)

Deprecated. Sharing of one singlethreaded RequestProcessor among different users and posting even blocking requests is inherently deadlock-prone. See use cases.

Creates request that can be later started by setting its delay. The request is not immediatelly put into the queue. It is planned after setting its delay by setDelay method.

Parameters:

run - action to run in the process

Returns:

the task to control execution of given action