Coherence Priority Tasks provide applications that have critical response time requirements better control of the execution of processes within Coherence. Execution and request timeouts can be configured to limit wait time for long running threads. In addition, a custom task API allows applications to control queue processing. Note that these features should be used with extreme caution because they can dramatically effect performance and throughput of the data grid.
Care should be taken when configuring Coherence Task Execution timeouts, especially for Coherence applications that pre-date this feature and thus do not handle timeout exceptions. If a write-through in a CacheStore is blocked (for example, if a database query is hung) and exceeds the configured timeout value, the Coherence Task Manager will attempt to interrupt the execution of the thread and an exception will be thrown. In a similar fashion, queries or aggregations that exceed configured timeouts will be interrupted and an exception will be thrown. Applications that use this feature should make sure that they handle these exceptions correctly to ensure system integrity. Since this configuration is performed on a service by service basis, changing these settings on existing caches/services not designed with this feature in mind should be done with great care.
When configuring Execution Timeouts these values need to be considered: request-timeout, task-timeout, and the task-hung-threshold (see "Execution Timeout Parameters"). The request-timeout is the amount of time the client will wait a request to return. The task-timeout is the amount of time that the server will allow the thread to execute before interrupting execution. The task-hung-threshold is the amount of time that a thread can execute before the server reports the thread as "hung." "Hung" threads are for reporting purposes only. These timeout settings are in milliseconds and are configured in the coherence-cache-config.xml or by using command line parameters.
Table 9-1 describes the execution timeout parameters.
Table 9-1 Execution Timeout Parameters
| Parameter Name | Description |
|---|---|
|
< |
Specifies the amount of time in milliseconds that a task can execute before it is considered "hung". Note: A posted task that has not yet started is never considered as hung. This attribute is applied only if the Thread pool is used (the |
|
< |
Specifies the default timeout value for tasks that can be timed-out (for example, implement the |
|
< |
Specifies the default timeout value for requests that can time-out (for example, implement the
|
To set the distributed cache thread count to 7 with a task time out of 5000 milliseconds and a task hung threshold of 10000 milliseconds, the following would need to be added to the coherence-cache-config.xml for the node.
Example 9-1 Sample Task Time and Task Hung Configuration
<caching-schemes>
<distributed-scheme>
<scheme-name>example-distributed</scheme-name>
<service-name>DistributedCache</service-name>
<thread-count>7</thread-count>
<task-timeout>5000ms</task-timeout>
<task-hung-threshold>10000ms</task-hung-threshold>
</distributed-scheme>
</caching-schemes>
Setting the client request timeout to 15 milliseconds
Example 9-2 Sample Client Request Timeout Configuration
<distributed-scheme>
<scheme-name>example-distributed</scheme-name>
<service-name>DistributedCache</service-name>
<request-timeout>15000ms</request-timeout>
</distributed-scheme>
Note:
The request-timeout should always be longer than thethread-hung-threshold or the task-timeout.The command line options can be used to set the service type default (such as distributed cache, invocation, proxy, and so on) for the node. Table 9-2 describes the options.
Table 9-2 Command Line Options for Setting Service Type
| Option | Description |
|---|---|
|
|
The default client request timeout for the Replicated cache service |
|
|
The default client request timeout for the Optimistic cache service |
|
|
The default client request timeout for distributed cache services |
|
|
The default server execution timeout for distributed cache services |
|
|
The default time before a thread is reported as hung by distributed cache services |
|
|
The default client request timeout for invocation services |
|
|
The default time before a thread is reported as hung by invocation services |
|
|
The default server execution timeout invocation services |
|
|
The default client request timeout for proxy services |
|
|
The default server execution timeout proxy services |
|
|
The default time before a thread is reported as hung by proxy services |
The PriorityTask interface enables you to control the ordering in which a service schedules tasks for execution using a thread pool and hold their execution time to a specified limit. Instances of PriorityTask typically also implement either the Invocable or Runnable interface. Priority Task Execution is only relevant when a task back log exists.
The API defines the following ways to schedule tasks for execution
SCHEDULE_STANDARD—a task will be scheduled for execution in a natural (based on the request arrival time) order
SCHEDULE_FIRST—a task will be scheduled in front of any equal or lower scheduling priority tasks and executed as soon as any of worker threads become available
SCHEDULE_IMMEDIATE—a task will be immediately executed by any idle worker thread; if all of them are active, a new thread will be created to execute this task
Coherence provides the following classes to help create priority task objects:
PriorityProcessor can be extended to create a custom entry processor.
PriorityFilter can be extended to create a custom priority filter.
PriorityAggregator can be extended to create a custom aggregation.
PriorityTask can be extended to create an priority invocation class.
After extending each of these classes the developer will need to implement several methods. The return values for getRequestTimeoutMillis, getExecutionTimeoutMillis, and getSchedulingPriority should be stored on a class-by-class basis in your application configuration parameters. These methods are described in Table 9-3.
Table 9-3 Methods to Support Task Timeout
| Method | Description |
|---|---|
|
|
Obtains the maximum amount of time a calling thread is willing to wait for a result of the request execution. The request time is measured on the client side as the time elapsed from the moment a request is sent for execution to the corresponding server node(s) and includes: the time it takes to deliver the request to the executing node(s); the interval between the time the task is received and placed into a service queue until the execution starts; the task execution time; the time it takes to deliver a result back to the client. The value of |
|
|
Obtains the maximum amount of time this task is allowed to run before the corresponding service will attempt to stop it. The value of |
|
|
Obtains this task's scheduling priority. Valid values are |
|
|
This method will be called if and only if all attempts to interrupt this task were unsuccessful in stopping the execution or if the execution was canceled before it had a chance to run at all. Since this method is usually called on a service thread, implementors must exercise extreme caution since any delay introduced by the implementation will cause a delay of the corresponding service. |
When a task timeout occurs the node will get a RequestTimeoutException. Example 9-3 illustrates an exception that may be thrown.
Example 9-3 Exception Thrown by a TaskTimeout
com.tangosol.net.RequestTimeoutException: Request timed out after 4015 millis
at com.tangosol.coherence.component.util.daemon.queueProcessor.Service.checkRequestTimeout(Service.CDB:8)
at com.tangosol.coherence.component.util.daemon.queueProcessor.Service.poll(Service.CDB:52)
at com.tangosol.coherence.component.util.daemon.queueProcessor.Service.poll(Service.CDB:18)
at com.tangosol.coherence.component.util.daemon.queueProcessor.service.InvocationService.query(InvocationService.CDB:17)
at com.tangosol.coherence.component.util.safeService.SafeInvocationService.query(SafeInvocationService.CDB:1)