thread.h

Go to the documentation of this file.

/*
 * thread.h
 *
 * Executable thread encapsulation class (pre-emptive if OS allows).
 *
 * Portable Tools 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_THREAD_H
#define PTLIB_THREAD_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#ifdef Priority
#undef Priority
#endif

#include <ptlib/mutex.h>
#include <ptlib/notifier.h>
#include <set>


class PSemaphore;
class PSyncPoint;


// PThread

class PThread : public PObject, PProfiling::HighWaterMark<PThread>
{
  PCLASSINFO(PThread, PObject);

  public:
    P_DECLARE_TRACED_ENUM(Priority,
      LowestPriority,  
      LowPriority,     
      NormalPriority,  
      HighPriority,    
      HighestPriority  
    );

    enum AutoDeleteFlag {
      AutoDeleteThread,   

      NoAutoDeleteThread  
    };

    PThread(
      PINDEX stack,  
      AutoDeleteFlag deletion = AutoDeleteThread,
      Priority priorityLevel = NormalPriority,  
      const PString & threadName = PString::Empty() 
    );

    ~PThread();

    void PrintOn(
      ostream & strm    
    ) const;

    virtual void Restart();

    virtual void Terminate();

    virtual PBoolean IsTerminated() const;

    void WaitForTermination() const;

    PBoolean WaitForTermination(
      const PTimeInterval & maxWait  
    ) const;

    static bool WaitAndDelete(
      PThread * & thread,                    
      const PTimeInterval & maxWait = 10000, 
      PMutex * mutex = NULL,                 
      bool lock = true                       
    );

    virtual void Suspend(
      PBoolean susp = true    
    );

    virtual void Resume();

    virtual PBoolean IsSuspended() const;

    static void Sleep(
      const PTimeInterval & delay   
    );

    virtual void SetPriority(
      Priority priorityLevel    
    );

    virtual Priority GetPriority() const;

    virtual void SetAutoDelete(
      AutoDeleteFlag deletion = AutoDeleteThread  
    );

    void SetNoAutoDelete() { SetAutoDelete(NoAutoDeleteThread); }

    virtual PString GetThreadName() const;

    static PString GetThreadName(PThreadIdentifier id);

    static PString GetCurrentThreadName() { return GetThreadName(GetCurrentThreadId()); }

    static PString GetIdentifiersAsString(PThreadIdentifier tid, PUniqueThreadIdentifier uid);

    virtual void SetThreadName(
      const PString & name        
    );

    PPROFILE_EXCLUDE(
      PThreadIdentifier GetThreadId() const
    );

    PPROFILE_EXCLUDE(
      static PThreadIdentifier GetCurrentThreadId()
    );

    PPROFILE_EXCLUDE(
      PUniqueThreadIdentifier GetUniqueIdentifier() const
    );

    PPROFILE_EXCLUDE(
      static PUniqueThreadIdentifier GetCurrentUniqueIdentifier()
    );

    PPROFILE_EXCLUDE(
      static PINDEX GetTotalCount()
    );

    struct Times
    {
      PPROFILE_EXCLUDE(
        Times()
      );
      PPROFILE_EXCLUDE(
        friend ostream & operator<<(ostream & strm, const Times & times)
      );
      PPROFILE_EXCLUDE(
        float AsPercentage() const
      );
      PPROFILE_EXCLUDE(
        Times operator-(const Times & rhs) const
      );
      PPROFILE_EXCLUDE(
        Times & operator-=(const Times & rhs)
      );
      PPROFILE_EXCLUDE(
        bool operator<(const Times & rhs) const { return m_uniqueId < rhs.m_uniqueId; }
      );

      PString                 m_name;     
      PThreadIdentifier       m_threadId; 
      PUniqueThreadIdentifier m_uniqueId; 
      PTimeInterval           m_real;     
      PTimeInterval           m_kernel;   
      PTimeInterval           m_user;     
      PTime                   m_sample;   
    };

    PPROFILE_EXCLUDE(
    bool GetTimes(
      Times & times   
    ));

    PPROFILE_EXCLUDE(
    static bool GetTimes(
      PThreadIdentifier id, 
      Times & times         
    ));

    PPROFILE_EXCLUDE(
    static void GetTimes(
      std::vector<Times> & times    
    ));
    static void GetTimes(
      std::list<Times> & times      
    );
    static void GetTimes(
      std::set<Times> & times      
    );

    static int GetPercentageCPU(
      Times & previousTimes,                             
      const PTimeInterval & period = PTimeInterval(0,1), 
      PThreadIdentifier id = PNullThreadIdentifier       
    );

    static unsigned GetNumProcessors();

    virtual void Main() = 0;

    static PThread * Current();

    static void Yield();

    static PThread * Create(
      const PNotifier & notifier,     
      INT parameter = 0,              
      AutoDeleteFlag deletion = AutoDeleteThread,
      Priority priorityLevel = NormalPriority,  
      const PString & threadName = PString::Empty(), 
      PINDEX stackSize = 0            
    );
    static PThread * Create(
      const PNotifier & notifier,     
      const PString & threadName      
    ) { return Create(notifier, 0, NoAutoDeleteThread, NormalPriority, threadName); }
  
    bool IsAutoDelete() const { return m_type == e_IsAutoDelete; }

    class LocalStorageBase
    {
      public:
        virtual ~LocalStorageBase() { }
        void ThreadDestroyed(PThread & thread);
      protected:
        LocalStorageBase();
        void DestroyStorage();
        virtual void * Allocate() const = 0;
        virtual void Deallocate(void * ptr) const = 0;
        virtual void * GetStorage() const;
      private:
        typedef std::map<PUniqueThreadIdentifier, void *> DataMap;
        mutable DataMap  m_data;
        PCriticalSection m_mutex;
      friend class PThreadLocalStorageData;
    };

  private:
    PThread(bool isProcess);
    // Create a new thread instance as part of a <code>PProcess</code> class.

    void InternalThreadMain();
    void InternalPreMain();
    void InternalPostMain();
    void InternalDestroy();

    friend class PProcess;
    friend class PExternalThread;
    // So a PProcess can get at PThread() constructor but nothing else.

    PThread(const PThread &)
      : PObject ()
      , m_type()
      , m_originalStackSize()
      , m_threadId()
      , m_uniqueId()
#ifdef _WIN32
      , m_comInitialised()
#endif
    { }
    // Empty constructor to prevent copying of thread instances.

    PThread & operator=(const PThread &) { return *this; }
    // Empty assignment operator to prevent copying of thread instances.

  protected:
    enum Type { e_IsAutoDelete, e_IsManualDelete, e_IsProcess, e_IsExternal } m_type;

    PINDEX m_originalStackSize;

    PString m_threadName; // Give the thread a name for debugging purposes.
    PCriticalSection m_threadNameMutex;

    PThreadIdentifier       m_threadId;
    PUniqueThreadIdentifier m_uniqueId;

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


/*
   This class automates calling a global function with no arguments within it's own thread.
   It is used as follows:

   void GlobalFunction()
   {
   }

   ...
   PString arg;
   new PThreadMain(&GlobalFunction)
 */
class PThreadMain : public PThread
{
    PCLASSINFO(PThreadMain, PThread);
  public:
    typedef void (*FnType)(); 
    PThreadMain(FnType function, bool autoDel = false)
      : PThread(10000, autoDel ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread)
      , m_function(function)
    {
      PThread::Resume();
    }

    ~PThreadMain()
    {
        WaitForTermination();
    }

    virtual void Main()
    {
      (*m_function)();
    }

  protected:
    FnType m_function;
};


/*
   This template automates calling a global function using a functor
   It is used as follows:

   struct Functor {
     void operator()(PThread & thread) { ... code in here }
   }

   ...
   Functor arg;
   new PThreadFunctor<Functor>(arg)
 */
template<typename Functor>
class PThreadFunctor : public PThread
{
    PCLASSINFO(PThreadFunctor, PThread);
  public:
    PThreadFunctor(
      Functor & funct,
      bool autoDel = false,
      const char * name = NULL,
      PThread::Priority priority = PThread::NormalPriority
    )
      : PThread(10000, autoDel ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread, priority, name)
      , m_funct(funct)
    {
      PThread::Resume();
    }

    ~PThreadFunctor()
    {
        WaitForTermination();
    }

    virtual void Main()
    {
      m_funct(*this);
    }

  protected:
    Functor & m_funct;
};


/*
   This template automates calling a global function with one argument within it's own thread.
   It is used as follows:

   void GlobalFunction(PString arg)
   {
   }

   ...
   PString arg;
   new PThread1Arg<PString>(arg, &GlobalFunction)
 */
template<typename Arg1Type>
class PThread1Arg : public PThread
{
    PCLASSINFO(PThread1Arg, PThread);
  public:
    typedef void (*FnType)(Arg1Type arg1);

    PThread1Arg(
      Arg1Type arg1,
      FnType function,
      bool autoDel = false,
      const char * name = NULL,
      PThread::Priority priority = PThread::NormalPriority
    ) : PThread(10000, autoDel ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread, priority, name)
      , m_function(function)
      , m_arg1(arg1)
    {
      PThread::Resume();
    }

    ~PThread1Arg()
    {
        WaitForTermination();
    }

    virtual void Main()
    {
      (*m_function)(m_arg1);
    }

  protected:
    FnType   m_function;
    Arg1Type m_arg1;
};


/*
   This template automates calling a global function with two arguments within it's own thread.
   It is used as follows:

   void GlobalFunction(PString arg1, int arg2)
   {
   }

   ...
   PString arg;
   new PThread2Arg<PString, int>(arg1, arg2, &GlobalFunction)
 */
template<typename Arg1Type, typename Arg2Type>
class PThread2Arg : public PThread
{
    PCLASSINFO(PThread2Arg, PThread);
  public:
    typedef void (*FnType)(Arg1Type arg1, Arg2Type arg2); 
    PThread2Arg(
      Arg1Type arg1,
      Arg2Type arg2,
      FnType function,
      bool autoDel = false,
      const char * name = NULL,
      PThread::Priority priority = PThread::NormalPriority
    ) : PThread(10000, autoDel ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread, priority, name)
      , m_function(function)
      , m_arg1(arg1)
      , m_arg2(arg2)
    {
      PThread::Resume();
    }
    
    ~PThread2Arg()
    {
        WaitForTermination();
    }

    virtual void Main()
    {
      (*m_function)(m_arg1, m_arg2);
    }

  protected:
    FnType   m_function;
    Arg1Type m_arg1;
    Arg2Type m_arg2;
};

/*
   This template automates calling a global function with three arguments within it's own thread.
   It is used as follows:

   void GlobalFunction(PString arg1, int arg2, int arg3)
   {
   }

   ...
   PString arg;
   new PThread3Arg<PString, int, int>(arg1, arg2, arg3, &GlobalFunction)
 */
template<typename Arg1Type, typename Arg2Type, typename Arg3Type>
class PThread3Arg : public PThread
{
  PCLASSINFO(PThread3Arg, PThread);
  public:
    typedef void (*FnType)(Arg1Type arg1, Arg2Type arg2, Arg3Type arg3); 
    PThread3Arg(
      Arg1Type arg1,
      Arg2Type arg2,
      Arg3Type arg3,
      FnType function,
      bool autoDel = false,
      const char * name = NULL,
      PThread::Priority priority = PThread::NormalPriority
    ) : PThread(10000, autoDel ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread, priority, name)
      , m_function(function)
      , m_arg1(arg1)
      , m_arg2(arg2)
      , m_arg3(arg3)
    {
      PThread::Resume();
    }
    
    ~PThread3Arg()
    {
        WaitForTermination();
    }

    virtual void Main()
    {
      (*m_function)(m_arg1, m_arg2, m_arg3);
    }

  protected:
    FnType   m_function;
    Arg1Type m_arg1;
    Arg2Type m_arg2;
    Arg3Type m_arg3;
};

/*
   This template automates calling a member function with no arguments within it's own thread.
   It is used as follows:

   class Example {
     public:
      void Function()
      {
      }
   };

   ...
   Example ex;
   new PThreadObj<Example>(ex, &Example::Function)
 */

template <typename ObjType>
class PThreadObj : public PThread
{
    PCLASSINFO_ALIGNED(PThreadObj, PThread, 16);
  public:
    typedef void (ObjType::*ObjTypeFn)(); 

    PThreadObj(
      ObjType & obj,
      ObjTypeFn function,
      bool autoDel = false,
      const char * name = NULL,
      PThread::Priority priority = PThread::NormalPriority
    ) : PThread(10000,
                autoDel ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread,
                priority,
                name)
      , m_object(obj)
      , m_function(function)
    {
      PThread::Resume();
    }

    ~PThreadObj()
    {
        WaitForTermination();
    }

    void Main()
    {
      (m_object.*m_function)();
    }

  protected:
    ObjType & m_object;
    P_ALIGN_FIELD(ObjTypeFn,m_function,16);
};


/*
   This template automates calling a member function with one argument within it's own thread.
   It is used as follows:

   class Example {
     public:
      void Function(PString arg)
      {
      }
   };

   ...
   Example ex;
   PString str;
   new PThreadObj1Arg<Example>(ex, str, &Example::Function)
 */
template <class ObjType, typename Arg1Type>
class PThreadObj1Arg : public PThread
{
    PCLASSINFO_ALIGNED(PThreadObj1Arg, PThread, 16);
  public:
    typedef void (ObjType::*ObjTypeFn)(Arg1Type); 

    PThreadObj1Arg(
      ObjType & obj,
      Arg1Type arg1,
      ObjTypeFn function,
      bool autoDel = false,
      const char * name = NULL,
      PThread::Priority priority = PThread::NormalPriority
    ) : PThread(10000,
                autoDel ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread,
                priority,
                name)
      , m_object(obj)
      , m_function(function)
      , m_arg1(arg1)
    {
      PThread::Resume();
    }

    ~PThreadObj1Arg()
    {
        WaitForTermination();
    }

    void Main()
    {
      (m_object.*m_function)(m_arg1);
    }

  protected:
    ObjType & m_object;
    P_ALIGN_FIELD(ObjTypeFn,m_function,16);
    Arg1Type  m_arg1;
};

template <class ObjType, typename Arg1Type, typename Arg2Type>
class PThreadObj2Arg : public PThread
{
    PCLASSINFO_ALIGNED(PThreadObj2Arg, PThread, 16);
  public:
    typedef void (ObjType::*ObjTypeFn)(Arg1Type, Arg2Type);

    PThreadObj2Arg(
      ObjType & obj,
      Arg1Type arg1,
      Arg2Type arg2,
      ObjTypeFn function,
      bool autoDel = false,
      const char * name = NULL,
      PThread::Priority priority = PThread::NormalPriority
    ) : PThread(10000,
                autoDel ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread,
                priority,
                name)
      , m_object(obj)
      , m_function(function)
      , m_arg1(arg1)
      , m_arg2(arg2)
    {
      PThread::Resume();
    }

    ~PThreadObj2Arg()
    {
        WaitForTermination();
    }

    void Main()
    {
      (m_object.*m_function)(m_arg1, m_arg2);
    }

  protected:
    ObjType & m_object;
    P_ALIGN_FIELD(ObjTypeFn,m_function,16);
    Arg1Type  m_arg1;
    Arg2Type  m_arg2;
};


//
// PThreadLocalStorage
//

template <class Storage_T>
class PThreadLocalStorage : public PThread::LocalStorageBase
{
  public:
    typedef Storage_T * Ptr_T;

    ~PThreadLocalStorage()        { this->DestroyStorage(); }
    Ptr_T Get() const             { return  (Ptr_T)this->GetStorage(); }
    operator Ptr_T() const        { return  (Ptr_T)this->GetStorage(); }
    Ptr_T operator->() const      { return  (Ptr_T)this->GetStorage(); }
    Storage_T & operator*() const { return *(Ptr_T)this->GetStorage(); }

  protected:
    virtual void * Allocate() const           { return new Storage_T(); }
    virtual void Deallocate(void * ptr) const { delete (Ptr_T)ptr; }
};


#define P_HAS_THREADLOCAL_STORAGE 1  // For backward compatbility


#endif // PTLIB_THREAD_H

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