activemq-cpp/src/main/decaf/util/Timer.h

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef _DECAF_UTIL_TIMER_H_
#define _DECAF_UTIL_TIMER_H_

#include <memory>

#include <decaf/util/Config.h>
#include <decaf/util/Date.h>
#include <decaf/util/concurrent/TimeUnit.h>
#include <decaf/lang/Pointer.h>
#include <decaf/lang/exceptions/NullPointerException.h>
#include <decaf/lang/exceptions/IllegalStateException.h>
#include <decaf/lang/exceptions/IllegalArgumentException.h>

namespace decaf {
namespace util {

    class TimerTask;
    class TimerImpl;

    /**
     * A facility for threads to schedule tasks for future execution in a background thread.
     * Tasks may be scheduled for one-time execution, or for repeated execution at regular
     * intervals.
     *
     * Corresponding to each Timer object is a single background thread that is used to execute
     * all of the timer's tasks, sequentially. Timer tasks should complete quickly. If a timer
     * task takes excessive time to complete, it "hogs" the timer's task execution thread. This
     * can, in turn, delay the execution of subsequent tasks, which may "bunch up" and execute
     * in rapid succession when (and if) the offending task finally completes.
     *
     * This class is thread-safe: multiple threads can share a single Timer object without the
     * need for external synchronization.
     *
     * This class does not offer real-time guarantees: it schedules tasks using the wait(long)
     * method.
     *
     * @since 1.0
     */
    class DECAF_API Timer {
    private:

        TimerImpl* internal;

    private:

        Timer(const Timer&);
        Timer operator=(const Timer&);

    public:

        Timer();

        /**
         * Create a new Timer whose associated thread is assigned the name given.
         *
         * @param name
         *      The name to assign to this Timer's Thread.
         */
        Timer(const std::string& name);

        virtual ~Timer();

        /**
         * Terminates this timer, discarding any currently scheduled tasks. Does not interfere with a
         * currently executing task (if it exists). Once a timer has been terminated, its execution thread
         * terminates gracefully, and no more tasks may be scheduled on it.
         *
         * Note that calling this method from within the run method of a timer task that was invoked by this
         * timer absolutely guarantees that the ongoing task execution is the last task execution that will ever
         * be performed by this timer.
         *
         * This method may be called repeatedly; the second and subsequent calls have no effect.
         */
        void cancel();

        /**
         * The caller will block until the Timer has completed termination meaning all tasks
         * that where scheduled before cancelation have now completed and the executor is ready for
         * deletion.  If the timeout period elapses before the Timer reaches the terminated
         * state then this method return false to indicate it has not terminated.
         *
         * @param timeout
         *      The amount of time to wait before abandoning the wait for termination.
         * @param unit
         *      The unit of time that the timeout value represents.
         *
         * @return true if the Timer terminated or false if the timeout expired.
         *
         * @throws InterruptedException if this call is interrupted while awaiting termination.
         */
        bool awaitTermination(long long timeout, const decaf::util::concurrent::TimeUnit& unit);

        /**
         * Removes all canceled tasks from this timer's task queue. Calling this method has no effect on the
         * behavior of the timer, but eliminates the canceled tasks from the queue causing the Timer to destroy
         * the TimerTask pointer it was originally given, the caller should ensure that they no longer have
         * any references to TimerTasks that were previously scheduled.
         *
         * Most programs will have no need to call this method. It is designed for use by the rare application
         * that cancels a large number of tasks. Calling this method trades time for space: the runtime of the
         * method may be proportional to n + c log n, where n is the number of tasks in the queue and c is the
         * number of canceled tasks.
         *
         * This method can be called on a Timer object that has no scheduled tasks without error.
         *
         * @return the number of tasks removed from the queue.
         */
        int purge();

        /**
         * Schedules the specified task for execution after the specified delay.
         *
         * The TimerTask pointer is considered to be owned by the Timer class once it has been scheduled, the
         * Timer will destroy its TimerTask's once they have been canceled or the Timer itself is canceled.
         * A TimerTask is considered scheduled only when this method return without throwing an exception, until
         * that time ownership is not considered to have been transferred to the Timer and the caller should
         * ensure that the TimerTask gets deleted if an exception is thrown and no further attempts to schedule
         * that TimerTask instance are planned.
         *
         * @param task - task to be scheduled.
         * @param delay - delay in milliseconds before task is to be executed.
         *
         * @throw NullPointerException - if the TimerTask value is Null.
         * @throw IllegalArgumentException - if delay is negative, or delay + System.currentTimeMillis() is negative.
         * @throw IllegalStateException - if task was already scheduled or canceled, or timer was canceled.
         */
        void schedule(TimerTask* task, long long delay);

        /**
         * Schedules the specified task for execution after the specified delay.
         *
         * @param task - task to be scheduled.
         * @param delay - delay in milliseconds before task is to be executed.
         *
         * @throw NullPointerException - if the TimerTask value is Null.
         * @throw IllegalArgumentException - if delay is negative, or delay + System.currentTimeMillis() is negative.
         * @throw IllegalStateException - if task was already scheduled or canceled, or timer was canceled.
         */
        void schedule(const decaf::lang::Pointer<TimerTask>& task, long long delay);

        /**
         * Schedules the specified task for execution at the specified time. If the time is in the past, the
         * task is scheduled for immediate execution.
         *
         * The TimerTask pointer is considered to be owned by the Timer class once it has been scheduled, the
         * Timer will destroy its TimerTask's once they have been canceled or the Timer itself is canceled.
         * A TimerTask is considered scheduled only when this method return without throwing an exception, until
         * that time ownership is not considered to have been transferred to the Timer and the caller should
         * ensure that the TimerTask gets deleted if an exception is thrown and no further attempts to schedule
         * that TimerTask instance are planned.
         *
         * @param task - task to be scheduled.
         * @param time - time at which task is to be executed.
         *
         * @throw NullPointerException - if the TimerTask value is Null.
         * @throw IllegalArgumentException - if time.getTime() is negative.
         * @throw IllegalStateException - if task was already scheduled or canceled, timer was canceled, or
         *                                timer thread terminated.
         */
        void schedule(TimerTask* task, const Date& time);

        /**
         * Schedules the specified task for execution at the specified time. If the time is in the past, the
         * task is scheduled for immediate execution.
         *
         * @param task - task to be scheduled.
         * @param time - time at which task is to be executed.
         *
         * @throw NullPointerException - if the TimerTask value is Null.
         * @throw IllegalArgumentException - if time.getTime() is negative.
         * @throw IllegalStateException - if task was already scheduled or canceled, timer was canceled, or
         *                                timer thread terminated.
         */
        void schedule(const decaf::lang::Pointer<TimerTask>& task, const Date& time);

        /**
         * Schedules the specified task for repeated fixed-delay execution, beginning after the specified delay.
         * Subsequent executions take place at approximately regular intervals separated by the specified period.
         *
         * The TimerTask pointer is considered to be owned by the Timer class once it has been scheduled, the
         * Timer will destroy its TimerTask's once they have been canceled or the Timer itself is canceled.
         * A TimerTask is considered scheduled only when this method return without throwing an exception, until
         * that time ownership is not considered to have been transferred to the Timer and the caller should
         * ensure that the TimerTask gets deleted if an exception is thrown and no further attempts to schedule
         * that TimerTask instance are planned.
         *
         * In fixed-delay execution, each execution is scheduled relative to the actual execution time of the
         * previous execution. If an execution is delayed for any reason (such as other background activity),
         * subsequent executions will be delayed as well. In the long run, the frequency of execution will
         * generally be slightly lower than the reciprocal of the specified period (assuming the system clock
         * underlying Object.wait(long long) is accurate).
         *
         * Fixed-delay execution is appropriate for recurring activities that require "smoothness." In other
         * words, it is appropriate for activities where it is more important to keep the frequency accurate
         * in the short run than in the long run. This includes most animation tasks, such as blinking a cursor
         * at regular intervals. It also includes tasks wherein regular activity is performed in response to
         * human input, such as automatically repeating a character as long as a key is held down.
         *
         * @param task - task to be scheduled.
         * @param delay - delay in milliseconds before task is to be executed.
         * @param period - time in milliseconds between successive task executions.
         *
         * @throw NullPointerException - if the TimerTask value is Null.
         * @throw IllegalArgumentException - if delay is negative, or delay + System.currentTimeMillis() is negative.
         * @throw IllegalStateException - if task was already scheduled or canceled, timer was canceled, or
         *                                timer thread terminated.
         */
        void schedule(TimerTask* task, long long delay, long long period);

        /**
         * Schedules the specified task for repeated fixed-delay execution, beginning after the specified delay.
         * Subsequent executions take place at approximately regular intervals separated by the specified period.
         *
         * In fixed-delay execution, each execution is scheduled relative to the actual execution time of the
         * previous execution. If an execution is delayed for any reason (such as other background activity),
         * subsequent executions will be delayed as well. In the long run, the frequency of execution will
         * generally be slightly lower than the reciprocal of the specified period (assuming the system clock
         * underlying Object.wait(long long) is accurate).
         *
         * Fixed-delay execution is appropriate for recurring activities that require "smoothness." In other
         * words, it is appropriate for activities where it is more important to keep the frequency accurate
         * in the short run than in the long run. This includes most animation tasks, such as blinking a cursor
         * at regular intervals. It also includes tasks wherein regular activity is performed in response to
         * human input, such as automatically repeating a character as long as a key is held down.
         *
         * @param task - task to be scheduled.
         * @param delay - delay in milliseconds before task is to be executed.
         * @param period - time in milliseconds between successive task executions.
         *
         * @throw NullPointerException - if the TimerTask value is Null.
         * @throw IllegalArgumentException - if delay is negative, or delay + System.currentTimeMillis() is negative.
         * @throw IllegalStateException - if task was already scheduled or canceled, timer was canceled, or
         *                                timer thread terminated.
         */
        void schedule(const decaf::lang::Pointer<TimerTask>& task, long long delay, long long period);

        /**
         * Schedules the specified task for repeated fixed-delay execution, beginning at the specified time.
         * Subsequent executions take place at approximately regular intervals separated by the specified period.
         *
         * The TimerTask pointer is considered to be owned by the Timer class once it has been scheduled, the
         * Timer will destroy its TimerTask's once they have been canceled or the Timer itself is canceled.
         * A TimerTask is considered scheduled only when this method return without throwing an exception, until
         * that time ownership is not considered to have been transferred to the Timer and the caller should
         * ensure that the TimerTask gets deleted if an exception is thrown and no further attempts to schedule
         * that TimerTask instance are planned.
         *
         * In fixed-delay execution, each execution is scheduled relative to the actual execution time of the
         * previous execution. If an execution is delayed for any reason (such as other background activity),
         * subsequent executions will be delayed as well. In the long run, the frequency of execution will
         * generally be slightly lower than the reciprocal of the specified period (assuming the system clock
         * underlying Object.wait(long long) is accurate).
         *
         * Fixed-delay execution is appropriate for recurring activities that require "smoothness." In other
         * words, it is appropriate for activities where it is more important to keep the frequency accurate
         * in the short run than in the long run. This includes most animation tasks, such as blinking a cursor
         * at regular intervals. It also includes tasks wherein regular activity is performed in response to
         * human input, such as automatically repeating a character as long as a key is held down.
         *
         * @param task - task to be scheduled.
         * @param firstTime - First time at which task is to be executed.
         * @param period - time in milliseconds between successive task executions.
         *
         * @throw NullPointerException - if the TimerTask value is Null.
         * @throw IllegalArgumentException - if time.getTime() is negative.
         * @throw IllegalStateException - if task was already scheduled or canceled, timer was canceled, or
         *                                timer thread terminated.
         */
        void schedule(TimerTask* task, const Date& firstTime, long long period);

        /**
         * Schedules the specified task for repeated fixed-delay execution, beginning at the specified time.
         * Subsequent executions take place at approximately regular intervals separated by the specified period.
         *
         * In fixed-delay execution, each execution is scheduled relative to the actual execution time of the
         * previous execution. If an execution is delayed for any reason (such as other background activity),
         * subsequent executions will be delayed as well. In the long run, the frequency of execution will
         * generally be slightly lower than the reciprocal of the specified period (assuming the system clock
         * underlying Object.wait(long long) is accurate).
         *
         * Fixed-delay execution is appropriate for recurring activities that require "smoothness." In other
         * words, it is appropriate for activities where it is more important to keep the frequency accurate
         * in the short run than in the long run. This includes most animation tasks, such as blinking a cursor
         * at regular intervals. It also includes tasks wherein regular activity is performed in response to
         * human input, such as automatically repeating a character as long as a key is held down.
         *
         * @param task - task to be scheduled.
         * @param firstTime - First time at which task is to be executed.
         * @param period - time in milliseconds between successive task executions.
         *
         * @throw NullPointerException - if the TimerTask value is Null.
         * @throw IllegalArgumentException - if time.getTime() is negative.
         * @throw IllegalStateException - if task was already scheduled or canceled, timer was canceled, or
         *                                timer thread terminated.
         */
        void schedule(const decaf::lang::Pointer<TimerTask>& task, const Date& firstTime, long long period);

        /**
         * Schedules the specified task for repeated fixed-rate execution, beginning after the specified delay.
         * Subsequent executions take place at approximately regular intervals, separated by the specified period.
         *
         * The TimerTask pointer is considered to be owned by the Timer class once it has been scheduled, the
         * Timer will destroy its TimerTask's once they have been canceled or the Timer itself is canceled.
         * A TimerTask is considered scheduled only when this method return without throwing an exception, until
         * that time ownership is not considered to have been transferred to the Timer and the caller should
         * ensure that the TimerTask gets deleted if an exception is thrown and no further attempts to schedule
         * that TimerTask instance are planned.
         *
         * In fixed-rate execution, each execution is scheduled relative to the scheduled execution time of the
         * initial execution. If an execution is delayed for any reason (such as garbage collection or other
         * background activity), two or more executions will occur in rapid succession to "catch up." In the
         * long run, the frequency of execution will be exactly the reciprocal of the specified period (assuming
         * the system clock underlying Object.wait(long) is accurate).
         *
         * Fixed-rate execution is appropriate for recurring activities that are sensitive to absolute time, such
         * as ringing a chime every hour on the hour, or running scheduled maintenance every day at a particular
         * time. It is also appropriate for recurring activities where the total time to perform a fixed number
         * of executions is important, such as a count down timer that ticks once every second for ten seconds.
         * Finally, fixed-rate execution is appropriate for scheduling multiple repeating timer tasks that must
         * remain synchronized with respect to one another.
         *
         * @param task - task to be scheduled.
         * @param delay - delay in milliseconds before task is to be executed.
         * @param period - time in milliseconds between successive task executions.
         *
         * @throw NullPointerException - if the TimerTask value is Null.
         * @throw IllegalArgumentException - if delay is negative, or delay + System.currentTimeMillis() is negative.
         * @throw IllegalStateException - if task was already scheduled or canceled, timer was canceled, or
         *                                timer thread terminated.
         */
        void scheduleAtFixedRate(TimerTask* task, long long delay, long long period);

        /**
         * Schedules the specified task for repeated fixed-rate execution, beginning after the specified delay.
         * Subsequent executions take place at approximately regular intervals, separated by the specified period.
         *
         * In fixed-rate execution, each execution is scheduled relative to the scheduled execution time of the
         * initial execution. If an execution is delayed for any reason (such as garbage collection or other
         * background activity), two or more executions will occur in rapid succession to "catch up." In the
         * long run, the frequency of execution will be exactly the reciprocal of the specified period (assuming
         * the system clock underlying Object.wait(long) is accurate).
         *
         * Fixed-rate execution is appropriate for recurring activities that are sensitive to absolute time, such
         * as ringing a chime every hour on the hour, or running scheduled maintenance every day at a particular
         * time. It is also appropriate for recurring activities where the total time to perform a fixed number
         * of executions is important, such as a countdown timer that ticks once every second for ten seconds.
         * Finally, fixed-rate execution is appropriate for scheduling multiple repeating timer tasks that must
         * remain synchronized with respect to one another.
         *
         * @param task - task to be scheduled.
         * @param delay - delay in milliseconds before task is to be executed.
         * @param period - time in milliseconds between successive task executions.
         *
         * @throw NullPointerException - if the TimerTask value is Null.
         * @throw IllegalArgumentException - if delay is negative, or delay + System.currentTimeMillis() is negative.
         * @throw IllegalStateException - if task was already scheduled or canceled, timer was canceled, or
         *                                timer thread terminated.
         */
        void scheduleAtFixedRate(const decaf::lang::Pointer<TimerTask>& task, long long delay, long long period);

        /**
         * Schedules the specified task for repeated fixed-rate execution, beginning at the specified time.
         * Subsequent executions take place at approximately regular intervals, separated by the specified period.
         *
         * The TimerTask pointer is considered to be owned by the Timer class once it has been scheduled, the
         * Timer will destroy its TimerTask's once they have been canceled or the Timer itself is canceled.
         * A TimerTask is considered scheduled only when this method return without throwing an exception, until
         * that time ownership is not considered to have been transferred to the Timer and the caller should
         * ensure that the TimerTask gets deleted if an exception is thrown and no further attempts to schedule
         * that TimerTask instance are planned.
         *
         * In fixed-rate execution, each execution is scheduled relative to the scheduled execution time of the
         * initial execution. If an execution is delayed for any reason (such as garbage collection or other
         * background activity), two or more executions will occur in rapid succession to "catch up." In the
         * long run, the frequency of execution will be exactly the reciprocal of the specified period (assuming
         * the system clock underlying Object.wait(long) is accurate).
         *
         * Fixed-rate execution is appropriate for recurring activities that are sensitive to absolute time, such
         * as ringing a chime every hour on the hour, or running scheduled maintenance every day at a particular
         * time. It is also appropriate for recurring activities where the total time to perform a fixed number
         * of executions is important, such as a countdown timer that ticks once every second for ten seconds.
         * Finally, fixed-rate execution is appropriate for scheduling multiple repeating timer tasks that must
         * remain synchronized with respect to one another.
         *
         * @param task - task to be scheduled.
         * @param firstTime - First time at which task is to be executed.
         * @param period - time in milliseconds between successive task executions.
         *
         * @throw NullPointerException - if the TimerTask value is Null.
         * @throw IllegalArgumentException - if time.getTime() is negative.
         * @throw IllegalStateException - if task was already scheduled or canceled, timer was canceled, or
         *                                timer thread terminated.
         */
        void scheduleAtFixedRate(TimerTask* task, const Date& firstTime, long long period);

        /**
         * Schedules the specified task for repeated fixed-rate execution, beginning at the specified time.
         * Subsequent executions take place at approximately regular intervals, separated by the specified period.
         *
         * In fixed-rate execution, each execution is scheduled relative to the scheduled execution time of the
         * initial execution. If an execution is delayed for any reason (such as garbage collection or other
         * background activity), two or more executions will occur in rapid succession to "catch up." In the
         * long run, the frequency of execution will be exactly the reciprocal of the specified period (assuming
         * the system clock underlying Object.wait(long) is accurate).
         *
         * Fixed-rate execution is appropriate for recurring activities that are sensitive to absolute time, such
         * as ringing a chime every hour on the hour, or running scheduled maintenance every day at a particular
         * time. It is also appropriate for recurring activities where the total time to perform a fixed number
         * of executions is important, such as a countdown timer that ticks once every second for ten seconds.
         * Finally, fixed-rate execution is appropriate for scheduling multiple repeating timer tasks that must
         * remain synchronized with respect to one another.
         *
         * @param task - task to be scheduled.
         * @param firstTime - First time at which task is to be executed.
         * @param period - time in milliseconds between successive task executions.
         *
         * @throw NullPointerException - if the TimerTask value is Null.
         * @throw IllegalArgumentException - if time.getTime() is negative.
         * @throw IllegalStateException - if task was already scheduled or canceled, timer was canceled, or
         *                                timer thread terminated.
         */
        void scheduleAtFixedRate(const decaf::lang::Pointer<TimerTask>& task, const Date& firstTime, long long period);

    private:

        void scheduleTask(const decaf::lang::Pointer<TimerTask>& task, long long delay, long long period, bool fixed);

    };

}}

#endif /* _DECAF_UTIL_TIMER_H_ */