mutex.h

Go to the documentation of this file.

/*
 * mutex.h
 *
 * Mutual exclusion thread synchonisation class.
 *
 * Portable Windows Library
 *
 * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Portable Windows Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
 * All Rights Reserved.
 *
 * Contributor(s): ______________________________________.
 */

#ifndef PTLIB_MUTEX_H
#define PTLIB_MUTEX_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <ptlib/atomic.h>
#include <ptlib/semaphor.h>


class PMutexExcessiveLockInfo
{
  protected:
    PDebugLocation m_location;
    unsigned       m_excessiveLockTimeout;
    mutable atomic<bool> m_excessiveLockActive;
    uint64_t       m_startHeldSamplePoint;

    PMutexExcessiveLockInfo();
    PMutexExcessiveLockInfo(
      const PDebugLocation & location,
      unsigned timeout
    );
    PMutexExcessiveLockInfo(const PMutexExcessiveLockInfo & other);
    virtual ~PMutexExcessiveLockInfo() { }
    void Construct(unsigned timeout);

#if PTRACING
    void Constructed(const PObject & mutex) const;
    void Destroyed(const PObject & mutex) const;
    #define PMUTEX_CONSTRUCTED() Constructed(*this)
    #define PMUTEX_DESTROYED() Destroyed(*this)
#else
    #define PMUTEX_CONSTRUCTED()
    #define PMUTEX_DESTROYED()
#endif

    void PrintOn(ostream &strm) const;
    void ExcessiveLockPhantom(const PObject & mutex) const;
    virtual void AcquiredLock(uint64_t startWaitCycle, bool readOnly, const PDebugLocation & location);
    virtual void ReleasedLock(const PObject & mutex, uint64_t startHeldSamplePoint, bool readOnly, const PDebugLocation & location);

    static unsigned MinDeadlockTime(unsigned waitTime);

  public:
    void SetLocationName(const char * name) { m_location.m_extra = name; }
};


class PTimedMutex : public PSync, public PMutexExcessiveLockInfo, PProfiling::HighWaterMark<PTimedMutex>
{
    PCLASSINFO(PTimedMutex, PSync)
  public:
    /* Create a new mutex.
       Initially the mutex will not be "set", so the first call to Wait() will
       never wait.

       The name/line parameters are used for deadlock detection debugging.
     */
    explicit PTimedMutex();
    explicit PTimedMutex(
      const PDebugLocation & location, 
      unsigned timeout = 0             
    );

    PTimedMutex(const PTimedMutex & mutex);

    PTimedMutex & operator=(const PTimedMutex &) { return *this; }

    ~PTimedMutex();

    virtual void Wait();

    virtual PBoolean Wait(
      const PTimeInterval & timeout // Amount of time to wait.
    );

    virtual void Signal();

    PINLINE bool Try() { return Wait(0); }

    virtual void PrintOn(ostream &strm) const;

    static unsigned ExcessiveLockWaitTime;
    enum DeadlockStackWalkModes
    {
        DeadlockStackWalkDisabled,
        DeadlockStackWalkEnabled,
        DeadlockStackWalkOnPhantomRelease,
        DeadlockStackWalkNoSymbols
    };
    static DeadlockStackWalkModes DeadlockStackWalkMode;
#if PTRACING
    static unsigned CtorDtorLogLevel;
#endif

  protected:
    PThreadIdentifier       m_lockerId;
    PThreadIdentifier       m_lastLockerId;
    PUniqueThreadIdentifier m_lastUniqueId;
    unsigned                m_lockCount;

    void Construct();
    void PlatformConstruct();
    bool PlatformWait(const PTimeInterval & timeout);
    void PlatformSignal(const PDebugLocation * location);
    void InternalWait(const PDebugLocation * location);
    void InternalWaitComplete(uint64_t startWaitCycle, const PDebugLocation * location);
    bool InternalSignal(const PDebugLocation * location);

// Include platform dependent part of class
#ifdef _WIN32
#include "msos/ptlib/mutex.h"
#else
#include "unix/ptlib/mutex.h"
#endif
};

typedef PTimedMutex PMutex;


#define PDECLARE_MUTEX_ARG_1(var)        struct PTimedMutex_##var : PTimedMutex { PTimedMutex_##var() : PTimedMutex(P_DEBUG_LOCATION) { } } var
#define PDECLARE_MUTEX_ARG_2(var,nam)    struct PTimedMutex_##var : PTimedMutex { PTimedMutex_##var() : PTimedMutex(#nam            ) { } } var
#define PDECLARE_MUTEX_ARG_3(var,nam,to) struct PTimedMutex_##var : PTimedMutex { PTimedMutex_##var() : PTimedMutex(#nam,to         ) { } } var

#define PDECLARE_MUTEX_PART1(narg, args) PDECLARE_MUTEX_PART2(narg, args)
#define PDECLARE_MUTEX_PART2(narg, args) PDECLARE_MUTEX_ARG_##narg args

#define PDECLARE_MUTEX(...) PDECLARE_MUTEX_PART1(PARG_COUNT(__VA_ARGS__), (__VA_ARGS__))

#if PTRACING
  class PInstrumentedMutex : PDebugLocation, public PTimedMutex
  {
    public:
      PInstrumentedMutex(
        const char * baseName,
        const char * file,
        unsigned line,
        const char * waitName,
        const char * heldName,
        unsigned waitTime,
        unsigned heldTime,
        unsigned throttleTime = 10000,    
        unsigned throttledLogLevel = 2,   
        unsigned unthrottledLogLevel = 6, 
        unsigned thresholdPercent = 5,    
        unsigned maxHistory = 0           
      ) : PDebugLocation(file, line, baseName)
        , PTimedMutex(this, MinDeadlockTime(waitTime))
        , m_timeWaitContext(PDebugLocation(file, line, waitName), waitTime, throttleTime, throttledLogLevel, unthrottledLogLevel, thresholdPercent, maxHistory)
        , m_timeHeldContext(PDebugLocation(file, line, heldName), heldTime, throttleTime, throttledLogLevel, unthrottledLogLevel, thresholdPercent, maxHistory)
      { }

      void SetWaitThrottleTime(unsigned throttleTime) { m_timeWaitContext.SetThrottleTime(throttleTime); }
      void SetWaitThrottledLogLevel(unsigned throttledLogLevel) { m_timeWaitContext.SetThrottledLogLevel(throttledLogLevel); }
      void SetWaitUnthrottledLogLevel(unsigned unthrottledLogLevel) { m_timeWaitContext.SetUnthrottledLogLevel(unthrottledLogLevel); }
      void SetWaitThresholdPercent(unsigned thresholdPercent) { m_timeWaitContext.SetThresholdPercent(thresholdPercent); }
      void SetWaitMaxHistory(unsigned maxHistory) { m_timeWaitContext.SetMaxHistory(maxHistory); }

      void SetHeldThrottleTime(unsigned throttleTime) { m_timeHeldContext.SetThrottleTime(throttleTime); }
      void SetHeldThrottledLogLevel(unsigned throttledLogLevel) { m_timeHeldContext.SetThrottledLogLevel(throttledLogLevel); }
      void SetHeldUnthrottledLogLevel(unsigned unthrottledLogLevel) { m_timeHeldContext.SetUnthrottledLogLevel(unthrottledLogLevel); }
      void SetHeldThresholdPercent(unsigned thresholdPercent) { m_timeHeldContext.SetThresholdPercent(thresholdPercent); }
      void SetHeldMaxHistory(unsigned maxHistory) { m_timeHeldContext.SetMaxHistory(maxHistory); }

      virtual bool InstrumentedWait(const PTimeInterval & timeout, const PDebugLocation & location);
      virtual void InstrumentedSignal(const PDebugLocation & location) { PlatformSignal(&location); }

    protected:
      virtual void AcquiredLock(uint64_t startWaitCycle, bool readOnly, const PDebugLocation & location);
      virtual void ReleasedLock(const PObject & mutex, uint64_t startHeldSamplePoint, bool readOnly, const PDebugLocation & location);

      PProfiling::TimeScope m_timeWaitContext;
      PProfiling::TimeScope m_timeHeldContext;
  };

  #define PDECLARE_INSTRUMENTED_MUTEX(var, name, ...)           \
    struct PInstrumentedMutex_##name : PInstrumentedMutex {     \
      PInstrumentedMutex_##name(const char * mutexName = #name) \
            : PInstrumentedMutex(mutexName, __FILE__, __LINE__, \
                                 "Wait " #name, "Held " #name,  \
                                 __VA_ARGS__) { }               \
    } var

#else
  #define PDECLARE_INSTRUMENTED_MUTEX(var, name, waitTime, heldTime, ...) \
                       PDECLARE_MUTEX(var, name, MinDeadlockTime(waitTime))
#endif


class PCriticalSection : public PSync
{
  PCLASSINFO(PCriticalSection, PSync);

  public:
    PCriticalSection();

    PCriticalSection(const PCriticalSection &);

    ~PCriticalSection();

    PCriticalSection & operator=(const PCriticalSection &) { return *this; }

    PObject * Clone() const
    {
      return new PCriticalSection();
    }

    virtual void Wait();
    inline void Enter() { Wait(); }

    virtual PBoolean Wait(
      const PTimeInterval & timeout // Amount of time to wait.
    );

    virtual void Signal();
    inline void Leave() { Signal(); }

    bool Try();

#if _WIN32
    mutable CRITICAL_SECTION criticalSection;
#elif defined(P_PTHREADS) || defined(VX_TASKS)
    mutable pthread_mutex_t m_mutex;
#endif
};


#endif // PTLIB_MUTEX_H


// End Of File ///////////////////////////////////////////////////////////////