Skip Headers
Oracle® Coherence Developer's Guide
Release 3.7.1

Part Number E22837-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

29 Priority Tasks

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.

The following sections are included in this chapter:

29.1 Priority Tasks — Timeouts

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.

29.1.1 Configuring Execution Timeouts

The <request-timeout>, <task-timeout>, and the <task-hung-threshold> elements are used to configuring execution timeouts for a service's worker threads. These timeout settings are configured in a cache configuration file and can also be set using command line parameters. See Chapter 30, "Using the Service Guardian," for information on setting timeouts for service threads.

Table 29-1 describes the execution timeout elements.

Table 29-1 Execution Timeout Elements

Element Name Description

<request-timeout>

Specifies the default timeout value for requests that can time out (for example, implement the PriorityTask interface), but do not explicitly specify the request timeout value. 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 following:

  1. The time it takes to deliver the request to an executing node (server).

  2. The interval between the time the task is received and placed into a service queue until the execution starts.

  3. The task execution time.

  4. The time it takes to deliver a result back to the client.

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 (0s) for clustered client requests and 30 seconds (30s) for non-clustered client requests.

<task-timeout>

Specifies the default timeout value for tasks that can be timed-out (for example, implement the PriorityTask interface), but do not explicitly specify the task execution timeout value. The task execution time is measured on the server side and does not include the time spent waiting in a service backlog queue before being started. This attribute is applied only if the thread pool is used (the thread-count value is positive). If zero is specified, the default service-guardian <timeout-milliseconds> value is used.

<task-hung-threshold>

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 thread-count value is positive).


The following example sets a distributed cache's thread count to 7 with a task time out of 5000 milliseconds and a task hung threshold of 10000 milliseconds:

Example 29-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-hung-threshold>10000</task-hung-threshold>
      <task-timeout>5000</task-timeout>
    </distributed-scheme>
</caching-schemes>

Setting the client request timeout to 15 milliseconds

Example 29-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 the thread-hung-threshold or the task-timeout.

29.1.2 Command Line Options

Use the command line options to set the service type default (such as distributed cache, invocation, proxy, and so on) for the node. Table 29-2 describes the options.

Table 29-2 Command Line Options for Setting Service Type

Option Description

tangosol.coherence.replicated.request.timeout

The default client request timeout for the Replicated cache service

tangosol.coherence.optimistic.request.timeout

The default client request timeout for the Optimistic cache service

tangosol.coherence.distributed.request.timeout

The default client request timeout for distributed cache services

tangosol.coherence.distributed.task.timeout

The default server execution timeout for distributed cache services

tangosol.coherence.distributed.task.hung

The default time before a thread is reported as hung by distributed cache services

tangosol.coherence.invocation.request.timeout

The default client request timeout for invocation services

tangosol.coherence.invocation.task.hung

The default time before a thread is reported as hung by invocation services

tangosol.coherence.invocation.task.timeout

The default server execution timeout invocation services

tangosol.coherence.proxy.request.timeout

The default client request timeout for proxy services

tangosol.coherence.proxy.task.timeout

The default server execution timeout proxy services

tangosol.coherence.proxy.task.hung

The default time before a thread is reported as hung by proxy services


29.2 Priority Task Execution — Custom Objects

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

29.2.1 APIs for Creating Priority Task Objects

Coherence provides the following classes to help create priority task objects:

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 29-3.

Table 29-3 Methods to Support Task Timeout

Method Description

public long getRequestTimeoutMillis()

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 TIMEOUT_DEFAULT indicates a default timeout value configured for the corresponding service; the value of TIMEOUT_NONE indicates that the client thread is can wait indefinitely until the task execution completes or is canceled by the service due to a task execution timeout specified by the getExecutionTimeoutMillis() value.

public long getExecutionTimeoutMillis()

Obtains the maximum amount of time this task is allowed to run before the corresponding service attempts to stop it. The value of TIMEOUT_DEFAULT indicates a default timeout value configured for the corresponding service; the value of TIMEOUT_NONE indicates that this task can execute indefinitely. If, by the time the specified amount of time passed, the task has not finished, the service attempts to stop the execution by using the Thread.interrupt() method. In the case that interrupting the thread does not result in the task's termination, the runCanceled method is called.

public int getSchedulingPriority()

Obtains this task's scheduling priority. Valid values are SCHEDULE_STANDARD, SCHEDULE_FIRST, SCHEDULE_IMMEDIATE

public void runCanceled(boolean fAbandoned)

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.


29.2.2 Errors Thrown by Task Timeouts

When a task timeout occurs the node gets a RequestTimeoutException. Example 29-3 illustrates an exception that may be thrown.

Example 29-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)