PTLib
Version 2.14.3
|
This class represents an operating system process. More...
#include <pprocess.h>
Classes | |
class | HostSystemURLHandlerInfo |
This class can be used to register various URL types with the host operating system so that URLs will automatically launch the correct application. More... | |
Public Member Functions | |
void | PreInitialise (int argc, char **argv) |
Internal initialisation function called directly from InternalMain() . More... | |
void | PreShutdown () |
Internal shutdown function called directly from the ~PProcess InternalMain() . More... | |
virtual int | InternalMain (void *arg=NULL) |
Main function for process, called from real main after initialisation. More... | |
PThread * | GetThread (PThreadIdentifier threadId) const |
bool | SignalTimerChange () |
~PProcess () | |
virtual void | PXOnSignal (int) |
virtual void | PXOnAsyncSignal (int) |
void | PXCheckSignals () |
Overrides from class PObject | |
Comparison | Compare (const PObject &obj) const |
Compare two process instances. More... | |
Overrides from class PThread | |
virtual void | Terminate () |
Terminate the process. More... | |
![]() | |
bool | IsAutoDelete () const |
int | PXBlockOnChildTerminate (int pid, const PTimeInterval &timeout) |
int | PXBlockOnIO (int handle, int type, const PTimeInterval &timeout) |
void | PXAbortBlock () const |
void | PrintOn (ostream &strm) const |
Standard stream print function. More... | |
PThread (PINDEX stack, AutoDeleteFlag deletion=AutoDeleteThread, Priority priorityLevel=NormalPriority, const PString &threadName=PString::Empty()) | |
Create a new thread instance. More... | |
~PThread () | |
Destroy the thread, this simply calls the Terminate() function with all its restrictions and penalties. More... | |
virtual void | Restart () |
Restart a terminated thread using the same stack priority etc that was current when the thread terminated. More... | |
virtual PBoolean | IsTerminated () const |
Determine if the thread has been terminated or ran to completion. More... | |
void | WaitForTermination () const |
Block and wait for the thread to terminate. More... | |
PBoolean | WaitForTermination (const PTimeInterval &maxWait) const |
Block and wait for the thread to terminate. More... | |
virtual void | Suspend (PBoolean susp=true) |
Suspend or resume the thread. More... | |
virtual void | Resume () |
Resume thread execution, this is identical to Suspend(false) . More... | |
virtual PBoolean | IsSuspended () const |
Determine if the thread is currently suspended. More... | |
virtual void | SetPriority (Priority priorityLevel) |
Set the priority of the thread relative to other threads in the current process. More... | |
virtual Priority | GetPriority () const |
Get the current priority of the thread in the current process. More... | |
virtual void | SetAutoDelete (AutoDeleteFlag deletion=AutoDeleteThread) |
Set the flag indicating thread object is to be automatically deleted when the thread ends. More... | |
void | SetNoAutoDelete () |
Reet the flag indicating thread object is to be automatically deleted when the thread ends. More... | |
virtual PString | GetThreadName () const |
Get the name of the thread. More... | |
virtual void | SetThreadName (const PString &name) |
Change the name of the thread. More... | |
virtual PThreadIdentifier | GetThreadId () const |
Get operating system specific thread identifier for this thread. More... | |
bool | GetTimes (Times ×) |
Get the thread execution times. More... | |
virtual void | Main ()=0 |
User override function for the main execution routine of the thread. More... | |
![]() | |
unsigned | GetTraceContextIdentifier () const |
Get PTRACE context identifier. More... | |
void | SetTraceContextIdentifier (unsigned id) |
void | GetTraceContextIdentifier (PObject &obj) |
void | GetTraceContextIdentifier (PObject *obj) |
void | SetTraceContextIdentifier (const PObject &obj) |
void | SetTraceContextIdentifier (const PObject *obj) |
virtual | ~PObject () |
virtual PObject * | Clone () const |
Create a copy of the class on the heap. More... | |
template<class CLS > | |
CLS * | CloneAs () const |
As for Clone() but converts to specified type. More... | |
virtual PINDEX | HashFunction () const |
This function yields a hash value required by the PDictionary class. More... | |
virtual const char * | GetClass (unsigned ancestor=0) const |
Get the current dynamic type of the object instance. More... | |
PBoolean | IsClass (const char *cls) const |
virtual PBoolean | InternalIsDescendant (const char *clsName) const |
Determine if the dynamic type of the current instance is a descendent of the specified class. More... | |
__inline const PObject * | PTraceObjectInstance () const |
virtual Comparison | CompareObjectMemoryDirect (const PObject &obj) const |
Determine the byte wise comparison of two objects. More... | |
bool | operator== (const PObject &obj) const |
Compare the two objects. More... | |
bool | operator!= (const PObject &obj) const |
Compare the two objects. More... | |
bool | operator< (const PObject &obj) const |
Compare the two objects. More... | |
bool | operator> (const PObject &obj) const |
Compare the two objects. More... | |
bool | operator<= (const PObject &obj) const |
Compare the two objects. More... | |
bool | operator>= (const PObject &obj) const |
Compare the two objects. More... | |
virtual void | ReadFrom (istream &strm) |
Input the contents of the object from the stream. More... | |
Static Public Member Functions | |
static void | PostShutdown () |
static void | PXShowSystemWarning (PINDEX code) |
static void | PXShowSystemWarning (PINDEX code, const PString &str) |
Operating System information functions | |
static PString | GetOSClass () |
Get the class of the operating system the process is running on, eg "unix". More... | |
static PString | GetOSName () |
Get the name of the operating system the process is running on, eg "Linux". More... | |
static PString | GetOSHardware () |
Get the hardware the process is running on, eg "sparc". More... | |
static PString | GetOSVersion () |
Get the version of the operating system the process is running on, eg "2.0.33". More... | |
static bool | IsOSVersion (unsigned major, unsigned minor=0, unsigned build=0) |
See if operating system is later than the version specified. More... | |
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. More... | |
static PString | GetLibVersion () |
Get the version of the PTLib library the process is running on, eg "2.5beta3". More... | |
![]() | |
static void | Sleep (const PTimeInterval &delay) |
Suspend the current thread for the specified amount of time. More... | |
static PThreadIdentifier | GetCurrentThreadId () |
static PThread * | Current () |
Get the currently running thread object instance. More... | |
static void | Yield () |
Yield to another thread without blocking. More... | |
static PThread * | Create (const PNotifier ¬ifier, INT parameter=0, AutoDeleteFlag deletion=AutoDeleteThread, Priority priorityLevel=NormalPriority, const PString &threadName=PString::Empty(), PINDEX stackSize=0) |
Create a simple thread executing the specified notifier. More... | |
static PThread * | Create (const PNotifier ¬ifier, const PString &threadName) |
Protected Types | |
typedef std::map < PThreadIdentifier, PThread * > | ThreadMap |
typedef PList< PThread > | ThreadList |
![]() | |
enum | Type { e_IsAutoDelete, e_IsManualDelete, e_IsProcess, e_IsExternal } |
typedef std::list< const LocalStorageBase * > | LocalStorageList |
Protected Member Functions | |
void | Construct () |
void | InternalThreadStarted (PThread *thread) |
void | InternalThreadEnded (PThread *thread) |
void | InternalSetAutoDeleteThread (PThread *thread) |
void | InternalCleanAutoDeleteThreads () |
void | HouseKeeping () |
PDICTIONARY (PXFdDict, POrdinalKey, PThread) | |
void | CommonConstruct () |
void | CommonDestruct () |
virtual void | _PXShowSystemWarning (PINDEX code, const PString &str) |
Protected Attributes | |
bool | m_library |
int | terminationValue |
PString | manufacturer |
PString | productName |
unsigned | majorVersion |
unsigned | minorVersion |
CodeStatus | status |
unsigned | buildNumber |
PFilePath | executableFile |
PStringArray | configurationPaths |
PArgList | arguments |
int | maxHandles |
PTime | programStartTime |
bool | m_shuttingDown |
PMutex | m_threadMutex |
ThreadMap | m_activeThreads |
ThreadList | m_autoDeleteThreads |
PAtomicBoolean | m_keepingHouse |
PThread * | m_houseKeeper |
PSyncPoint | m_signalHouseKeeper |
PTimer::List * | m_timerList |
PProcessIdentifier | m_processID |
uint32_t | m_pxSignals |
![]() | |
enum PThread::Type | m_type |
PINDEX | m_originalStackSize |
PString | m_threadName |
PMutex | m_threadNameMutex |
PThreadIdentifier | m_threadId |
LocalStorageList | m_localStorage |
![]() | |
unsigned | m_traceContextIdentifier |
Friends | |
PTimer::List * | PTimer::TimerList () |
void | PXSignalHandler (int) |
void | PXSigHandler (int) |
Construction | |
enum | CodeStatus { AlphaCode, BetaCode, ReleaseCode, NumCodeStatuses } |
Release status for the program. More... | |
PProcess (const char *manuf="", const char *name="", unsigned majorVersion=1, unsigned minorVersion=0, CodeStatus status=ReleaseCode, unsigned buildNumber=1, bool library=false, bool suppressStartup=false) | |
Create a new process instance. More... | |
Process information functions | |
void | Startup () |
Start up all items registered with PProcessStartupFactory. More... | |
virtual void | OnThreadStart (PThread &thread) |
Callback for when a thread is started by the PTLib system. More... | |
virtual void | OnThreadEnded (PThread &thread) |
Callback for when a thread is ended if wqas started in the PTLib system. More... | |
virtual bool | OnInterrupt (bool terminating) |
Callback for when a ^C (SIGINT), hangup (SIGHUP) or termination request (SIGTERM) is received by process. More... | |
void | SetTerminationValue (int value) |
Set the termination value for the process. More... | |
int | GetTerminationValue () const |
Get the termination value for the process. More... | |
PArgList & | GetArguments () |
Get the programme arguments. More... | |
virtual const PString & | GetManufacturer () const |
Get the name of the manufacturer of the software. More... | |
virtual const PString & | GetName () const |
Get the name of the process. More... | |
virtual PString | GetVersion (PBoolean full=true) const |
Get the version of the software. More... | |
const PFilePath & | GetFile () const |
Get the processes executable image file path. More... | |
PProcessIdentifier | GetProcessID () const |
Get the platform dependent process identifier for the process. More... | |
PTime | GetStartTime () const |
Return the time at which the program was started. More... | |
PString | GetUserName () const |
Get the effective user name of the owner of the process, eg "root" etc. More... | |
PBoolean | SetUserName (const PString &username, PBoolean permanent=false) |
Set the effective owner of the process. More... | |
PDirectory | GetHomeDirectory () const |
Get the "home" directory for the logged in user. More... | |
PString | GetGroupName () const |
Get the effective group name of the owner of the process, eg "root" etc. More... | |
PBoolean | SetGroupName (const PString &groupname, PBoolean permanent=false) |
Set the effective group of the process. More... | |
int | GetMaxHandles () const |
Get the maximum file handle value for the process. More... | |
PBoolean | SetMaxHandles (int newLimit) |
Set the maximum number of file handles for the process. More... | |
virtual PString | GetConfigurationFile () |
Get the default file to use in PConfig instances. More... | |
void | SetConfigurationPath (const PString &path) |
Set the default file or set of directories to search for use in PConfig. More... | |
static PProcess & | Current () |
Get the current processes object instance. More... | |
static PBoolean | IsInitialised () |
Determine if the current processes object instance has been initialised. More... | |
static PProcessIdentifier | GetCurrentProcessID () |
Get the platform dependent process identifier for the currentprocess. More... | |
Additional Inherited Members | |
![]() | |
enum | Priority { LowestPriority, LowPriority, NormalPriority, HighPriority, HighestPriority, NumPriorities } |
Codes for thread priorities. More... | |
enum | AutoDeleteFlag { AutoDeleteThread, NoAutoDeleteThread } |
Codes for thread autodelete flag. More... | |
![]() | |
enum | Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 } |
Result of the comparison operation performed by the Compare() function. More... | |
This class represents an operating system process.
This is a running "programme" in the context of the operating system. Note that there can only be one instance of a PProcess class in a given programme.
The instance of a PProcess or its GUI descendent PApplication
is usually a static variable created by the application writer. This is the initial "anchor" point for all data structures in an application. As the application writer never needs to access the standard system main()
function, it is in the library, the programmes execution begins with the virtual function PThread::Main()
on a process.
|
protected |
|
protected |
enum PProcess::CodeStatus |
PProcess::PProcess | ( | const char * | manuf = "" , |
const char * | name = "" , |
||
unsigned | majorVersion = 1 , |
||
unsigned | minorVersion = 0 , |
||
CodeStatus | status = ReleaseCode , |
||
unsigned | buildNumber = 1 , |
||
bool | library = false , |
||
bool | suppressStartup = false |
||
) |
Create a new process instance.
manuf | Name of manufacturer |
name | Name of product |
majorVersion | Major version number of the product |
minorVersion | Minor version number of the product |
status | Development status of the product |
buildNumber | Build number of the product |
library | PProcess is a library rather than an application |
suppressStartup | Do not execute Startup() |
PProcess::~PProcess | ( | ) |
|
protectedvirtual |
Reimplemented in PServiceProcess.
|
protected |
|
protected |
|
virtual |
Compare two process instances.
This should almost never be called as a programme only has access to a single process, its own.
EqualTo
if the two process object have the same name. obj | Other process to compare against. |
Reimplemented from PObject.
|
protected |
|
static |
Get the current processes object instance.
The current process is the one the application is running in.
PArgList& PProcess::GetArguments | ( | ) |
Get the programme arguments.
Programme arguments are a set of strings provided to the programme in a platform dependent manner.
|
virtual |
Get the default file to use in PConfig instances.
|
static |
Get the platform dependent process identifier for the currentprocess.
This is an arbitrary (and unique) integer attached to a process by the operating system.
const PFilePath& PProcess::GetFile | ( | ) | const |
Get the processes executable image file path.
PString PProcess::GetGroupName | ( | ) | const |
Get the effective group name of the owner of the process, eg "root" etc.
This is a platform dependent string only provided by platforms that are multi-user. Note that some value may be returned as a "simulated" user. For example, in MS-DOS an environment variable
PDirectory PProcess::GetHomeDirectory | ( | ) | const |
Get the "home" directory for the logged in user.
This checke dthe environment variable HOME first, and if not set tries to determine the home directory in a platform dependent manner.
|
static |
Get the version of the PTLib library the process is running on, eg "2.5beta3".
|
virtual |
Get the name of the manufacturer of the software.
This is used in the default "About" dialog box and for determining the location of the configuration information as used by the PConfig
class.
The default for this information is the empty string.
int PProcess::GetMaxHandles | ( | ) | const |
Get the maximum file handle value for the process.
For some platforms this is meaningless.
|
virtual |
Get the name of the process.
This is used in the default "About" dialog box and for determining the location of the configuration information as used by the PConfig
class.
The default is the title part of the executable image file.
|
static |
Get the class of the operating system the process is running on, eg "unix".
|
static |
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 |
Get the hardware the process is running on, eg "sparc".
|
static |
Get the name of the operating system the process is running on, eg "Linux".
|
static |
Get the version of the operating system the process is running on, eg "2.0.33".
|
inline |
Get the platform dependent process identifier for the process.
This is an arbitrary (and unique) integer attached to a process by the operating system.
References m_processID.
PTime PProcess::GetStartTime | ( | ) | const |
Return the time at which the program was started.
int PProcess::GetTerminationValue | ( | ) | const |
Get the termination value for the process.
The termination value is an operating system dependent integer which indicates the processes termiantion value. It can be considered a "return value" for an entire programme.
PThread* PProcess::GetThread | ( | PThreadIdentifier | threadId | ) | const |
PString PProcess::GetUserName | ( | ) | const |
Get the effective user name of the owner of the process, eg "root" etc.
This is a platform dependent string only provided by platforms that are multi-user. Note that some value may be returned as a "simulated" user. For example, in MS-DOS an environment variable
Get the version of the software.
This is used in the default "About" dialog box and for determining the location of the configuration information as used by the PConfig
class.
If the full
parameter is true then a version string built from the major, minor, status and build veriosn codes is returned. If false then only the major and minor versions are returned.
The default for this information is "1.0".
full | true for full version, false for short version. |
|
protected |
|
protected |
|
virtual |
Main function for process, called from real main after initialisation.
Reimplemented in PServiceProcess.
|
protected |
|
protected |
|
protected |
|
static |
Determine if the current processes object instance has been initialised.
If this returns true it is safe to use the PProcess::Current() function.
|
static |
See if operating system is later than the version specified.
major | Major version number |
minor | Minor version number |
build | Build number |
|
virtual |
Callback for when a ^C (SIGINT), hangup (SIGHUP) or termination request (SIGTERM) is received by process.
Note this function is called asynchronously and there may be many limitations on what can and cannot be done depending on the underlying operating system. It is recommeneded that this does no more than set flags and return.
Default behaviour returns false and the process is killed.
terminating | true if process terminating. |
|
virtual |
Callback for when a thread is ended if wqas started in the PTLib system.
Note this is called in the context of the old thread.
|
virtual |
Callback for when a thread is started by the PTLib system.
Note this is called in the context of the new thread.
|
protected |
|
static |
void PProcess::PreInitialise | ( | int | argc, |
char ** | argv | ||
) |
Internal initialisation function called directly from InternalMain()
.
The user should never call this function.
void PProcess::PreShutdown | ( | ) |
Internal shutdown function called directly from the ~PProcess InternalMain()
.
The user should never call this function.
void PProcess::PXCheckSignals | ( | ) |
|
virtual |
Reimplemented in PServiceProcess.
|
virtual |
Reimplemented in PServiceProcess.
|
static |
|
static |
void PProcess::SetConfigurationPath | ( | const PString & | path | ) |
Set the default file or set of directories to search for use in PConfig.
To find the .ini file for use in the default PConfig() instance, this explicit filename is used, or if it is a set of directories separated by either ':' or ';' characters, depending on platform, then the application base name postfixed with ".ini" is searched for through those directories.
The search is actually done when the GetConfigurationFile() is called, this function only sets the internal variable.
Note for Windows, a path beginning with "HKEY_LOCAL_MACHINE\\" or "HKEY_CURRENT_USER\\" will actually search teh system registry for the application base name only (no ".ini") in that folder of the registry.
path | Explicit file or set of directories |
Set the effective group of the process.
This is a platform dependent string only provided by platforms that are multi-user.
For unix systems if the groupname may consist exclusively of digits and there is no actual groupname consisting of that string then the numeric uid value is used. For example "0" is the superuser. For the rare occassions where the groups name is the same as their uid, if the groupname field starts with a '#' then the numeric form is forced.
If an empty string is provided then original group that executed the process in the first place (the real group) is set as the effective group.
The permanent flag indicates that the group will not be able to simply change back to the original group as indicated above, ie for unix systems setgid() is used instead of setegid(). This is not necessarily meaningful for all platforms.
groupname | New group name or gid |
permanent | Flag for if effective or real group |
PBoolean PProcess::SetMaxHandles | ( | int | newLimit | ) |
Set the maximum number of file handles for the process.
For unix systems the user must be run with the approriate privileges before this function can set the value above the system limit.
For some platforms this is meaningless.
newLimit | New limit on file handles |
void PProcess::SetTerminationValue | ( | int | value | ) |
Set the termination value for the process.
The termination value is an operating system dependent integer which indicates the processes termiantion value. It can be considered a "return value" for an entire programme.
value | Value to return a process termination status. |
Set the effective owner of the process.
This is a platform dependent string only provided by platforms that are multi-user.
For unix systems if the username may consist exclusively of digits and there is no actual username consisting of that string then the numeric uid value is used. For example "0" is the superuser. For the rare occassions where the users name is the same as their uid, if the username field starts with a '#' then the numeric form is forced.
If an empty string is provided then original user that executed the process in the first place (the real user) is set as the effective user.
The permanent flag indicates that the user will not be able to simple change back to the original user as indicated above, ie for unix systems setuid() is used instead of seteuid(). This is not necessarily meaningful for all platforms.
username | New user name or uid |
permanent | Flag for if effective or real user |
bool PProcess::SignalTimerChange | ( | ) |
void PProcess::Startup | ( | ) |
Start up all items registered with PProcessStartupFactory.
|
virtual |
Terminate the process.
Usually only used in abnormal abort situation.
Reimplemented from PThread.
Reimplemented in PServiceProcess.
|
friend |
|
friend |
|
friend |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
Referenced by GetProcessID().
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |