Source: synchronizable.h


Annotated List
Files
Globals
Hierarchy
Index
// ##########################################################################
// ####                                                                  ####
// ####                      RTP Audio Server Project                    ####
// ####                    ============================                  ####
// ####                                                                  ####
// #### Synchronizable                                                   ####
// ####                                                                  ####
// #### 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 SYNCHRONIZABLE_H
#define SYNCHRONIZABLE_H


#include "system.h"


#include <pthread.h>


namespace Coral {


// Debug mode: Print all synchronized/unsynchronized calls with file name
//             and line number using macros synchronized() and unsynchronized()
//             to call debug functions.
// #define SYNC_DEBUG


/**
  * This class realizes synchronized access to a thread's data by other threads.
  * Synchronization is done by using a global pthread mutex and obtaining
  * access to this mutex by synchronized() for synchronized access and releasing
  * this mutex for unsynchronized access.
  * IMPORTANT: Do *not* use synchronized()/unsynchronized() within async signal
  * handlers. This may cause deadlocks. See PThread's pthread_mutex_lock man-page,
  * section "Async Signal Safety" for more information!
  *
  * @short   Synchronizable
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  * @see Thread
  */
class Synchronizable
{
   // ====== Constructor/Destructor =========================================
   public:
   /**
     * Constructor
     */
   Synchronizable();
   
   /**
     * Destructor
     */
   ~Synchronizable();

   
   // ====== Synchronization ================================================
   /**
     * synchronized() begins a synchronized block. The block has to be
     * finished by unsynchronized(). synchronized() will wait until the mutex
     * is available.
     *
     * @see unsynchronized
     * @see synchronizedTry
     */
   inline void synchronized();

   /**
     * synchronizedTry() tries to begins a synchronized block. It does the same
     * as synchronized(), but returns immediately, if the mutex is obtained by
     * another thread.
     *
     * @see synchronized
     * @see unsynchronized
     */
   inline bool synchronizedTry();
   
   /**
     * unsynchronized() ends a synchronized block, which has begun by
     * synchronized().
     *
     * @see synchronized
     */
   inline void unsynchronized();


   /**
     * Do reinitialization of Synchronizable.
     */
   void resynchronize();


   // ====== Debug functions ================================================
   /**
     * Debug version of synchronized. This will print PID, file name
     * and line number, followed by debug information.
     *
     * @param file File name.
     * @param line Line number.
     *
     * @see synchronized
     */
   void synchronized_debug(const char* file, const cardinal line);

   /**
     * Debug version of unsynchronized. This will print PID, file name
     * and line number, followed by debug information.
     *
     * @param file File name.
     * @param line Line number.
     *
     * @see unsynchronized
     */
   void unsynchronized_debug(const char* file, const cardinal line);

   /**
     * Debug version of synchronizedTry. This will print PID, file name
     * and line number, followed by debug information.
     *
     * @param file File name.
     * @param line Line number.
     *
     * @see synchronizedTry
     */
   bool synchronizedTry_debug(const char* file, const cardinal line);

   /**
     * Debug version of resynchronize. This will print PID, file name
     * and line number, followed by debug information.
     *
     * @param file File name.
     * @param line Line number.
     *
     * @see resynchronize
     */
   void resynchronize_debug(const char* file, const cardinal line);


   // ====== Private data ===================================================
   private:
   pthread_mutex_t Mutex;    
};


}


#include "synchronizable.icc"


#ifdef SYNC_DEBUG
#define synchronized()    synchronized_debug(__FILE__,__LINE__)
#define unsynchronized()  unsynchronized_debug(__FILE__,__LINE__)
#define synchronizedTry() synchronizedTry_debug(__FILE__,__LINE__)
#define resynchronize()   resynchronize_debug(__FILE__,__LINE__)
#endif


#endif

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