source: box/trunk/lib/common/Timer.cpp @ 3084

// --------------------------------------------------------------------------
//
// File
//              Name:    Timer.cpp
//              Purpose: Generic timers which execute arbitrary code when
//                       they expire.
//              Created: 5/11/2006
//
// --------------------------------------------------------------------------

#include "Box.h"

#ifdef WIN32
#       ifndef _WIN32_WINNT
#               define _WIN32_WINNT 0x0500
#       elif _WIN32_WINNT < 0x0500
#               error Timers require at least Windows 2000 headers
#       endif
#endif

#include <signal.h>
#include <cstring>

#include "Timer.h"
#include "Logging.h"

#include "MemLeakFindOn.h"

std::vector<Timer*>* Timers::spTimers = NULL;
bool Timers::sRescheduleNeeded = false;

#define TIMER_ID "timer " << mName << " (" << this << ") "
#define TIMER_ID_OF(t) "timer " << (t).GetName() << " (" << &(t) << ") "

typedef void (*sighandler_t)(int);

// --------------------------------------------------------------------------
//
// Function
//              Name:    static void Timers::Init()
//              Purpose: Initialise timers, prepare signal handler
//              Created: 5/11/2006
//
// --------------------------------------------------------------------------
void Timers::Init()
{
        ASSERT(!spTimers);
        
        #if defined WIN32 && ! defined PLATFORM_CYGWIN
                // no init needed
        #else
                struct sigaction newact, oldact;
                newact.sa_handler = Timers::SignalHandler;
                newact.sa_flags = SA_RESTART;
                sigemptyset(&newact.sa_mask);
                if (::sigaction(SIGALRM, &newact, &oldact) != 0)
                {
                        BOX_ERROR("Failed to install signal handler");
                        THROW_EXCEPTION(CommonException, Internal);
                }
                ASSERT(oldact.sa_handler == 0);
        #endif // WIN32 && !PLATFORM_CYGWIN
        
        spTimers = new std::vector<Timer*>;
}

// --------------------------------------------------------------------------
//
// Function
//              Name:    static void Timers::Cleanup()
//              Purpose: Clean up timers, stop signal handler
//              Created: 6/11/2006
//
// --------------------------------------------------------------------------
void Timers::Cleanup()
{
        ASSERT(spTimers);
        if (!spTimers)
        {
                BOX_ERROR("Tried to clean up timers when not initialised!");
                return;
        }
        
        #if defined WIN32 && ! defined PLATFORM_CYGWIN
                // no cleanup needed
        #else
                struct itimerval timeout;
                memset(&timeout, 0, sizeof(timeout));

                int result = ::setitimer(ITIMER_REAL, &timeout, NULL);
                ASSERT(result == 0);

                struct sigaction newact, oldact;
                newact.sa_handler = SIG_DFL;
                newact.sa_flags = SA_RESTART;
                sigemptyset(&(newact.sa_mask));
                if (::sigaction(SIGALRM, &newact, &oldact) != 0)
                {
                        BOX_ERROR("Failed to remove signal handler");
                        THROW_EXCEPTION(CommonException, Internal);
                }
                ASSERT(oldact.sa_handler == Timers::SignalHandler);
        #endif // WIN32 && !PLATFORM_CYGWIN

        spTimers->clear();
        delete spTimers;
        spTimers = NULL;
}

// --------------------------------------------------------------------------
//
// Function
//              Name:    static void Timers::Add(Timer&)
//              Purpose: Add a new timer to the set, and reschedule next wakeup
//              Created: 5/11/2006
//
// --------------------------------------------------------------------------
void Timers::Add(Timer& rTimer)
{
        ASSERT(spTimers);
        ASSERT(&rTimer);
        spTimers->push_back(&rTimer);
        Reschedule();
}

// --------------------------------------------------------------------------
//
// Function
//              Name:    static void Timers::Remove(Timer&)
//              Purpose: Removes the timer from the set (preventing it from
//                       being called) and reschedule next wakeup
//              Created: 5/11/2006
//
// --------------------------------------------------------------------------
void Timers::Remove(Timer& rTimer)
{
        ASSERT(spTimers);
        ASSERT(&rTimer);

        bool restart = true;
        while (restart)
        {
                restart = false;

                for (std::vector<Timer*>::iterator i = spTimers->begin();
                        i != spTimers->end(); i++)
                {
                        if (&rTimer == *i)
                        {
                                spTimers->erase(i);
                                restart = true;
                                break;
                        }
                }
        }
                
        Reschedule();
}

void Timers::RequestReschedule()
{
        sRescheduleNeeded = true;
}

void Timers::RescheduleIfNeeded()
{
        if (sRescheduleNeeded) 
        {
                Reschedule();
        }
}

#define FORMAT_MICROSECONDS(t) \
        (int)(t / 1000000) << "." << \
        (int)(t % 1000000) << " seconds"

// --------------------------------------------------------------------------
//
// Function
//              Name:    static void Timers::Reschedule()
//              Purpose: Recalculate when the next wakeup is due
//              Created: 5/11/2006
//
// --------------------------------------------------------------------------
void Timers::Reschedule()
{
        ASSERT(spTimers);
        if (spTimers == NULL)
        {
                THROW_EXCEPTION(CommonException, Internal)
        }

        #ifndef WIN32
                struct sigaction oldact;
                if (::sigaction(SIGALRM, NULL, &oldact) != 0)
                {
                        BOX_ERROR("Failed to check signal handler");
                        THROW_EXCEPTION(CommonException, Internal)
                }

                ASSERT(oldact.sa_handler == Timers::SignalHandler);

                if (oldact.sa_handler != Timers::SignalHandler)
                {
                        BOX_ERROR("Signal handler was " <<
                                (void *)oldact.sa_handler << 
                                ", expected " <<
                                (void *)Timers::SignalHandler);
                        THROW_EXCEPTION(CommonException, Internal)
                }
        #endif

        // Clear the reschedule-needed flag to false before we start.
        // If a timer event occurs while we are scheduling, then we
        // may or may not need to reschedule again, but this way
        // we will do it anyway.
        sRescheduleNeeded = false;

#ifdef WIN32
        // win32 timers need no management
#else
        box_time_t timeNow = GetCurrentBoxTime();

        // scan for, trigger and remove expired timers. Removal requires
        // us to restart the scan each time, due to std::vector semantics.
        bool restart = true;
        while (restart)
        {
                restart = false;

                for (std::vector<Timer*>::iterator i = spTimers->begin();
                        i != spTimers->end(); i++)
                {
                        Timer& rTimer = **i;
                        int64_t timeToExpiry = rTimer.GetExpiryTime() - timeNow;
                
                        if (timeToExpiry <= 0)
                        {
                                /*
                                BOX_TRACE("timer " << *i << " has expired, "
                                        "triggering it");
                                */
                                BOX_TRACE(TIMER_ID_OF(**i) "has expired, "
                                        "triggering " <<
                                        FORMAT_MICROSECONDS(-timeToExpiry) <<
                                        " late");
                                rTimer.OnExpire();
                                spTimers->erase(i);
                                restart = true;
                                break;
                        }
                        else
                        {
                                /*
                                BOX_TRACE("timer " << *i << " has not "
                                        "expired, triggering in " <<
                                        FORMAT_MICROSECONDS(timeToExpiry) <<
                                        " seconds");
                                */
                        }
                }
        }

        // Now the only remaining timers should all be in the future.
        // Scan to find the next one to fire (earliest deadline).
                        
        int64_t timeToNextEvent = 0;
        std::string nameOfNextEvent;

        for (std::vector<Timer*>::iterator i = spTimers->begin();
                i != spTimers->end(); i++)
        {
                Timer& rTimer = **i;
                int64_t timeToExpiry = rTimer.GetExpiryTime() - timeNow;

                ASSERT(timeToExpiry > 0)
                if (timeToExpiry <= 0)
                {
                        timeToExpiry = 1;
                }
                
                if (timeToNextEvent == 0 || timeToNextEvent > timeToExpiry)
                {
                        timeToNextEvent = timeToExpiry;
                        nameOfNextEvent = rTimer.GetName();
                }
        }
        
        ASSERT(timeToNextEvent >= 0);

        if (timeToNextEvent == 0)
        {
                BOX_TRACE("timer: no more events, going to sleep.");
        }
        else
        {
                BOX_TRACE("timer: next event: " << nameOfNextEvent <<
                        " expires in " << FORMAT_MICROSECONDS(timeToNextEvent));
        }

        struct itimerval timeout;
        memset(&timeout, 0, sizeof(timeout));
        
        timeout.it_value.tv_sec  = BoxTimeToSeconds(timeToNextEvent);
        timeout.it_value.tv_usec = (int)
                (BoxTimeToMicroSeconds(timeToNextEvent)
                % MICRO_SEC_IN_SEC);

        if(::setitimer(ITIMER_REAL, &timeout, NULL) != 0)
        {
                BOX_ERROR("Failed to initialise system timer\n");
                THROW_EXCEPTION(CommonException, Internal)
        }
#endif
}

// --------------------------------------------------------------------------
//
// Function
//              Name:    static void Timers::SignalHandler(unused)
//              Purpose: Called as signal handler. Nothing is safe in a signal
//                       handler, not even traversing the list of timers, so
//                       just request a reschedule in future, which will do
//                       that for us, and trigger any expired timers at that
//                       time.
//              Created: 5/11/2006
//
// --------------------------------------------------------------------------
void Timers::SignalHandler(int unused)
{
        // ASSERT(spTimers);
        Timers::RequestReschedule();
}

// --------------------------------------------------------------------------
//
// Function
//              Name:    Timer::Timer(size_t timeoutMillis,
//                       const std::string& rName)
//              Purpose: Standard timer constructor, takes a timeout in
//                       seconds from now, and an optional name for
//                       logging purposes.
//              Created: 27/07/2008
//
// --------------------------------------------------------------------------

Timer::Timer(size_t timeoutMillis, const std::string& rName)
: mExpires(GetCurrentBoxTime() + MilliSecondsToBoxTime(timeoutMillis)),
  mExpired(false),
  mName(rName)
#ifdef WIN32
, mTimerHandle(INVALID_HANDLE_VALUE)
#endif
{
        #ifndef BOX_RELEASE_BUILD
        if (timeoutMillis == 0)
        {
                BOX_TRACE(TIMER_ID "initialised for " << timeoutMillis << 
                        " ms, will not fire");
        }
        else
        {
                BOX_TRACE(TIMER_ID "initialised for " << timeoutMillis <<
                        " ms, to fire at " << FormatTime(mExpires, false, true));
        }
        #endif

        if (timeoutMillis == 0)
        {
                mExpires = 0;
        }
        else
        {
                Timers::Add(*this);
                Start(timeoutMillis * 1000);
        }
}

// --------------------------------------------------------------------------
//
// Function
//              Name:    Timer::Start()
//              Purpose: This internal function initialises an OS TimerQueue
//                       timer on Windows, while on Unixes there is only a
//                       single global timer, managed by the Timers class,
//                       so this method does nothing.
//              Created: 27/07/2008
//
// --------------------------------------------------------------------------

void Timer::Start()
{
#ifdef WIN32
        box_time_t timeNow = GetCurrentBoxTime();
        int64_t timeToExpiry = mExpires - timeNow;

        if (timeToExpiry <= 0)
        {
                BOX_WARNING(TIMER_ID << "fudging expiry from -" <<
                        FORMAT_MICROSECONDS(-timeToExpiry))
                timeToExpiry = 1;
        }

        Start(timeToExpiry);
#endif
}

// --------------------------------------------------------------------------
//
// Function
//              Name:    Timer::Start(int64_t timeoutMillis)
//              Purpose: This internal function initialises an OS TimerQueue
//                       timer on Windows, with a specified delay already
//                       calculated to save us doing it again. Like
//                       Timer::Start(), on Unixes it does nothing.
//              Created: 27/07/2008
//
// --------------------------------------------------------------------------

void Timer::Start(int64_t timeoutMillis)
{
#ifdef WIN32
        // only call me once!
        ASSERT(mTimerHandle == INVALID_HANDLE_VALUE);

        // Windows XP always seems to fire timers up to 20 ms late,
        // at least on my test laptop. Not critical in practice, but our
        // tests are precise enough that they will fail if we don't
        // correct for it.
        timeoutMillis -= 20;
        
        // Set a system timer to call our timer routine
        if (CreateTimerQueueTimer(&mTimerHandle, NULL, TimerRoutine,
                (PVOID)this, timeoutMillis, 0, WT_EXECUTEINTIMERTHREAD)
                == FALSE)
        {
                BOX_ERROR(TIMER_ID "failed to create timer: " <<
                        GetErrorMessage(GetLastError()));
                mTimerHandle = INVALID_HANDLE_VALUE;
        }
#endif
}

// --------------------------------------------------------------------------
//
// Function
//              Name:    Timer::Stop()
//              Purpose: This internal function deletes the associated OS
//                       TimerQueue timer on Windows, and on Unixes does
//                       nothing.
//              Created: 27/07/2008
//
// --------------------------------------------------------------------------

void Timer::Stop()
{
#ifdef WIN32
        if (mTimerHandle != INVALID_HANDLE_VALUE)
        {
                if (DeleteTimerQueueTimer(NULL, mTimerHandle,
                        INVALID_HANDLE_VALUE) == FALSE)
                {
                        BOX_ERROR(TIMER_ID "failed to delete timer: " <<
                                GetErrorMessage(GetLastError()));
                }
                mTimerHandle = INVALID_HANDLE_VALUE;
        }
#endif
}

// --------------------------------------------------------------------------
//
// Function
//              Name:    Timer::~Timer()
//              Purpose: Destructor for Timer objects.
//              Created: 27/07/2008
//
// --------------------------------------------------------------------------

Timer::~Timer()
{
        #ifndef BOX_RELEASE_BUILD
        BOX_TRACE(TIMER_ID "destroyed");
        #endif

        Timers::Remove(*this);
        Stop();
}

// --------------------------------------------------------------------------
//
// Function
//              Name:    Timer::Timer(Timer& rToCopy)
//              Purpose: Copy constructor for Timer objects. Creates a new
//                       timer that will trigger at the same time as the
//                       original. The original will usually be discarded.
//              Created: 27/07/2008
//
// --------------------------------------------------------------------------

Timer::Timer(const Timer& rToCopy)
: mExpires(rToCopy.mExpires),
  mExpired(rToCopy.mExpired),
  mName(rToCopy.mName)
#ifdef WIN32
, mTimerHandle(INVALID_HANDLE_VALUE)
#endif
{
        #ifndef BOX_RELEASE_BUILD
        if (mExpired)
        {
                BOX_TRACE(TIMER_ID "initialised from timer " << &rToCopy << ", "
                        "already expired, will not fire");
        }
        else if (mExpires == 0)
        {
                BOX_TRACE(TIMER_ID "initialised from timer " << &rToCopy << ", "
                        "no expiry, will not fire");
        }
        else
        {
                BOX_TRACE(TIMER_ID "initialised from timer " << &rToCopy << ", "
                        "to fire at " <<
                        (int)(mExpires / MICRO_SEC_IN_SEC_LL) << "." <<
                        (int)(mExpires % MICRO_SEC_IN_SEC_LL));
        }
        #endif

        if (!mExpired && mExpires != 0)
        {
                Timers::Add(*this);
                Start();
        }
}

// --------------------------------------------------------------------------
//
// Function
//              Name:    Timer::operator=(const Timer& rToCopy)
//              Purpose: Assignment operator for Timer objects. Works
//                       exactly the same as the copy constructor, except
//                       that if the receiving timer is already running,
//                       it is stopped first.
//              Created: 27/07/2008
//
// --------------------------------------------------------------------------

Timer& Timer::operator=(const Timer& rToCopy)
{
        #ifndef BOX_RELEASE_BUILD
        if (rToCopy.mExpired)
        {
                BOX_TRACE(TIMER_ID "initialised from timer " << &rToCopy << ", "
                        "already expired, will not fire");
        }
        else if (rToCopy.mExpires == 0)
        {
                BOX_TRACE(TIMER_ID "initialised from timer " << &rToCopy << ", "
                        "no expiry, will not fire");
        }
        else
        {
                BOX_TRACE(TIMER_ID "initialised from timer " << &rToCopy << ", "
                        "to fire at " <<
                        (int)(rToCopy.mExpires / MICRO_SEC_IN_SEC_LL) << "." <<
                        (int)(rToCopy.mExpires % MICRO_SEC_IN_SEC_LL));
        }
        #endif

        Timers::Remove(*this);
        Stop();

        mExpires = rToCopy.mExpires;
        mExpired = rToCopy.mExpired;
        mName    = rToCopy.mName;

        if (!mExpired && mExpires != 0)
        {
                Timers::Add(*this);
                Start();
        }

        return *this;
}

// --------------------------------------------------------------------------
//
// Function
//              Name:    Timer::OnExpire()
//              Purpose: Method called by Timers::Reschedule (on Unixes)
//                       on next poll after timer expires, or from
//                       Timer::TimerRoutine (on Windows) from a separate
//                       thread managed by the OS. Marks the timer as
//                       expired for future reference.
//              Created: 27/07/2008
//
// --------------------------------------------------------------------------

void Timer::OnExpire()
{
        #ifndef BOX_RELEASE_BUILD
        BOX_TRACE(TIMER_ID "fired");
        #endif

        mExpired = true;
}

// --------------------------------------------------------------------------
//
// Function
//              Name:    Timer::TimerRoutine(PVOID lpParam,
//                       BOOLEAN TimerOrWaitFired)
//              Purpose: Static method called by the Windows OS when a
//                       TimerQueue timer expires.
//              Created: 27/07/2008
//
// --------------------------------------------------------------------------

#ifdef WIN32
VOID CALLBACK Timer::TimerRoutine(PVOID lpParam,
        BOOLEAN TimerOrWaitFired)
{
        Timer* pTimer = (Timer*)lpParam;
        pTimer->OnExpire();
        // is it safe to write to write debug output from a timer?
        // e.g. to write to the Event Log?
}
#endif