timer.h

Go to the documentation of this file.
00001 /*
00002  * timer.h
00003  *
00004  * Copyright (c) 2009 Thomas A. Vaughan
00005  * All rights reserved.
00006  *
00007  *
00008  * Redistribution and use in source and binary forms, with or without
00009  * modification, are permitted provided that the following conditions are met:
00010  *     * Redistributions of source code must retain the above copyright
00011  *       notice, this list of conditions and the following disclaimer.
00012  *     * Redistributions in binary form must reproduce the above copyright
00013  *       notice, this list of conditions and the following disclaimer in the
00014  *       documentation and/or other materials provided with the distribution.
00015  *     * Neither the name of the <organization> nor the
00016  *       names of its contributors may be used to endorse or promote products
00017  *       derived from this software without specific prior written permission.
00018  *
00019  * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
00020  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00021  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00022  * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
00023  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00024  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00025  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
00026  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00027  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00028  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00029  *
00030  *
00031  * Simple library for managing a timer queue.
00032  */
00033 
00034 #ifndef WAVEPACKET_TIMER_H__
00035 #define WAVEPACKET_TIMER_H__
00036 
00037 
00038 // includes --------------------------------------------------------------------
00039 #include "common/common.h"
00040 
00041 #include "geometry/geometry_3d.h"
00042 #include "threadsafe/smart_ptr.h"
00043 
00044 
00045 namespace timer {
00046 
00047 // doxygen block
00048 
00049 /// \ingroup general
00050 /*@{*/
00051 
00052 ////////////////////////////////////////////////////////////////////////////////
00053 ///
00054 /// \defgroup timer Simple Timer Queue
00055 ///
00056 ///\n
00057 /// A library for managing timers.  
00058 ///
00059 /// General usage:
00060 ///     - create a queue object
00061 ///     - repeatedly call it on checkTimers()
00062 ///     - add timers with the timer::Queue::addTimer() method
00063 ///     - as timers expire in checkTimers(), their notifyTimer() method
00064 ///             will be called.
00065 ///
00066 /// Time is specified using qword_t types (64 bit unsigned integers).  This is
00067 /// the number of microseconds since the Epoch (Jan 1 1970).  Theoretically this
00068 /// gives you microsecond-level timing for the next 584 thousand years.  In
00069 /// practice, I doubt the kernel scheduler will do much better than millisecond
00070 /// resolution.
00071 ///
00072 /// The Queue object is threadsafe.  Thread safety of individual Timer objects
00073 /// is up to the implementer.
00074 ///
00075 ////////////////////////////////////////////////////////////////////////////////
00076 /*@{*/
00077 
00078 
00079 /// base class from which you can inherit and construct your own timers
00080 class Timer {
00081 public:
00082         // virtual destructor --------------------------------------------------
00083         virtual ~Timer(void) throw();
00084 
00085         // timer::Timer class interface methods --------------------------------
00086 
00087         /// this method is called when the timer goes off
00088         virtual void notifyTimer(void) = 0;
00089 };
00090 
00091 
00092 
00093 /// this is a queue to which Timer objects can be added
00094 class Queue {
00095 public:
00096         // virtual destructor --------------------------------------------------
00097         virtual ~Queue(void) throw();
00098 
00099         // timer::Queue class interface methods --------------------------------
00100 
00101         /// add a timer which will go off in usFromNow microseconds
00102         virtual void addTimer(IN qword_t usFromNow,
00103                                 IN smart_ptr<Timer>& timer) = 0;
00104 
00105         /// update the current time of the Queue object
00106         virtual void setTime(IN qword_t usSinceEpoch) throw() = 0;
00107 
00108         /// check all timers, given the current time.  Internally, this also
00109         ///  calls setTime().  So if you call checkTimers() often you may
00110         ///  never need to call setTime() explicitly.
00111         virtual void checkTimers(IN qword_t usSinceEpoch) = 0;
00112 
00113 
00114         // static factory methods ----------------------------------------------
00115         static smart_ptr<Queue> create(void);
00116 };
00117 
00118 
00119 
00120 };      // timer namespace
00121 
00122 /*@}*/  // end of documentation block
00123 
00124 #endif  // WAVEPACKET_TIMER_H__
00125