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): ______________________________________.
 */

#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>


#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() ); \
     } \
}
#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 PExternalThread;

// PProcess

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

  public:
    enum CodeStatus {
      AlphaCode,        
      BetaCode,         
      ReleaseCode,      
      HotfixCode        
    };

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

    Comparison Compare(
      const PObject & obj   
    ) const;

    virtual void PrintOn(
      ostream & strm
    ) const;

    virtual void Terminate();

    static PProcess & Current();

    void Startup();

    bool GetAllThreadIdentifiers(
      std::vector<PThreadIdentifier> & identifiers   
    );

    PThread * GetThread(
      PThreadIdentifier threadId    
    ) const;

    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();

    bool IsMultipleInstance() const;

    PTime GetStartTime() const;

    struct MemoryUsage {
      MemoryUsage()
        : m_virtual(0)
        , m_resident(0)
        , m_max(0)
        , m_current(0)
        , m_blocks(0)
        { }

      size_t m_virtual;
      size_t m_resident;
      size_t m_max;
      size_t m_current;
      size_t m_blocks;
    };

    void GetMemoryUsage(
      MemoryUsage & usage
    ) const;

    PPROFILE_EXCLUDE(
    bool GetProcessTimes(
      Times & times   
    ) const
    );

    PPROFILE_EXCLUDE(
    static bool GetSystemTimes(
      Times & times   
    ));

    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();

    struct VersionInfo
    {
      unsigned     m_major;
      unsigned     m_minor;
      CodeStatus   m_status;
      unsigned     m_patch;
      unsigned     m_oem;
      unsigned     m_svn;
      const char * m_git;

      PString AsString(bool full = true) const;
    };

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

    virtual int InternalMain(void * arg = NULL);

    virtual void AddRunTimeSignalHandlers(
      const int * signals = NULL
    );

    virtual void RemoveRunTimeSignalHandlers();

    virtual void AsynchronousRunTimeSignal(
      int signal, 
      PProcessIdentifier source  
    );

    struct RunTimeSignalInfo {
      int                m_signal;
      PProcessIdentifier m_source;
    };

    virtual void HandleRunTimeSignal(const RunTimeSignalInfo & signalInfo);
    virtual void HandleRunTimeSignal(int signal); // Backward compatibility

    static const char * GetRunTimeSignalName(int signal);

    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
    };

    virtual bool IsServiceProcess() const;
    bool SignalTimerChange();

  protected:
    void PlatformConstruct();
    void PlatformDestruct();

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

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

    VersionInfo m_version;            // Process (applications) version

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

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

    atomic<bool> m_shuttingDown;

    // Do not write trace logs while holding m_threadMutex, as most trace logs lock
    // the target log mutex before obtaining this in PThread::Current().
    PCriticalSection m_threadMutex; 

    typedef std::map<PThreadIdentifier, PThread *> ThreadMap;
    ThreadMap m_activeThreads;
    void InternalThreadStarted(PThread * thread);
    void InternalThreadEnded(PThread * thread);
    
    typedef std::list< PSharedPtr<PExternalThread> > ThreadList;
    ThreadList m_externalThreads;
    PSyncQueue<PThread*> m_autoDeleteThreads;

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

#if P_TIMERS
    PTimer::List * m_timerList;
    friend PTimer::List * PTimer::TimerList();
#endif

    PProcessIdentifier m_processID;

    static PRunTimeSignalHandler PlatformSetRunTimeSignalHandler(int signal);
    static void PlatformResetRunTimeSignalHandler(int signal, PRunTimeSignalHandler previous);
    static POrdinalToString::Initialiser const InternalSigNames[];

    std::vector<PRunTimeSignalHandler> m_previousRunTimeSignalHandlers;
    std::vector<RunTimeSignalInfo> m_RunTimeSignalsQueueBuffer;
    size_t m_RunTimeSignalsQueueIn, m_RunTimeSignalsQueueOut;
    PCriticalSection m_RunTimeSignalsQueueMutex;
    void InternalPostRunTimeSignal(int signal, PProcessIdentifier source);
    void InternalHandleRunTimeSignal(const RunTimeSignalInfo & signalInfo);

#if PTRACING
    PDECLARE_NOTIFIER(PTimer, PProcess, ProfileUpdateLogTimer) { PTRACE(3, "PTLibProfile", *this); }
    void PrintProfileOn(ostream & strm);
    PTimer         * m_profileProcessTimer;
    PCriticalSection m_profileProcessMutex;
    Times            m_profileLastProcessTimes;
    set<Times>       m_profileLastThreadTimes;
#endif // PTRACING

  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 = "",              
      unsigned majorVersionNum = 1,        
      unsigned minorVersionNum = 0,        
      CodeStatus statusCode = ReleaseCode, 
      unsigned buildNum = 1,               
      bool suppressStartup = false         
    ) : PProcess(manuf, name, majorVersionNum, minorVersionNum, statusCode, buildNum, true, suppressStartup) { }

    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 ///////////////////////////////////////////////////////////////