PTLib  Version 2.10.11
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;
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;
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 {
230 
231  public:
234  enum CodeStatus {
242  NumCodeStatuses
243  };
244 
247  PProcess(
248  const char * manuf = "",
249  const char * name = "",
250  WORD majorVersion = 1,
251  WORD minorVersion = 0,
252  CodeStatus status = ReleaseCode,
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 
369  PArgList & GetArguments();
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 
472  PBoolean SetUserName(
473  const PString & username,
474  PBoolean permanent = false
475  );
476 
485  PString GetGroupName() const;
486 
511  PBoolean SetGroupName(
512  const PString & groupname,
513  PBoolean permanent = false
514  );
515 
522  int GetMaxHandles() const;
523 
533  PBoolean SetMaxHandles(
534  int newLimit
535  );
536 
537 #ifdef P_CONFIG_FILE
538 
540  virtual PString GetConfigurationFile();
541 #endif
542 
556  void SetConfigurationPath(
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 
629  PTimerList * GetTimerList();
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  {
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 ///////////////////////////////////////////////////////////////
bool m_shuttingDown
Definition: pprocess.h:724
std::map< PThreadIdentifier, PThread * > ThreadMap
Definition: pprocess.h:726
virtual void Main()
< Dummy Main() as libraries do not have one.
Definition: pprocess.h:768
WORD buildNumber
Definition: pprocess.h:715
PTime programStartTime
Definition: pprocess.h:722
void QueueRequest(RequestType::Action action, PTimer *timer, bool isSync=true)
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
PString productName
Definition: pprocess.h:710
This class defines an absolute time and date.
Definition: ptime.h:53
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
Comparison
Result of the comparison operation performed by the Compare() function.
Definition: object.h:1184
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
Code is still very much under construction.
Definition: pprocess.h:237
RequestType(Action act, PTimer *t)
Definition: pprocess.h:143
static void Initialise(unsigned level, const char *filename=NULL, unsigned options=Timestamp|Thread|Blocks)
Set the most common trace options.
void ProcessTimerQueue()
This is an array collection class of PString objects.
Definition: pstring.h:2024
WORD minorVersion
Definition: pprocess.h:713
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
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
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
Class for a process that is a dynamically loaded library.
Definition: pprocess.h:748
enum PTimerList::RequestType::Action m_action
The character string class.
Definition: pstring.h:108
This class allows the parsing of a set of program arguments.
Definition: args.h:45
virtual Comparison Compare(const PObject &obj) const
Compare the two objects and return their relative rank.
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
PAtomicInteger::IntegerType m_serialNumber
Definition: pprocess.h:155
Template class for generic factories of an abstract class.
Definition: pfactory.h:144
PMutex m_activeThreadMutex
Definition: pprocess.h:728
Definition: pprocess.h:136
Definition: pprocess.h:779
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
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
ThreadMap m_activeThreads
Definition: pprocess.h:727
HostSystemURLHandlerInfo(const PString &t)
Definition: pprocess.h:676
PTimeInterval Process()
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
PSyncPoint * m_sync
Definition: pprocess.h:156
unsigned IDType
Definition: timer.h:186