pprocess.h

Go to the documentation of this file.

/*
 * pprocess.h
 *
 * Operating System Process (running program executable) 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): ______________________________________.
 *
 * $Revision: 30255 $
 * $Author: rjongbloed $
 * $Date: 2013-08-07 13:53:48 +1000 (Wed, 07 Aug 2013) $
 */

#ifndef PTLIB_PROCESS_H
#define PTLIB_PROCESS_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <ptlib/mutex.h>
#include <ptlib/syncpoint.h>
#include <ptlib/thread.h>
#include <ptlib/pfactory.h>

#include <queue>
#include <set>

#ifdef P_VXWORKS
#define PCREATE_PROCESS(cls) \
  cls instance; \
  instance.InternalMain();
#elif defined(P_RTEMS)
#define PCREATE_PROCESS(cls) \
extern "C" {\
   void* POSIX_Init( void* argument) \
     { \
       static cls instance; \
       exit( instance.InternalMain() ); \
     } \
}
#elif defined(_WIN32_WCE)
#define PCREATE_PROCESS(cls) \
  PDEFINE_WINMAIN(hInstance, , lpCmdLine, ) \
    { \
      cls *pInstance = new cls(); \
      pInstance->GetArguments().SetArgs(lpCmdLine); \
      int terminationValue = pInstance->InternalMain(hInstance); \
      delete pInstance; \
      return terminationValue; \
    }
#else
#define PCREATE_PROCESS(cls) \
  int main(int argc, char * argv[]) \
    { \
      cls *pInstance = new cls(); \
      pInstance->PreInitialise(argc, argv); \
      int terminationValue = pInstance->InternalMain(); \
      delete pInstance; \
      return terminationValue; \
    }
#endif // P_VXWORKS

/*$MACRO PDECLARE_PROCESS(cls,ancestor,manuf,name,major,minor,status,build)
   This macro is used to declare the components necessary for a user PWLib
   process. This will declare the PProcess descendent class, eg PApplication,
   and create an instance of the class. See the <code>PCREATE_PROCESS</code> macro
   for more details.
 */
#define PDECLARE_PROCESS(cls,ancestor,manuf,name,major,minor,status,build) \
  class cls : public ancestor { \
    PCLASSINFO(cls, ancestor); \
    public: \
      cls() : ancestor(manuf, name, major, minor, status, build) { } \
    private: \
      virtual void Main(); \
  };


class PTimerList : public PObject
/* This class defines a list of <code>PTimer</code> objects. It is primarily used
   internally by the library and the user should never create an instance of
   it. The <code>PProcess</code> instance for the application maintains an instance
   of all of the timers created so that it may decrements them at regular
   intervals.
 */
{
  PCLASSINFO(PTimerList, PObject);

  public:
    // Create a new timer list
    PTimerList();

    /* Decrement all the created timers and dispatch to their callback
       functions if they have expired. The <code>PTimer::Tick()</code> function
       value is used to determine the time elapsed since the last call to
       Process().

       The return value is the number of milliseconds until the next timer
       needs to be despatched. The function need not be called again for this
       amount of time, though it can (and usually is).
       
       @return
       maximum time interval before function should be called again.
     */
    PTimeInterval Process();

    PTimer::IDType GetNewTimerId() const { return ++timerId; }

    class RequestType {
      public:
        enum Action {
          Stop,
          Start,
          Pause
        } m_action;

        RequestType(Action act, PTimer * t)
          : m_action(act)
          , m_timer(t)
          , m_id(t->GetTimerId())
          , m_absoluteTime(t->GetAbsoluteTime())
          , m_serialNumber(t->GetNextSerialNumber())
          , m_sync(NULL)
        { }

        PTimer *                    m_timer;
        PTimer::IDType              m_id;
        PInt64                      m_absoluteTime;
        PAtomicInteger::IntegerType m_serialNumber;
        PSyncPoint *                m_sync;
    };

    void QueueRequest(RequestType::Action action, PTimer * timer, bool isSync = true);

    void ProcessTimerQueue();

  private:
    // queue of timer action requests
    PMutex m_queueMutex;
    typedef std::queue<RequestType> RequestQueueType;
    RequestQueueType m_requestQueue;

    //  counter to keep track of timer IDs
    mutable PAtomicInteger timerId; 

    // map used to store active timer information
    struct ActiveTimerInfo {
      ActiveTimerInfo(PTimer * t, PAtomicInteger::IntegerType serialNumber) 
        : m_timer(t), m_serialNumber(serialNumber) { }
      PTimer * m_timer;
      PAtomicInteger::IntegerType m_serialNumber;
    };
    typedef std::map<PTimer::IDType, ActiveTimerInfo> ActiveTimerInfoMap;
    ActiveTimerInfoMap m_activeTimers;

    // set used to store timer expiry times, in order
    struct TimerExpiryInfo {
      TimerExpiryInfo(PTimer::IDType id, PInt64 expireTime, PAtomicInteger::IntegerType serialNumber)
        : m_timerId(id), m_expireTime(expireTime), m_serialNumber(serialNumber) { }
      PTimer::IDType m_timerId;
      PInt64 m_expireTime;
      PAtomicInteger::IntegerType m_serialNumber;
    };

          struct TimerExpiryInfo_compare
                  : public binary_function<TimerExpiryInfo, TimerExpiryInfo, bool>
          {     
            bool operator()(const TimerExpiryInfo & _Left, const TimerExpiryInfo & _Right) const
                  {     return (_Left.m_expireTime < _Right.m_expireTime); }
          };

    typedef std::multiset<TimerExpiryInfo, TimerExpiryInfo_compare> TimerExpiryInfoList;
    TimerExpiryInfoList m_expiryList;

    // The last system timer tick value that was used to process timers.
    PTimeInterval m_lastSample;

    // thread that handles the timer stuff
    PThread * m_timerThread;
};


// PProcess

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

  public:

    enum CodeStatus {
      AlphaCode,    
      BetaCode,     
      ReleaseCode,  
      NumCodeStatuses
    };

    PProcess(
      const char * manuf = "",         
      const char * name = "",          
      WORD majorVersion = 1,           
      WORD minorVersion = 0,           
      CodeStatus status = ReleaseCode, 
      WORD buildNumber = 1,            
      bool library = false,            
      bool suppressStartup = false     
    );

    Comparison Compare(
      const PObject & obj   
    ) const;

    virtual void Terminate();

    static PProcess & Current();

    void Startup();

    virtual void OnThreadStart(
      PThread & thread
    );

    virtual void OnThreadEnded(
      PThread & thread
    );

    virtual bool OnInterrupt(
      bool terminating 
    );

    static PBoolean IsInitialised();

    void SetTerminationValue(
      int value  
    );

    int GetTerminationValue() const;

    PArgList & GetArguments();

    virtual const PString & GetManufacturer() const;

    virtual const PString & GetName() const;

    virtual PString GetVersion(
      PBoolean full = true 
    ) const;

    const PFilePath & GetFile() const;

    PProcessIdentifier GetProcessID() const { return m_processID; }

    static PProcessIdentifier GetCurrentProcessID();

    PTime GetStartTime() const;

    PString GetUserName() const;

    PBoolean SetUserName(
      const PString & username, 
      PBoolean permanent = false    
    );

    PDirectory GetHomeDirectory() const;

    PString GetGroupName() const;

    PBoolean SetGroupName(
      const PString & groupname, 
      PBoolean permanent = false     
    );

    int GetMaxHandles() const;

    PBoolean SetMaxHandles(
      int newLimit  
    );

#if P_CONFIG_FILE

    virtual PString GetConfigurationFile();

    void SetConfigurationPath(
      const PString & path   
    );
#endif // P_CONFIG_FILE


    static PString GetOSClass();

    static PString GetOSName();

    static PString GetOSHardware();

    static PString GetOSVersion();

    static bool IsOSVersion(
      unsigned major,     
      unsigned minor = 0, 
      unsigned build = 0  
    );

    static PDirectory GetOSConfigDir();

    static PString GetLibVersion();

    PTimerList * GetTimerList();

    void PreInitialise(
      int argc,     // Number of program arguments.
      char ** argv  // Array of strings for program arguments.
    );

    void PreShutdown();
    static void PostShutdown();

    virtual int InternalMain(void * arg = NULL);

    class HostSystemURLHandlerInfo 
    {
      public:
        HostSystemURLHandlerInfo()
        { }

        HostSystemURLHandlerInfo(const PString & t)
          : type(t)
        { }

        static bool RegisterTypes(const PString & types, bool force = true);

        void SetIcon(const PString & icon);
        PString GetIcon() const;

        void SetCommand(const PString & key, const PString & command);
        PString GetCommand(const PString & key) const;

        bool GetFromSystem();
        bool CheckIfRegistered();

        bool Register();

        PString type;

    #if _WIN32
        PString iconFileName;
        PStringToString cmds;
    #endif
    };

    PThread * GetThread(PThreadIdentifier threadId) const;
    bool SignalTimerChange();

  protected:
    void Construct();

  // Member variables
    bool m_library;                   // Indication PTLib is being used as a library for an external process.
    int  terminationValue;            // Application return value

    PString manufacturer;             // Application manufacturer name.
    PString productName;              // Application executable base name from argv[0]

    WORD       majorVersion;          // Major version number of the product
    WORD       minorVersion;          // Minor version number of the product
    CodeStatus status;                // Development status of the product
    WORD       buildNumber;           // Build number of the product

    PFilePath    executableFile;      // Application executable file from argv[0] (not open)
    PStringArray configurationPaths;  // Explicit file or set of directories to find default PConfig
    PArgList     arguments;           // The list of arguments
    int          maxHandles;          // Maximum number of file handles process can open.

    PTime programStartTime;           // time at which process was intantiated, i.e. started

    bool   m_shuttingDown;
    PMutex m_threadMutex;

    typedef std::map<PThreadIdentifier, PThread *> ThreadMap;
    ThreadMap m_activeThreads;
    void InternalThreadStarted(PThread * thread);
    void InternalThreadEnded(PThread * thread);
    
    typedef PList<PThread> ThreadList;
    ThreadList m_autoDeleteThreads;
    void InternalSetAutoDeleteThread(PThread * thread);
    void InternalCleanAutoDeleteThreads();

    PAtomicBoolean m_keepingHouse;
    PThread      * m_houseKeeper; // Thread for doing timers, thread clean up etc.
    PSyncPoint     m_signalHouseKeeper;
    void HouseKeeping();

    PTimerList m_timers;

    PProcessIdentifier m_processID;

  friend class PThread;


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


 class PLibraryProcess : public PProcess
 {
  PCLASSINFO(PLibraryProcess, PProcess);

  public:
    PLibraryProcess(
      const char * manuf = "",         
      const char * name = "",          
      WORD majorVersionNum = 1,           
      WORD minorVersionNum = 0,           
      CodeStatus statusCode = ReleaseCode, 
      WORD buildNum = 1             
    ) : PProcess(manuf, name, majorVersionNum, minorVersionNum, statusCode, buildNum, true) { }

    virtual void Main() { }
};


/*
 *  one instance of this class (or any descendants) will be instantiated
 *  via PGenericFactory<PProessStartup> one "main" has been started, and then
 *  the OnStartup() function will be called. The OnShutdown function will
 *  be called after main exits, and the instances will be destroyed if they
 *  are not singletons
 */
class PProcessStartup : public PObject
{
  PCLASSINFO(PProcessStartup, PObject)
  public:
    virtual void OnStartup()  { }
    virtual void OnShutdown() { }
};

typedef PFactory<PProcessStartup> PProcessStartupFactory;

#if PTRACING

// using an inline definition rather than a #define crashes gcc 2.95. Go figure
#define P_DEFAULT_TRACE_OPTIONS ( PTrace::Blocks | PTrace::Timestamp | PTrace::Thread | PTrace::FileAndLine )

template <unsigned level, unsigned options = P_DEFAULT_TRACE_OPTIONS >
class PTraceLevelSetStartup : public PProcessStartup
{
  public:
    void OnStartup()
    { PTrace::Initialise(level, NULL, options); }
};

#endif // PTRACING


#endif // PTLIB_PROCESS_H


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