PriorityTask
API for custom execution processing.This chapter includes the following sections:
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. Use these features with extreme caution because they can dramatically affect 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. For example, if a write-through in a CacheStore
is blocked and exceeds the configured timeout value, the Coherence task manager attempts to interrupt the execution of the thread and an exception is thrown. In a similar fashion, queries or aggregations that exceed configured timeouts are interrupted and an exception is thrown. Applications that use this feature should ensure 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.
The <request-timeout>
, <task-timeout>
, and the <task-hung-threshold>
elements are used to configure execution timeouts for a service's worker threads. These timeout settings are configured for a service in a cache configuration file and can also be set using command line parameters. See Using the Service Guardian, for information on setting timeouts for service threads.
Table 31-1 describes the execution timeout elements.
Table 31-1 Execution Timeout Elements
Element Name | Description |
---|---|
< |
Specifies the default timeout value for requests that can time out (for example, implement the
If the value does not contain a unit, a unit of milliseconds is assumed. Legal values are positive integers or zero (indicating no default timeout). Default value is an infinite timeout ( |
< |
Specifies the default timeout value for tasks that can be timed-out (for example, entry processors that implement the |
< |
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 |
The following distributed cache example explicitly configures the service dynamic thread pool, a task time out of 5000
milliseconds, and a task hung threshold of 10000
milliseconds:
<caching-schemes> <distributed-scheme> <scheme-name>example-distributed</scheme-name> <service-name>DistributedCache</service-name> <thread-count-min>7</thread-count-min> <thread-count-max>20</thread-count-max> <task-hung-threshold>10000</task-hung-threshold> <task-timeout>5000</task-timeout> </distributed-scheme> </caching-schemes>
Setting the client request timeout to 15
milliseconds
<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 the thread-hung-threshold
or the task-timeout
.
Use the command line options to set the service type default (such as distributed cache, invocation, proxy, and so on) for the node. Table 31-2 describes the options.
Table 31-2 Command Line Options for Setting Execution Timeout
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 the task 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 is scheduled for execution in a natural (based on the request arrival time) order
SCHEDULE_FIRST
—a task is 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 is immediately executed by any idle worker thread; if all of them are active, a new thread is 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 must 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 31-3.
Table 31-3 Methods to Support Task Timeout
Method | Description |
---|---|
|
Obtains the maximum amount of time a calling thread is can 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 attempts to stop it. The value of |
|
Obtains this task's scheduling priority. Valid values are |
|
This method is 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 causes a delay of the corresponding service. |
When a task timeout occurs the node gets a RequestTimeoutException
. For example:
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)