Overview | Package | Class | Tree | Index | Help

Oracle® Coherence Java API Reference
v3.5.3
E15583-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.tangosol.net
Interface PriorityTask

All Known Implementing Classes:
  AbstractHttpSessionCollection.ExitAgent, AbstractInvocable, AbstractPriorityTask, PortalCacheProvider.FlushAgent, PriorityAggregator, PriorityFilter, PriorityProcessor, WorkManager.AbstractWork, WorkManager.CollectMembershipInfo, WorkManager.ReleaseWork, WorkManager.RequestStatus, WorkManager.ScheduleWork, WorkManager.SendFeedback

    public interface PriorityTask

The PriorityTask interface allows to control the ordering in which a service schedules tasks for execution using a thread pool and limit their execution times to a specified duration. Instances of PriorityTask typically also implement either `Invocable` or Runnable interface.

Depending on the value returned by the `getSchedulingPriority()` method, the scheduling order will be one of the following:

- `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.

A best effort will be made to limit the task execution time according to the value returned by the `getExecutionTimeoutMillis()` method. However, it should be noted that:

- for tasks with the scheduling priority of SCHEDULE_IMMEDIATE, factors that could make the execution time longer than the timeout value are long GC pauses and high network latency;
- if the service has a task backlog (when there are more tasks scheduled for execution than the number of available worker threads), the request execution time (measured from the client's perspective) for tasks with the scheduling priorities of SCHEDULE_STANDARD or SCHEDULE_FIRST could be longer and include the time those tasks were kept in a queue before invocation;
- the corresponding service is free to cancel the task execution before the task is started and call the `runCanceled(boolean)` method if it's known that the client is no longer interested in the results of the task execution.

In addition to allowing control of the task execution (as scheduled and measured on the server side), the PriorityTask interface could also be used to control the request time from the calling thread perspective (measured on the client). A best effort will be made to limit the request time (the time period that the calling thread is blocked waiting for a response from the corresponding service) to the value returned by the `getRequestTimeoutMillis()` method.

It should be noted that the request timeout value (RT) could be grater than, equal to or less than the task execution timeout value (ET). The value of RT which is less than ET indicates that even though the task execution is allowed to take longer period of time, the client thread will not wait for a result of the execution and will be able to handle a timeout exception if it arises. Since the time spent by the task waiting in the service backlog queue does not count toward the task execution time, a value of RT that is equal or slightly greater than ET still leaves a possibility that the client thread will throw a TimeoutException before the task completes its execution normally on a server.

Since:
  Coherence 3.3
Author:
  gg 2006.11.02

Field Summary
`static int` | `SCHEDULE_FIRST` Scheduling value indicating that this task is to be queued in front of any equal or lower scheduling priority tasks and executed as soon as any of the worker threads become available.
`static int` | `SCHEDULE_IMMEDIATE` Scheduling value indicating that this task is to be immediately executed by any idle worker thread; if all of them are active, a new thread will be created to execute this task.
`static int` | `SCHEDULE_STANDARD` Scheduling value indicating that this task is to be queued and executed in a natural (based on the request arrival time) order.
`static long` | `TIMEOUT_DEFAULT` A special timeout value to indicate that the corresponding service's default timeout value should be used.
`static long` | `TIMEOUT_NONE` A special timeout value to indicate that this task or request can run indefinitely.

Method Summary
`long` | `getExecutionTimeoutMillis()` Obtain the maximum amount of time this task is allowed to run before the corresponding service will attempt to stop it.
`long` | `getRequestTimeoutMillis()` Obtain the maximum amount of time a calling thread is willing to wait for a result of the request execution.
`int` | `getSchedulingPriority()` Obtain this task's scheduling priority.
`void` | `runCanceled(boolean fAbandoned)` This method will be called if and only if all attempts to interrupt this task were unsuccesful in stopping the execution or if the execution was canceled before it had a chance to run at all.

Field Detail

### SCHEDULE_STANDARD

    static final int SCHEDULE_STANDARD

  Scheduling value indicating that this task is to be queued and executed in a natural (based on the request arrival time) order.

  See Also:
    Constant Field Values

### SCHEDULE_FIRST

    static final int SCHEDULE_FIRST

  Scheduling value indicating that this task is to be queued in front of any equal or lower scheduling priority tasks and executed as soon as any of the worker threads become available.

  See Also:
    Constant Field Values

### SCHEDULE_IMMEDIATE

    static final int SCHEDULE_IMMEDIATE

  Scheduling value indicating that this task is to be immediately executed by any idle worker thread; if all of them are active, a new thread will be created to execute this task.

  See Also:
    Constant Field Values

### TIMEOUT_DEFAULT

    static final long TIMEOUT_DEFAULT

  A special timeout value to indicate that the corresponding service's default timeout value should be used.

  See Also:
    Constant Field Values

### TIMEOUT_NONE

    static final long TIMEOUT_NONE

  A special timeout value to indicate that this task or request can run indefinitely.

  See Also:
    Constant Field Values

Method Detail

### getSchedulingPriority

    int getSchedulingPriority()

  Obtain this task's scheduling priority. Valid values are one of the SCHEDULE_* constants.

  Returns:
    this task's scheduling priority

### getExecutionTimeoutMillis

    long getExecutionTimeoutMillis()

  Obtain the maximum amount of time this task is allowed to run before the corresponding service will attempt 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 will attempt 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(boolean)` method will be called.

  Returns:
    the execution timeout value in millisecods or one of the special TIMEOUT_* values

### getRequestTimeoutMillis

    long getRequestTimeoutMillis()

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

  If the specified amount of time elapsed and the client has not received any response from the server, an `RequestTimeoutException` will be thrown to the caller.

  Returns:
    the request timeout value in milliseconds or one of the special TIMEOUT_* values

### runCanceled

    void runCanceled(boolean fAbandoned)

  This method will be called if and only if all attempts to interrupt this task were unsuccesful 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.

  Parameters:
    `fAbandoned` - true if the task has timed-out, but all attempts to interrupt it were unsuccesful in stopping the execution; otherwise the task was never started

Overview | Package | Class | Tree | Index | Help

Oracle® Coherence Java API Reference
v3.5.3
E15583-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000, 2010, Oracle. All rights reserved.