Source: timedthread.h


Annotated List
Files
Globals
Hierarchy
Index
// ##########################################################################
// ####                                                                  ####
// ####                      RTP Audio Server Project                    ####
// ####                    ============================                  ####
// ####                                                                  ####
// #### Timed Thread                                                     ####
// ####                                                                  ####
// #### Version 1.00  --  February 23, 2001                              ####
// ####                                                                  ####
// #### Copyright (C) 1999  Thomas Dreibholz                             ####
// ####               2000  Universität Bonn, Abt. IV                    ####
// ####               2001  EMail: Dreibholz@bigfoot.com                 ####
// ####                     WWW:   http://www.bigfoot.com/~dreibholz     ####
// ####                                                                  ####
// ##########################################################################


#ifndef TIMEDTHREAD_H
#define TIMEDTHREAD_H


#include "system.h"
#include "thread.h"


#include <signal.h>


#if _NSIG <= 31
#error Your Kernel does not support more than 32 signals => SIGUSR1 reserved! Kernel update required!
#endif


namespace Coral {


/**
  * This abstract class realizes a timed thread based on Thread. The user
  * of this class has to implement timerEvent(). Inaccurate system timers
  * are corrected by calling user's timerEvent() implementation multiple
  * times if necessary. This feature can be modified by setTimerCorrection
  * (Default is on at a maximum of 10 calls).
  * IMPORTANT: Do *not* use Thread methods within async signal handlers.
  * This may cause deadlocks. See PThread's pthread_mutex_lock man-page,
  * section "Async Signal Safety" for more information!
  *
  * @short   Timed Thread
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  * @see Thread
  */

class TimedThread : public Thread
{
   // ====== Constructor/Destructor =========================================
   public:
   /**
     * Constructor. A new timed thread with a given interval will be created
     * but *not* started! To start the new thread, call start(). The
     * interval gives the time for the interval in microseconds, the virtual
     * function timerEvent() is called.
     * The default timer correction is set to 10. See setTimerCorrection() for
     * more information on timer correction.
     * The first call of timerEvent() will be made immediately, if the fast
     * start option is set (default). Otherwise it will be made after the
     * given interval.
     *
     * @param usec Interval in microseconds.
     * @param flags Thread flags
     *
     * @see Thread#start
     * @see timerEvent
     * @see Thread#Thread
     * @see setTimerCorrection
     * @see setFastStart
     */          
   TimedThread(const card64 usec, const cardinal flags = ThreadCancelAsynchronous);
   
   /**
     * Destructor.
     */
   ~TimedThread();


   // ====== Interval functions =============================================
   /**
     * Get timed thread's interval.
     *
     * @return Interval in microseconds.
     */
   inline card64 getInterval() const;
   
   /**
     * Set timed thread's interval.
     *
     * @param usec Interval in microseconds.
     */
   void setInterval(const card64 usec);

   /**
     * Get maxCorrection value for inaccurate system timer.
     *
     * @return true, if activated; false if not.
     *
     * @see setTimerCorrection
     */
   inline cardinal getTimerCorrection() const;
    
   /**
     * Set correction of inaccurate system timer to given value.
     * This on will cause the timerEvent() function to be called
     * a maximum of maxCorrection times, if the total number of calls is lower
     * than the calculated number of times the function should have been called.
     * If the number of correction calls is higher than maxCorrection,
     * *no* correction will be done!
     * Default is 0, which turns correction off.
     *
     * @param of true to activate correction; false to deactivate.
     */
   inline void setTimerCorrection(const cardinal maxCorrection = 0);

   /**
     * Leave timer correction loop: If the thread is in a timer correction
     * loop, the loop will be finished after the current timerEvent() call
     * returns.
     */
   inline void leaveCorrectionLoop();

   /**
     * Set fast start option: If false, the first call of timerEvent() will
     * be made *after* the given interval; otherwise it will be made immediately.
     * The default is true.
     *
     * @param on true, to set option; false otherwise.
     */
   inline void setFastStart(const bool on);

   /**
     * Get fast start option: If false, the first call of timerEvent() will
     * be made *after* the given interval; otherwise it will be made immediately.
     *
     * @return true, if option is set; false otherwise.
     */
   inline bool getFastStart() const;

   /**
     * Reimplementation of stop().
     */
   void stop();

   /**
     * Check for pending timer event(). This can be used to check for
     * a pending timer event() (SIGALRM signal) within the current
     * timerEvent() run.
     */
   inline bool pendingTimerEvent() const;


   // ====== timerEvent() to be implemented by subclass =====================
   protected:
   /**
     * The virtual timerEvent() method, which contains the timed thread's
     * implementation. It has to be implemented by classes, which inherit
     * TimedThread.
     * This method is called regularly with the given interval.
     */
   virtual void timerEvent() = 0;


   // ====== Private data ===================================================
   private:
   void run();


   card64   Interval;
   cardinal TimerCorrection;
   bool     AlarmHandlerInitialized;
   bool     FastStart;
   bool     NewInterval;
   bool     LeaveCorrectionLoop;
};


}


#include "timedthread.icc"


#endif

Generated by: viper@odin on Fri Feb 23 12:41:26 2001, using kdoc 2.0a36.