Source: thread.h


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


#ifndef THREAD_H
#define THREAD_H


#include "system.h"
#include "synchronizable.h"


#include <pthread.h>


namespace Coral {


/**
  * This abstract class realizes threads based on Linux's pthreads. The user
  * of this class has to implement run().
  * Synchronization is implemented by inheriting Synchronizable.
  * 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   Thread
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  * @see Synchronizable
  */
class Thread : public Synchronizable
{
   // ====== Constants ======================================================
   public:
   static const cardinal ThreadCancelAsynchronous = 0;
   static const cardinal ThreadCancelDeferred     = (1 << 0);


   // ====== Constructor/Destructor =========================================
   public:
   /**
     * Constructor. A new thread will be created but *not* started!
     * To start the new thread, call start().
     *
     * @param flags  Flags for the thread to be created
     *
     * @see start
     */
   Thread(const cardinal flags = ThreadCancelAsynchronous);
   
   /**
     * Destructor. The thread will be stopped (if running) and deleted.
     */
   virtual ~Thread();


   // ====== Status =========================================================
   /**
     * Check, if the thread is running.
     *
     * @return true, if the thread is running, false otherwise
     */
   inline bool running() const;

   
   // ====== Delay ==========================================================
   /**
     * Delay execution of current thread for a given timeout.
     * This function uses nanosleep(), so no signals are affected.
     *
     * @param delayTime Timeout in microseconds.
     * @param interruptable true, if delay may be interrupted by signals; false otherwise.
     * @return Remaining delay, if interrupted; 0 otherwise.
     */
   static card64 delay(const card64 delayTimeout, const bool interruptable = false);

   
   // ====== Thread control =================================================
   /**
     * Start the thread, if not already started.
     *
     * @return true, if the thread has been started; false, if not.
     */
   virtual bool start();
   
   /**
     * Stop the thread, if not already stopped.
     * If the thread flag ThreadCancelAsynchronous is set, it will be stopped
     * immediately. If the flag ThreadCancelDeferred is set, it will be stopped
     * when a cancellation point is reached (-> see pthreads documentation).
     * testCancel() is such a cancellation point.
     *
     * @see testCancel
     */
   virtual void stop();
   
   /**
     * Wait for the thread to be finished.
     */
   cardinal join();

   /**
     * Cancel the thread.
     */
   virtual void cancel();
   
   /**
     * Suspend the thread.
     * Note: The thread will not be suspended immediately! The thread will be
     * suspended, when it reaches the next testSuspension() call!
     * => To implement suspendable threads, testSuspension() must be called by
     * the thread regularly!!!
     *
     * @see testSuspension
     */
   virtual void suspend();
   
   /**
     * Resume a suspended thread.
     */
   virtual void resume();

   
   // ====== Tests for cancellation and suspension ==========================
   protected:
   /**
     * Test for cancellation. If the thread received a cancel signal, it will
     * be cancelled.
     */
   virtual void testCancel();
   
   /**
     * Test for suspension. If the thread received a suspension signal, it will
     * be suspended.
     *
     * @return true, if the thread was suspended.
     */
   virtual bool testSuspension();
   
   /**
     * Exit current thread.
     *
     * @param result Result to return.
     */
   inline static void exit(const cardinal result = 0);

   /**
     * Voluntarily move current thread to end of queue of threads waiting for
     * CPU time (sched_yield() call). This will result in scheduling to next
     * waiting thread, if there is any.
     */
   inline static void yield();


   // ====== run() method to be implemented by subclass =====================
   protected:
   /**
     * The virtual run() method, which contains the thread's implementation.
     * It has to be implemented by classes, which inherit Thread.
     */
   virtual void run() = 0;


   // ====== Private data ===================================================
   protected:
   pthread_t       PThread;


   private:
   static void* go(void* i);

   
   private:
   pthread_mutex_t SuspensionMutex;
   cardinal        Flags;
   bool            IsSuspended;
};


}


#include "thread.icc"


#endif

Generated by: viper@odin on Sun Feb 4 18:54:51 2001, using kdoc 2.0a22.