Oracle Coherence for C++ API
Release 3.6.0.0

E15728-01

coherence/net/PriorityTask.hpp

00001 /*
00002 * PriorityTask.hpp
00003 *
00004 * Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved.
00005 *
00006 * Oracle is a registered trademarks of Oracle Corporation and/or its
00007 * affiliates.
00008 *
00009 * This software is the confidential and proprietary information of Oracle
00010 * Corporation. You shall not disclose such confidential and proprietary
00011 * information and shall use it only in accordance with the terms of the
00012 * license agreement you entered into with Oracle.
00013 *
00014 * This notice may not be removed or altered.
00015 */
00016 #ifndef COH_PRIORITY_TASK_HPP
00017 #define COH_PRIORITY_TASK_HPP
00018 
00019 #include "coherence/lang.ns"
00020 
00021 COH_OPEN_NAMESPACE2(coherence,net)
00022 
00023 
00024 /**
00025 * The PriorityTask interface allows to control the ordering in which a
00026 * service schedules tasks for execution using a thread pool and limit their
00027 * execution times to a specified duration. Instances of PriorityTask
00028 * typically also implement either PriorityTask or Runnable interface.
00029 *
00030 * Depending on the value returned by the #getSchedulingPriority()
00031 * method, the scheduling order will be one of the following:
00032 * <ul>
00033 * <li> #SCHEDULE_STANDARD - a task will be scheduled for execution in
00034 *      a natural (based on the request arrival time) order;
00035 * <li> #SCHEDULE_FIRST - a task will be scheduled in front of any
00036 *      equal or lower scheduling priority tasks and executed as soon as any
00037 *      of worker threads become available;
00038 * <li> #SCHEDULE_IMMEDIATE - a task will be immediately executed by
00039 *      any idle worker thread; if all of them are active, a new thread will
00040 *      be created to execute this task.
00041 * </ul>
00042 *
00043 * A best effort will be made to limit the task execution time according to
00044 * the value returned by the #getExecutionTimeoutMillis() method. However,
00045 * it should be noted that:
00046 * <ul>
00047 * <li> for tasks with the scheduling priority of SCHEDULE_IMMEDIATE, factors
00048 *      that could make the execution time longer than the timeout value are
00049 *      long GC pauses and high network latency;
00050 * <li> if the service has a task backlog (when there are more tasks scheduled
00051 *      for execution than the number of available worker threads), the
00052 *      request execution time (measured from the client's perspective) for
00053 *      tasks with the scheduling priorities of SCHEDULE_STANDARD or
00054 *      SCHEDULE_FIRST could be longer and include the time those tasks were
00055 *      kept in a queue before invocation;
00056 * <li> the corresponding service is free to cancel the task execution before
00057 *      the task is started and call the #runCanceled method if it's
00058 *      known that the client is no longer interested in the results of the
00059 *      task execution.
00060 * </ul>
00061 *
00062 * In addition to allowing control of the task execution (as scheduled and
00063 * measured on the server side), the PriorityTask interface could also be used
00064 * to control the request time from the calling thread perspective (measured
00065 * on the client). A best effort will be made to limit the request time (the
00066 * time period that the calling thread is blocked waiting for a response from
00067 * the corresponding service) to the value returned by the
00068 * #getRequestTimeoutMillis() method.
00069 *
00070 * It should be noted that the request timeout value (RT) could be grater
00071 * than, equal to or less than the task execution timeout value (ET). The
00072 * value of RT which is less than ET indicates that even though the task
00073 * execution is allowed to take longer period of time, the client thread will
00074 * not wait for a result of the execution and will be able to handle a timeout
00075 * exception if it arises. Since the time spent by the task waiting in the
00076 * service backlog queue does not count toward the task execution time, a
00077 * value of RT that is equal or slightly greater than ET still leaves a
00078 * possibility that the client thread will throw a TimeoutException before the
00079 * task completes its execution normally on a server.
00080 *
00081 * @author djl  2008.05.15
00082 */
00083 class COH_EXPORT PriorityTask
00084     : public interface_spec<PriorityTask>
00085     {
00086     // ----- PriorityTask interface -----------------------------------------
00087 
00088     public:
00089         /**
00090         * Obtain this task's scheduling priority. Valid values are one of the
00091         * SCHEDULE_* constants.
00092         *
00093         * @return  this task's scheduling priority
00094         */
00095         virtual int32_t getSchedulingPriority() const = 0;
00096 
00097         /**
00098         * Obtain the maximum amount of time this task is allowed to run
00099         * before the corresponding service will attempt to stop it.
00100         *
00101         * The value of #TIMEOUT_DEFAULT indicates a default
00102         * timeout value configured for the corresponding service; the value
00103         * of #TIMEOUT_NONE indicates that this task can execute indefinitely.
00104         *
00105         * If, by the time the specified amount of time passed, the task has
00106         * not finished, the service will attempt to stop the execution by
00107         * using the Thread#interrupt() method. In the case that interrupting
00108         * the thread does not result in the task's termination, the
00109         * #runCanceled method will be called.
00110         *
00111         * @return the execution timeout value in millisecods or one of the
00112         *          special TIMEOUT_* values
00113         */
00114         virtual int64_t getExecutionTimeoutMillis() const = 0;
00115 
00116         /**
00117         * Obtain the maximum amount of time a calling thread is willing to
00118         * wait for a result of the request execution. The request time is
00119         * measured on the client side as the time elapsed from the moment a
00120         * request is sent for execution to the corresponding server node(s)
00121         * and includes:
00122         * <ul>
00123         * <li> the time it takes to deliver the request to the executing
00124         *      node(s);
00125         * <li> the interval between the time the task is received and placed
00126         *      into a service queue until the execution starts;
00127         * <li> the task execution time;
00128         * <li> the time it takes to deliver a result back to the client.
00129         * </ul>
00130         *
00131         * The value of TIMEOUT_DEFAULT  indicates a default timeout value
00132         * configured for the corresponding service; the
00133         * value of #TIMEOUT_NONE TIMEOUT_NONE indicates that the client
00134         * thread is willing to wait indefinitely until the task execution
00135         * completes or is canceled by the service due to a task execution
00136         * timeout specified by the #getExecutionTimeoutMillis() value.
00137         *
00138         * If the specified amount of time elapsed and the client has not
00139         * received any response from the server, an
00140         * RequestTimeoutException will be thrown to the caller.
00141         *
00142         * @return the request timeout value in milliseconds or one of the
00143         *          special TIMEOUT_* values
00144         */
00145         virtual int64_t getRequestTimeoutMillis() const = 0;
00146 
00147         /**
00148         * This method will be called if and only if all attempts to interrupt
00149         * this task were unsuccesful in stopping the execution or if the
00150         * execution was canceled <b>before</b> it had a chance to run at all.
00151         *
00152         * Since this method is usually called on a service thread,
00153         * implementors must exercise extreme caution since any delay
00154         * introduced by the implementation will cause a delay of the
00155         * corresponding service.
00156         *
00157         * @param fAbandoned   true if the task has timed-out, but all
00158         *                     attempts to interrupt it were unsuccesful in
00159         *                     stopping the execution; otherwise the task was
00160         *                     never started
00161         */
00162         virtual void runCanceled(bool fAbandoned) = 0;
00163 
00164 
00165     // ----- constants ------------------------------------------------------
00166 
00167     public:
00168         /**
00169         * Scheduling value indicating that this task is to be queued and
00170         * executed in a natural (based on the request arrival time) order.
00171         */
00172         static const int32_t SCHEDULE_STANDARD = 0;
00173 
00174         /**
00175         * Scheduling value indicating that this task is to be queued in front
00176         * of any equal or lower scheduling priority tasks and executed as
00177         * soon as any of the worker threads become available.
00178         */
00179         static const int32_t SCHEDULE_FIRST = 1;
00180 
00181         /**
00182         * Scheduling value indicating that this task is to be immediately
00183         * executed by any idle worker thread; if all of them are active, a
00184         * new thread will be created to execute this task.
00185         */
00186         static const int32_t SCHEDULE_IMMEDIATE = 2;
00187 
00188         /**
00189         * A special timeout value to indicate that the corresponding
00190         * service's default timeout value should be used.
00191         */
00192         static const int64_t TIMEOUT_DEFAULT = 0L;
00193 
00194         /**
00195         * A special timeout value to indicate that this task or request can
00196         * run indefinitely.
00197         */
00198         static const int64_t TIMEOUT_NONE = -1L;
00199     };
00200 
00201 COH_CLOSE_NAMESPACE2
00202 
00203 #endif // COH_PRIORITY_TASK_HPP
Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.