PTLib  Version 2.10.10
pprocess.h
Go to the documentation of this file.
1 /*
2  * pprocess.h
3  *
4  * Operating System Process (running program executable) class.
5  *
6  * Portable Windows Library
7  *
8  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
9  *
10  * The contents of this file are subject to the Mozilla Public License
11  * Version 1.0 (the "License"); you may not use this file except in
12  * compliance with the License. You may obtain a copy of the License at
13  * http://www.mozilla.org/MPL/
14  *
15  * Software distributed under the License is distributed on an "AS IS"
16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
17  * the License for the specific language governing rights and limitations
18  * under the License.
19  *
20  * The Original Code is Portable Windows Library.
21  *
22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
23  *
24  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
25  * All Rights Reserved.
26  *
27  * Contributor(s): ______________________________________.
28  *
29  * $Revision: 27817 $
30  * $Author: rjongbloed $
31  * $Date: 2012-06-12 21:52:14 -0500 (Tue, 12 Jun 2012) $
32  */
33 
34 #ifndef PTLIB_PROCESS_H
35 #define PTLIB_PROCESS_H
36 
37 #ifdef P_USE_PRAGMA
38 #pragma interface
39 #endif
40 
41 #include <ptlib/mutex.h>
43 #include <ptlib/thread.h>
44 #include <ptlib/pfactory.h>
45 
46 #include <queue>
47 #include <set>
48 
55 #ifdef P_VXWORKS
56 #define PCREATE_PROCESS(cls) \
57  cls instance; \
58  instance.InternalMain();
59 #elif defined(P_RTEMS)
60 #define PCREATE_PROCESS(cls) \
61 extern "C" {\
62  void* POSIX_Init( void* argument) \
63  { \
64  static cls instance; \
65  exit( instance.InternalMain() ); \
66  } \
67 }
68 #elif defined(_WIN32_WCE)
69 #define PCREATE_PROCESS(cls) \
70  PDEFINE_WINMAIN(hInstance, , lpCmdLine, ) \
71  { \
72  cls *pInstance = new cls(); \
73  pInstance->GetArguments().SetArgs(lpCmdLine); \
74  int terminationValue = pInstance->InternalMain(hInstance); \
75  delete pInstance; \
76  return terminationValue; \
77  }
78 #else
79 #define PCREATE_PROCESS(cls) \
80  int main(int argc, char ** argv, char ** envp) \
81  { \
82  cls *pInstance = new cls(); \
83  pInstance->PreInitialise(argc, argv, envp); \
84  int terminationValue = pInstance->InternalMain(); \
85  delete pInstance; \
86  return terminationValue; \
87  }
88 #endif // P_VXWORKS
89 
90 /*$MACRO PDECLARE_PROCESS(cls,ancestor,manuf,name,major,minor,status,build)
91  This macro is used to declare the components necessary for a user PWLib
92  process. This will declare the PProcess descendent class, eg PApplication,
93  and create an instance of the class. See the <code>PCREATE_PROCESS</code> macro
94  for more details.
95  */
96 #define PDECLARE_PROCESS(cls,ancestor,manuf,name,major,minor,status,build) \
97  class cls : public ancestor { \
98  PCLASSINFO(cls, ancestor); \
99  public: \
100  cls() : ancestor(manuf, name, major, minor, status, build) { } \
101  private: \
102  virtual void Main(); \
103  };
104 
105 
106 class PTimerList : public PObject
107 /* This class defines a list of <code>PTimer</code> objects. It is primarily used
108  internally by the library and the user should never create an instance of
109  it. The <code>PProcess</code> instance for the application maintains an instance
110  of all of the timers created so that it may decrements them at regular
111  intervals.
112  */
113 {
114  PCLASSINFO(PTimerList, PObject);
115 
116  public:
117  // Create a new timer list
118  PTimerList();
119 
120  /* Decrement all the created timers and dispatch to their callback
121  functions if they have expired. The <code>PTimer::Tick()</code> function
122  value is used to determine the time elapsed since the last call to
123  Process().
124 
125  The return value is the number of milliseconds until the next timer
126  needs to be despatched. The function need not be called again for this
127  amount of time, though it can (and usually is).
128 
129  @return
130  maximum time interval before function should be called again.
131  */
133 
134  PTimer::IDType GetNewTimerId() const { return ++timerId; }
135 
136  class RequestType {
137  public:
138  enum Action {
141  } m_action;
142 
144  : m_action(act)
145  , m_timer(t)
146  , m_id(t->GetTimerId())
147  , m_absoluteTime(t->GetAbsoluteTime())
148  , m_serialNumber(t->GetNextSerialNumber())
149  , m_sync(NULL)
150  { }
151 
157  };
158 
159  void QueueRequest(RequestType::Action action, PTimer * timer, bool isSync = true);
160 
161  void ProcessTimerQueue();
162 
163  private:
164  // queue of timer action requests
165  PMutex m_queueMutex;
166  typedef std::queue<RequestType> RequestQueueType;
167  RequestQueueType m_requestQueue;
168 
169  // add an active timer to the lists
170  void AddActiveTimer(const RequestType & request);
171 
172  // counter to keep track of timer IDs
173  mutable PAtomicInteger timerId;
174 
175  // map used to store active timer information
176  struct ActiveTimerInfo {
177  ActiveTimerInfo(PTimer * t, PAtomicInteger::IntegerType serialNumber)
178  : m_timer(t), m_serialNumber(serialNumber) { }
179  PTimer * m_timer;
180  PAtomicInteger::IntegerType m_serialNumber;
181  };
182  typedef std::map<PTimer::IDType, ActiveTimerInfo> ActiveTimerInfoMap;
183  ActiveTimerInfoMap m_activeTimers;
184 
185  // set used to store timer expiry times, in order
186  struct TimerExpiryInfo {
187  TimerExpiryInfo(PTimer::IDType id, PInt64 expireTime, PAtomicInteger::IntegerType serialNumber)
188  : m_timerId(id), m_expireTime(expireTime), m_serialNumber(serialNumber) { }
189  PTimer::IDType m_timerId;
190  PInt64 m_expireTime;
191  PAtomicInteger::IntegerType m_serialNumber;
192  };
193 
194  struct TimerExpiryInfo_compare
195  : public binary_function<TimerExpiryInfo, TimerExpiryInfo, bool>
196  {
197  bool operator()(const TimerExpiryInfo & _Left, const TimerExpiryInfo & _Right) const
198  { return (_Left.m_expireTime < _Right.m_expireTime); }
199  };
200 
201  typedef std::multiset<TimerExpiryInfo, TimerExpiryInfo_compare> TimerExpiryInfoList;
202  TimerExpiryInfoList m_expiryList;
203 
204  // The last system timer tick value that was used to process timers.
205  PTimeInterval m_lastSample;
206 
207  // thread that handles the timer stuff
208  PThread * m_timerThread;
209 };
210 
211 
213 // PProcess
214 
227 class PProcess : public PThread
228 {
229  PCLASSINFO(PProcess, PThread);
230 
231  public:
234  enum CodeStatus {
243  };
244 
247  PProcess(
248  const char * manuf = "",
249  const char * name = "",
250  WORD majorVersion = 1,
251  WORD minorVersion = 0,
253  WORD buildNumber = 1,
254  bool library = false
255  );
257 
267  const PObject & obj
268  ) const;
270 
275  virtual void Terminate();
276 
282  virtual PString GetThreadName() const;
283 
289  virtual void SetThreadName(
290  const PString & name
291  );
293 
302  static PProcess & Current();
303 
307  virtual void OnThreadStart(
308  PThread & thread
309  );
310 
314  virtual void OnThreadEnded(
315  PThread & thread
316  );
317 
330  virtual bool OnInterrupt(
331  bool terminating
332  );
333 
340  static PBoolean IsInitialised();
341 
348  void SetTerminationValue(
349  int value
350  );
351 
361  int GetTerminationValue() const;
362 
370 
380  virtual const PString & GetManufacturer() const;
381 
391  virtual const PString & GetName() const;
392 
407  virtual PString GetVersion(
408  PBoolean full = true
409  ) const;
410 
416  const PFilePath & GetFile() const;
417 
425  PProcessIdentifier GetProcessID() const { return m_processID; }
426 
434  static PProcessIdentifier GetCurrentProcessID();
435 
438  PTime GetStartTime() const;
439 
448  PString GetUserName() const;
449 
473  const PString & username,
474  PBoolean permanent = false
475  );
476 
485  PString GetGroupName() const;
486 
512  const PString & groupname,
513  PBoolean permanent = false
514  );
515 
522  int GetMaxHandles() const;
523 
534  int newLimit
535  );
536 
537 #ifdef P_CONFIG_FILE
538 
540  virtual PString GetConfigurationFile();
541 #endif
542 
557  const PString & path
558  );
560 
569  static PString GetOSClass();
570 
577  static PString GetOSName();
578 
584  static PString GetOSHardware();
585 
592  static PString GetOSVersion();
593 
599  static bool IsOSVersion(
600  unsigned major,
601  unsigned minor = 0,
602  unsigned build = 0
603  );
604 
612  static PDirectory GetOSConfigDir();
613 
620  static PString GetLibVersion();
622 
630 
634  void PreInitialise(
635  int argc, // Number of program arguments.
636  char ** argv, // Array of strings for program arguments.
637  char ** envp // Array of string for the system environment
638  );
639 
643  static void PreShutdown();
644  static void PostShutdown();
645 
647  virtual int InternalMain(void * arg = NULL);
648 
671  {
672  public:
674  { }
675 
677  : type(t)
678  { }
679 
680  static bool RegisterTypes(const PString & types, bool force = true);
681 
682  void SetIcon(const PString & icon);
683  PString GetIcon() const;
684 
685  void SetCommand(const PString & key, const PString & command);
686  PString GetCommand(const PString & key) const;
687 
688  bool GetFromSystem();
689  bool CheckIfRegistered();
690 
691  bool Register();
692 
694 
695  #if _WIN32
696  PString iconFileName;
697  PStringToString cmds;
698  #endif
699  };
701 
702  protected:
703  void Construct();
704 
705  // Member variables
706  bool m_library; // Indication PTLib is being used as a library for an external process.
707  int terminationValue; // Application return value
708 
709  PString manufacturer; // Application manufacturer name.
710  PString productName; // Application executable base name from argv[0]
711 
712  WORD majorVersion; // Major version number of the product
713  WORD minorVersion; // Minor version number of the product
714  CodeStatus status; // Development status of the product
715  WORD buildNumber; // Build number of the product
716 
717  PFilePath executableFile; // Application executable file from argv[0] (not open)
718  PStringArray configurationPaths; // Explicit file or set of directories to find default PConfig
719  PArgList arguments; // The list of arguments
720  int maxHandles; // Maximum number of file handles process can open.
721 
722  PTime programStartTime; // time at which process was intantiated, i.e. started
723 
725 
726  typedef std::map<PThreadIdentifier, PThread *> ThreadMap;
727  ThreadMap m_activeThreads;
729 
731 
732  PProcessIdentifier m_processID;
733 
734  friend class PThread;
735 
736 
737 // Include platform dependent part of class
738 #ifdef _WIN32
739 #include "msos/ptlib/pprocess.h"
740 #else
741 #include "unix/ptlib/pprocess.h"
742 #endif
743 };
744 
745 
748  class PLibraryProcess : public PProcess
749  {
750  PCLASSINFO(PLibraryProcess, PProcess);
751 
752  public:
758  const char * manuf = "",
759  const char * name = "",
760  WORD majorVersionNum = 1,
761  WORD minorVersionNum = 0,
762  CodeStatus statusCode = ReleaseCode,
763  WORD buildNum = 1
764  ) : PProcess(manuf, name, majorVersionNum, minorVersionNum, statusCode, buildNum, true) { }
766 
768  virtual void Main() { }
769 };
770 
771 
772 /*
773  * one instance of this class (or any descendants) will be instantiated
774  * via PGenericFactory<PProessStartup> one "main" has been started, and then
775  * the OnStartup() function will be called. The OnShutdown function will
776  * be called after main exits, and the instances will be destroyed if they
777  * are not singletons
778  */
779 class PProcessStartup : public PObject
780 {
782  public:
783  virtual void OnStartup() { }
784  virtual void OnShutdown() { }
785 };
786 
788 
789 #if PTRACING
790 
791 // using an inline definition rather than a #define crashes gcc 2.95. Go figure
792 #define P_DEFAULT_TRACE_OPTIONS ( PTrace::Blocks | PTrace::Timestamp | PTrace::Thread | PTrace::FileAndLine )
793 
794 template <unsigned level, unsigned options = P_DEFAULT_TRACE_OPTIONS >
795 class PTraceLevelSetStartup : public PProcessStartup
796 {
797  public:
798  void OnStartup()
799  { PTrace::Initialise(level, NULL, options); }
800 };
801 
802 #endif // PTRACING
803 
804 
805 #endif // PTLIB_PROCESS_H
806 
807 
808 // End Of File ///////////////////////////////////////////////////////////////
static PString GetLibVersion()
Get the version of the PTLib library the process is running on, eg "2.5beta3".
virtual bool OnInterrupt(bool terminating)
Callback for when a ^C (SIGINT) or termination request (SIGTERM) is received by process.
bool m_shuttingDown
Definition: pprocess.h:724
virtual const PString & GetName() const
Get the name of the process.
std::map< PThreadIdentifier, PThread * > ThreadMap
Definition: pprocess.h:726
virtual void Main()
< Dummy Main() as libraries do not have one.
Definition: pprocess.h:768
static void PreShutdown()
Internal shutdown function called directly from the ~PProcess InternalMain().
WORD buildNumber
Definition: pprocess.h:715
PTime programStartTime
Definition: pprocess.h:722
void QueueRequest(RequestType::Action action, PTimer *timer, bool isSync=true)
PString GetGroupName() const
Get the effective group name of the owner of the process, eg "root" etc.
static PString GetOSHardware()
Get the hardware the process is running on, eg "sparc".
PInt64 m_absoluteTime
Definition: pprocess.h:154
This class defines an arbitrary time interval to millisecond accuracy.
Definition: timeint.h:55
#define PCLASSINFO(cls, par)
Declare all the standard PTLib class information.
Definition: object.h:1049
Definition: pprocess.h:242
static PProcess & Current()
Get the current processes object instance.
PString productName
Definition: pprocess.h:710
This class defines an absolute time and date.
Definition: ptime.h:53
void SetIcon(const PString &icon)
bool m_library
Definition: pprocess.h:706
PFactory< PProcessStartup > PProcessStartupFactory
Definition: pprocess.h:787
This is a dictionary collection class of PString objects, keyed by another string.
Definition: pstring.h:2784
This class describes a full description for a file on the particular platform.
Definition: filepath.h:65
void SetTerminationValue(int value)
Set the termination value for the process.
Comparison
Result of the comparison operation performed by the Compare() function.
Definition: object.h:1184
static PString GetOSVersion()
Get the version of the operating system the process is running on, eg "2.0.33".
HostSystemURLHandlerInfo()
Definition: pprocess.h:673
PTimer * m_timer
Definition: pprocess.h:152
CodeStatus status
Definition: pprocess.h:714
PTimer::IDType GetNewTimerId() const
Definition: pprocess.h:134
virtual void Terminate()
Terminate the process.
Code is still very much under construction.
Definition: pprocess.h:237
RequestType(Action act, PTimer *t)
Definition: pprocess.h:143
static PString GetOSName()
Get the name of the operating system the process is running on, eg "Linux".
static void PostShutdown()
static void Initialise(unsigned level, const char *filename=NULL, unsigned options=Timestamp|Thread|Blocks)
Set the most common trace options.
PArgList & GetArguments()
Get the programme arguments.
virtual int InternalMain(void *arg=NULL)
Main function for process, called from real main after initialisation.
static PString GetOSClass()
Get the class of the operating system the process is running on, eg "unix".
static bool IsOSVersion(unsigned major, unsigned minor=0, unsigned build=0)
See if operating system is later than the version specified.
void ProcessTimerQueue()
This is an array collection class of PString objects.
Definition: pstring.h:2024
WORD minorVersion
Definition: pprocess.h:713
virtual void OnThreadEnded(PThread &thread)
Callback for when a thread is ended if wqas started in the PTLib system.
void SetCommand(const PString &key, const PString &command)
PBoolean SetMaxHandles(int newLimit)
Set the maximum number of file handles for the process.
virtual PString GetConfigurationFile()
Get the default file to use in PConfig instances.
virtual const PString & GetManufacturer() const
Get the name of the manufacturer of the software.
Comparison Compare(const PObject &obj) const
Compare two process instances.
PTimerList timers
Definition: pprocess.h:730
PString manufacturer
Definition: pprocess.h:709
Code is largely complete and is under test.
Definition: pprocess.h:239
This class represents an operating system process.
Definition: pprocess.h:227
A class representing a system timer.
Definition: timer.h:181
BOOL PBoolean
Definition: object.h:102
Class to represent a directory in the operating system file system.
Definition: pdirect.h:182
WORD majorVersion
Definition: pprocess.h:712
Definition: pprocess.h:106
void Construct()
PProcessIdentifier m_processID
Definition: pprocess.h:732
This class implements an integer that can be atomically incremented and decremented in a thread-safe ...
Definition: critsec.h:171
Action
Definition: pprocess.h:138
PTime GetStartTime() const
Return the time at which the program was started.
static PDirectory GetOSConfigDir()
Get the configuration directory of the operating system the process is running on, eg "/etc" for Unix, "c:\windows" for Win95 or "c:\winnt\system32\drivers\etc" for NT.
static PBoolean IsInitialised()
Determine if the current processes object instance has been initialised.
This class can be used to register various URL types with the host operating system so that URLs will...
Definition: pprocess.h:670
PLibraryProcess(const char *manuf="", const char *name="", WORD majorVersionNum=1, WORD minorVersionNum=0, CodeStatus statusCode=ReleaseCode, WORD buildNum=1)
Create a new process instance.
Definition: pprocess.h:757
PProcess(const char *manuf="", const char *name="", WORD majorVersion=1, WORD minorVersion=0, CodeStatus status=ReleaseCode, WORD buildNumber=1, bool library=false)
Create a new process instance.
Class for a process that is a dynamically loaded library.
Definition: pprocess.h:748
enum PTimerList::RequestType::Action m_action
virtual void SetThreadName(const PString &name)
Change the name of the thread.
PString GetUserName() const
Get the effective user name of the owner of the process, eg "root" etc.
The character string class.
Definition: pstring.h:108
int GetMaxHandles() const
Get the maximum file handle value for the process.
This class allows the parsing of a set of program arguments.
Definition: args.h:45
PTimerList * GetTimerList()
Get the list of timers handled by the application.
PTimer::IDType m_id
Definition: pprocess.h:153
This class defines a thread of execution in the system.
Definition: thread.h:66
PStringArray configurationPaths
Definition: pprocess.h:718
virtual void OnShutdown()
Definition: pprocess.h:784
PString GetCommand(const PString &key) const
PAtomicInteger::IntegerType m_serialNumber
Definition: pprocess.h:155
Template class for generic factories of an abstract class.
Definition: pfactory.h:144
virtual PString GetThreadName() const
Get the name of the thread.
PMutex m_activeThreadMutex
Definition: pprocess.h:728
PBoolean SetUserName(const PString &username, PBoolean permanent=false)
Set the effective owner of the process.
Definition: pprocess.h:136
Definition: pprocess.h:779
static PProcessIdentifier GetCurrentProcessID()
Get the platform dependent process identifier for the currentprocess.
const PFilePath & GetFile() const
Get the processes executable image file path.
Synonym for PTimedMutex.
PFilePath executableFile
Definition: pprocess.h:717
Definition: pprocess.h:139
Code has all known bugs removed and is shipping.
Definition: pprocess.h:241
PBoolean SetGroupName(const PString &groupname, PBoolean permanent=false)
Set the effective group of the process.
virtual void OnStartup()
Definition: pprocess.h:783
int maxHandles
Definition: pprocess.h:720
CodeStatus
Release status for the program.
Definition: pprocess.h:235
int terminationValue
Definition: pprocess.h:707
PArgList arguments
Definition: pprocess.h:719
PAtomicBase::IntegerType IntegerType
Definition: critsec.h:174
static bool RegisterTypes(const PString &types, bool force=true)
ThreadMap m_activeThreads
Definition: pprocess.h:727
HostSystemURLHandlerInfo(const PString &t)
Definition: pprocess.h:676
void SetConfigurationPath(const PString &path)
Set the default file or set of directories to search for use in PConfig.
PTimeInterval Process()
void PreInitialise(int argc, char **argv, char **envp)
Internal initialisation function called directly from InternalMain().
virtual void OnThreadStart(PThread &thread)
Callback for when a thread is started by the PTLib system.
Ultimate parent class for all objects in the class library.
Definition: object.h:1118
Definition: pprocess.h:140
PProcessIdentifier GetProcessID() const
Get the platform dependent process identifier for the process.
Definition: pprocess.h:425
PString type
Definition: pprocess.h:693
This class defines a thread synchronisation object.
Definition: syncpoint.h:67
virtual PString GetVersion(PBoolean full=true) const
Get the version of the software.
PSyncPoint * m_sync
Definition: pprocess.h:156
int GetTerminationValue() const
Get the termination value for the process.
unsigned IDType
Definition: timer.h:186