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): ______________________________________.
 *
 * $Revision: 20492 $
 * $Author: rjongbloed $
 * $Date: 2008-06-24 23:36:32 +0000 (Tue, 24 Jun 2008) $
 */

#ifndef _PTHREAD
#define _PTHREAD

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#ifdef Priority
#undef Priority
#endif

#include <ptlib/mutex.h>

class PSemaphore;

#define PThreadIdentifer PThreadIdentifier

typedef P_THREADIDENTIFIER PThreadIdentifier;

// PThread

class PThread : public PObject
{
  PCLASSINFO(PThread, PObject);

  public:

    enum Priority {
      LowestPriority,  

      LowPriority,     

      NormalPriority,  

      HighPriority,    

      HighestPriority, 

      NumPriorities
    };

    enum AutoDeleteFlag {
      AutoDeleteThread,   

      NoAutoDeleteThread  
    };

    PThread(
      PINDEX,                 
      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;

    virtual void Suspend(
      PBoolean susp = PTrue    
    );

    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;

    virtual void SetThreadName(
      const PString & name        
    );

    virtual PThreadIdentifier GetThreadId() const;
    static PThreadIdentifier GetCurrentThreadId();

    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 = 65536         
    );
    static PThread * Create(
      const PNotifier & notifier,     
      const PString & threadName      
    ) { return Create(notifier, 0, NoAutoDeleteThread, NormalPriority, threadName); }

  protected:
    void InitialiseProcessThread();
    /* Initialialise the primordial thread, the one in the PProcess. This is
       required due to the bootstrap logic of processes and threads.
     */

  private:
    PThread();
    // Create a new thread instance as part of a #PProcess class.

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

    PThread(const PThread &) : PObject () { }
    // Empty constructor to prevent copying of thread instances.

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

    PBoolean autoDelete;
    // Automatically delete the thread on completion.

    // Give the thread a name for debugging purposes.
    PString threadName;
    PMutex threadNameMutex;

#if PTRACING
  public:
    struct TraceInfo {
      TraceInfo()
      { traceBlockIndentLevel = 0; }

      PStack<PStringStream> traceStreams;
      unsigned traceLevel;
      unsigned traceBlockIndentLevel;
    };

#ifndef P_HAS_THREADLOCAL_STORAGE
  private:
    friend class PTrace;
    TraceInfo traceInfo;
#endif // P_HAS_THREADLOCAL_STORAGE
#endif // PTRACING

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

// Include definition of platform dependent thread ID format
#if defined(_WIN32) && !defined(_WIN32_WCE)
  #define PTHREAD_ID_FMT ":%u"
#else
  #define PTHREAD_ID_FMT ":0x%x"
#endif

#ifdef _MSC_VER
#pragma warning(disable:4355)
#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 _fn, PBoolean _autoDelete = PFalse)
      : PThread(10000, _autoDelete ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread), fn(_fn)
    { PThread::Resume(); }
    PThreadMain(const char * _file, int _line, FnType _fn, PBoolean _autoDelete = PFalse)
      : PThread(10000, _autoDelete ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread,  NormalPriority,
        psprintf("%s:%08x-%s:%i", GetClass(), (void *)this, _file, _line)), fn(_fn)
    { PThread::Resume(); }
    virtual void Main()
    { (*fn)(); }
    FnType fn;
};

/*
   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 _fn, PBoolean _autoDelete = PFalse)
      : PThread(10000, _autoDelete ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread), fn(_fn),
        arg1(_arg1)
    { PThread::Resume(); }
    PThread1Arg(const char * _file, int _line, Arg1Type _arg1, FnType _fn, PBoolean _autoDelete = PFalse)
      : PThread(10000, _autoDelete ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread,  NormalPriority,
        psprintf("%s:%08x-%s:%i", GetClass(), (void *)this, _file, _line)), fn(_fn),
        arg1(_arg1)
    { PThread::Resume(); }
    virtual void Main()
    { (*fn)(arg1); }
    FnType fn;
    Arg1Type 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 _fn, PBoolean _autoDelete = PFalse)
      : PThread(10000, _autoDelete ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread), fn(_fn),
        arg1(_arg1), arg2(_arg2)
    { PThread::Resume(); }
    PThread2Arg(const char * _file, int _line, Arg1Type _arg1, Arg2Type _arg2, FnType _fn, PBoolean _autoDelete = PFalse)
      : PThread(10000, _autoDelete ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread, NormalPriority,
        psprintf("%s:%08x-%s:%i", GetClass(), (void *)this, _file, _line)), fn(_fn),
        arg1(_arg1), arg2(_arg2)
    { PThread::Resume(); }
    virtual void Main()
    { (*fn)(arg1, arg2); }
    FnType fn;
    Arg1Type arg1;
    Arg2Type 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 _fn, PBoolean _autoDelete = PFalse)
      : PThread(10000, _autoDelete ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread), fn(_fn),
        arg1(_arg1), arg2(_arg2), arg3(_arg3)
    { PThread::Resume(); }
    PThread3Arg(const char * _file, int _line, Arg1Type _arg1, Arg2Type _arg2, Arg3Type _arg3, FnType _fn, PBoolean _autoDelete = PFalse)
      : PThread(10000, _autoDelete ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread, NormalPriority,
        psprintf("%s:%08x-%s:%i", GetClass(), (void *)this, _file, _line)), fn(_fn),
        arg1(_arg1), arg2(_arg2), arg3(_arg3)
    { PThread::Resume(); }
    virtual void Main()
    { (*fn)(arg1, arg2, arg3); }
    FnType fn;
    Arg1Type arg1;
    Arg2Type arg2;
    Arg2Type 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
{
  public:
  PCLASSINFO(PThreadObj, PThread);
  public:
    typedef void (ObjType::*ObjTypeFn)(); 
    PThreadObj(ObjType & _obj, ObjTypeFn _fn, PBoolean _autoDelete = PFalse)
      : PThread(10000, _autoDelete ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread),
        obj(_obj), fn(_fn)
    { PThread::Resume(); }
    PThreadObj(const char * _file, int _line, ObjType & _obj, ObjTypeFn _fn, PBoolean _autoDelete = PFalse)
      : PThread(10000, _autoDelete ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread, NormalPriority,
        psprintf("%s:%08x-%s:%i", GetClass(), (void *)this, _file, _line)),
        obj(_obj), fn(_fn)
    { PThread::Resume(); }
    void Main()
    { (obj.*fn)(); }

  protected:
    ObjType & obj;
    ObjTypeFn fn;
};


/*
   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(PThreadObj1Arg, PThread);
  public:
    typedef void (ObjType::*ObjTypeFn)(Arg1Type); 
    PThreadObj1Arg(ObjType & _obj, Arg1Type _arg1, ObjTypeFn _fn, PBoolean _autoDelete = PFalse)
      : PThread(10000, _autoDelete ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread),
                                obj(_obj), fn(_fn), arg1(_arg1)
    { PThread::Resume(); }
    PThreadObj1Arg(const char * _file, int _line, ObjType & _obj, Arg1Type _arg1, ObjTypeFn _fn, PBoolean _autoDelete = PFalse)
      : PThread(10000, _autoDelete ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread, NormalPriority,
                                psprintf("%s:%08x-%s:%i", GetClass(), (void *)this, _file, _line)),
                                obj(_obj), fn(_fn), arg1(_arg1)
    { PThread::Resume(); }
    void Main()
    { (obj.*fn)(arg1); }

  protected:
    ObjType & obj;
    ObjTypeFn fn;
    Arg1Type arg1;
};

template <class ObjType, typename Arg1Type, typename Arg2Type>
class PThreadObj2Arg : public PThread
{
  PCLASSINFO(PThreadObj2Arg, PThread);
  public:
    typedef void (ObjType::*ObjTypeFn)(Arg1Type, Arg2Type); 
    PThreadObj2Arg(ObjType & _obj, Arg1Type _arg1, Arg2Type _arg2, ObjTypeFn _fn, PBoolean _autoDelete = PFalse)
      : PThread(10000, _autoDelete ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread),
                                obj(_obj), fn(_fn), arg1(_arg1), arg2(_arg2)
    { PThread::Resume(); }
    PThreadObj2Arg(const char * _file, int _line, ObjType & _obj, Arg1Type _arg1, Arg2Type _arg2, ObjTypeFn _fn, PBoolean _autoDelete = PFalse)
      : PThread(10000, _autoDelete ? PThread::AutoDeleteThread : PThread::NoAutoDeleteThread, NormalPriority,
                                psprintf("%s:%08x-%s:%i", GetClass(), (void *)this, _file, _line)),
                                obj(_obj), fn(_fn), arg1(_arg1), arg2(_arg2)
    { PThread::Resume(); }
    void Main()
    { (obj.*fn)(arg1, arg2); }

  protected:
    ObjType & obj;
    ObjTypeFn fn;
    Arg1Type arg1;
    Arg1Type arg2;
};


//
// PThreadLocalStorage
//

#ifdef _WIN32

#define P_HAS_THREADLOCAL_STORAGE 1

template <class Storage_T>
class PThreadLocalStorage
{
  public:
    typedef DWORD Key_T;
    typedef Storage_T value_type;

    PThreadLocalStorage()
    { key = TlsAlloc(); }

    ~PThreadLocalStorage()
    { TlsFree(key);  }

    Key_T GetKey() const
    { return key; }

    value_type * Get()
    { return (value_type *) TlsGetValue(key); }

    void Set(value_type * v)
    { TlsSetValue(key, (LPVOID)v); }

  protected:
    DWORD key;
};

#elif defined(P_PTHREADS)

#include <pthread.h>

#define P_HAS_THREADLOCAL_STORAGE 1

template <class Storage_T>
class PThreadLocalStorage
{
  public:
    typedef pthread_key_t Key_T;
    typedef Storage_T value_type;

    PThreadLocalStorage()
    { pthread_key_create(&key, NULL); }

    ~PThreadLocalStorage()
    { pthread_key_delete(key); }

    Key_T GetKey() const
    { return key; }

    value_type * Get()
    { return (value_type *)pthread_getspecific(key); }

    void Set(value_type * v)
    { pthread_setspecific(key, v); }

  private:
    Key_T key;
};

#else

#undef P_HAS_THREADLOCAL_STORAGE 1
#warning("Thread local storage not supported");

#endif


#ifdef _MSC_VER
#pragma warning(default:4355)
#endif

#endif // _PTHREAD

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

---