FX::FXProcess Class Reference

#include <FXProcess.h>

Detailed Description

Provides process-wide information and control.

Where FXApp initialises the GUI subsystem, FXProcess initialises just those parts sufficient for command-line operation. Probably one of its most useful facilities is FXProcess_StaticInit which is used by a number of internal classes already.

FXProcess should be initialised first thing into main():

int main(int argc, char *argv[])
{
    FXProcess myprocess(argc, argv);
    FXApp app("name");      // Only for GUI apps
    app.init(argc, argv);   // Only for GUI apps
    ...
    app.create();           // Only for GUI apps
    ...
    return app.run();       // Only for GUI apps
}

Dynamic library facilities

You should use dllLoad() to load dynamic libraries - this loads and runs any FXProcess_StaticInit's the newly loaded library may have. If you manage your own loading, call runPendingStaticInits(). The search behaviour on POSIX is different than that for dlopen() - if a relative path, it emulates Windows by searching around where the executable is, then the current directory, then dlopen()'s default. It also tries appending .so if one isn't present already as well as prepending lib - this behaviour ensures that equivalent behaviour occurs both on Windows and POSIX. Watch out for calling DLL's the same as executables - on POSIX, there is no .exe extension to differentiate.

Once loaded you can resolve symbols using dllHandle::dllResolve() which returns a functor for that API. Note that C++ mangles its API names so you will have to specify extern "C" before their declaration in your DLL.

Free system resources

hostOSProcessorLoad(), hostOSMemoryLoad() and hostOSDiscIOLoad() allow your code to determine how free the system is in those areas. This can be used to dynamically adjust whether to use lots of memory and a fast algorithm or little memory and a slow algorithm.

A few parts of TnFOX use the convenience functions processorFull(), memoryFull() and discIOFull() but this facility is mostly intended for Tn. These functions return an integer index whereby zero is not full, one is getting full, two is nearly full and three is full and over. These numbers can be included in calculations as divisors of buffer sizes etc.

Note:: hostOSProcessLoad() and hostDiscIOLoad() are currently unimplemented. At some stage I'll do like FXSecure and maintain a shared memory region with the last five seconds of data from which meaningful values can be constructed.

Process-wide thread pool

A process-wide thread pool consisting of four threads is available at FXProcess::threadPool() and is created on first use. FX::QThreadPool offers timed callback facilities which are used by other code such as FX::FXFSMonitor. Once created, the thread pool lasts until the process terminates.

Security:

On POSIX, there is the weird and wonderful world of real and effective user ids and groups. Basically the real id of a process is under which user's shell it is running whereas the effective id is which user the process is impersonating. It gets more complex again on Linux because a process can impersonate someone different again only when accessing the file system. This does not in my mind make for easy security - and worst of all, you can't change these impersonation settings on a per-thread basis, only on a per-process one.

Hence we are substantially limited in what we can do whilst keeping semantics similar between NT and POSIX - unfortunately we need the ability to run as root but act like someone else because the Tn kernel can run as a daemon/service and the secure heap needs to be able to lock memory pages. I've decided that if the filing system is accessed like the real uid and TnFOX's ACL based security support forces the owner on all things it touches to be the real uid, it's safe to run the process with the suid bit set (ie; acting like root). Of course, users may not agree with this :)

Note:: userHandedness() is currently only implemented for Windows


Public Types
enum	UserHandedness { UNKNOWN_HANDED, LEFT_HANDED, RIGHT_HANDED }
typedef QValueList < MappedFileInfo >	MappedFileInfoList
typedef Generic::Functor < Generic::TL::create< void, bool >::value >	FatalExitUpcallSpec
Public Member Functions
	FXProcess ()
	FXProcess (int &argc, char *argv[])
bool	runPendingStaticInits (int &argc, char *argv[], FXStream &txtout)
Static Public Member Functions
static void	exit (FXint code=0)
static bool	isAutomatedTest () throw ()
static FXProcess *	instance ()
static FXuint	getMsCount ()
static void	getTimeOfDay (struct timeval *ts)
static FXulong	getNsCount ()
static FXuint	id ()
static FXuint	noOfProcessors ()
static FXuint	pageSize ()
static MappedFileInfoList	mappedFiles (bool forceRefresh=false)
static const FXString &	execpath ()
static FXString	dllPath (void addr, void dllstart=0, void *dllend=0)
static dllHandle	dllLoad (const FXString &path)
static void *	dllResolveBase (const dllHandle &h, const char *apiname)
static void	dllUnload (dllHandle &h)
static FXString	hostOS (FXString myos=0, FXString architecture=0)
static FXString	hostOSDescription (FXString myapi=0, FXString kernelname=0, FXString kernelversion=0, FXString apiversion=0, FXString *architecture=0)
static void	buildInfo (int *svnrev=0)
static FXfloat	hostOSProcessorLoad ()
static FXuint	processorFull ()
static FXfloat	hostOSMemoryLoad (FXuval *totalPhysMem=0)
static FXuint	memoryFull ()
static FXfloat	hostOSDiscIOLoad (const FXString &path)
static FXfloat	hostOSDiskIOLoad (const FXString &path)
static FXuint	discIOFull (const FXString &path)
static FXuint	diskIOFull (const FXString &path)
static void	overrideFreeResources (FXfloat memory=-1, FXfloat processor=-1, FXfloat discio=-1)
static FXuval	virtualAddrSpaceLeft (FXuval chunk=1)
static QValueList < MountablePartition >	mountablePartitions ()
static void	mountPartition (const FXString &partitionName, const FXString &location=FXString::nullStr(), const FXString &fstype=FXString::nullStr(), bool readWrite=true)
static void	unmountPartition (const FXString &location)
static QThreadPool &	threadPool ()
static UserHandedness	userHandedness ()
static void	overrideUserHandedness (UserHandedness val)
static FXuint	screenScale (FXuint value)
static void	overrideScreenScale (FXuint percent)
static void	overrideScreenSize (FXint w, FXint h)
static void	addFatalExitUpcall (FatalExitUpcallSpec upcallv)
static bool	removeFatalExitUpcall (FatalExitUpcallSpec upcallv)
static QMemArray< void * >	lockedPages ()
static void	int_addStaticInit (FXProcess_StaticInitBase *o)
static void	int_removeStaticInit (FXProcess_StaticInitBase *o)
static void	int_addStaticDepend (FXProcess_StaticDepend *d)
Friends
class	FXProcess_MemLock
class	FXWindow
class	FXShell
Classes
class	dllHandle
struct	MappedFileInfo
	A structure containing information about a mapped file. More...
struct	MountablePartition
	Information about a mountable partition. More...

Member Typedef Documentation

typedef QValueList<MappedFileInfo> FX::FXProcess::MappedFileInfoList

Defines a list of FXProcess::MappedFileInfo.

typedef Generic::Functor<Generic::TL::create<void, bool>::value> FX::FXProcess::FatalExitUpcallSpec

The specification of the fatal exit vector.

Member Enumeration Documentation

enum FX::FXProcess::UserHandedness

Indicates which hand the user is.

Constructor & Destructor Documentation

FX::FXProcess::FXProcess ( )

Initialises the process.

Member Function Documentation

static void FX::FXProcess::exit ( FXint code = 0 ) [static]

Cleans up the process and exits the process.

bool FX::FXProcess::runPendingStaticInits	(	int &	argc,
		char *	argv[],
		FXStream &	txtout
	)

Runs any pending static inits. Only required if you implement your own shared library loading.

static bool FX::FXProcess::isAutomatedTest ( ) throw () [static]

Is application an automated test?

static FXProcess* FX::FXProcess::instance ( ) [static]

Returns a pointer to the TProcess for this process.

static FXuint FX::FXProcess::getMsCount ( ) [static]

Returns a millisecond count. This number will wrap approximately every 50 days.

Referenced by FX::QShrdMemMutex::lock().

static void FX::FXProcess::getTimeOfDay ( struct timeval * ts ) [static]

Fills in the specified timeval structure with the current time.

static FXulong FX::FXProcess::getNsCount ( ) [static]

Returns a nanosecond count. It is highly unlikely that this timer is actually nanosecond accurate, but you have a good chance it is at least microsecond accurate. On systems which do not support high resolution timers, this returns getMsCount() multiplied by one million. You should not rely on this counter having its full 64 bit range ie; it may wrap sooner on some systems

static FXuint FX::FXProcess::id ( ) [static]

Returns the unique id of this process within the system.

static FXuint FX::FXProcess::noOfProcessors ( ) [static]

Returns the number of processors available to this process.

Referenced by FX::QMutex::QMutex().

static FXuint FX::FXProcess::pageSize ( ) [static]

Returns the size of a memory page on this machine.

static MappedFileInfoList FX::FXProcess::mappedFiles ( bool forceRefresh = false ) [static]

Returns a list of files currently mapped into this process. As this call is slow, a cache is maintained and updated accordingly when dllLoad() and dllUnload() are used. If however you wish to bypass the cache, call with forceRefresh set to true

static const FXString& FX::FXProcess::execpath ( ) [static]

Returns a full path to the currently running executable.

static FXString FX::FXProcess::dllPath	(	void *	addr,
		void **	dllstart = `0`,
		void **	dllend = `0`
	)			`[static]`

Returns a full path to the binary containing the specified address with optional return of start and end addresses of the binary map

Warning:: This is not an especially fast call

static dllHandle FX::FXProcess::dllLoad ( const FXString & path ) [static]

Loads in the specified dynamic library and initialises its static data. The handle returns automatically calls dllUnload() on destruction if it hadn't been already closed.

static void* FX::FXProcess::dllResolveBase	(	const dllHandle &	h,
		const char *	apiname
	)			`[static]`

Resolves the specified symbol in the given library to its address. The dllHandle::resolve() forms should be preferred to this as they are typesafe and much easier to use.

Referenced by FX::FXProcess::dllHandle::resolve().

static void FX::FXProcess::dllUnload ( dllHandle & h ) [static]

Unloads the specified dynamic library.

static FXString FX::FXProcess::hostOS	(	FXString *	myos = `0`,
		FXString *	architecture = `0`
	)			`[static]`

Returns a short description of the operating system eg; "Win32", "Linux" etc that TnFOX was built for with a slash '/' and then the machine architecture TnFOX was built for. This can vary from hostOSDescription() below.

static FXString FX::FXProcess::hostOSDescription	(	FXString *	myapi = `0`,
		FXString *	kernelname = `0`,
		FXString *	kernelversion = `0`,
		FXString *	apiversion = `0`,
		FXString *	architecture = `0`
	)			`[static]`

Returns a textual description of the host operating system. The format is as follows:

<API name> (<kernel name> [kernel version] kernel) version <API version>, <machine architecture> architecture

API name can be one of the following:

Win32
Win64
POSIX.2

The kernel name is whatever the operating system says it is (eg; 9x, NT, Linux) and the kernel version is whatever the operating system thinks it is. API version for Windows generally follows 4.x for Windows 95/NT until Windows 2000 where it becomes 5.x. For POSIX, it is always POSIX.2 meaning v2 but the API version is whatever the operating system reports itself as compliant with. The point to remember is this function is concerned with API version which is in fact all you need know about as well even in non-portable code.

Lastly, machine architecture currently can be one of: i486, PowerPC, Alpha, IA64, AMD64, unknown.

static void FX::FXProcess::buildInfo ( int * svnrev = 0 ) [static]

Returns build information for TnFOX. svnrev is the latest SVN revision of the repository from which TnFOX was checked out. Note this can be -1 if svnversion wasn't available during build

static FXfloat FX::FXProcess::hostOSProcessorLoad ( ) [static]

Returns a normalised floating-point value whereby 1.0 means full. System processors are combined so that CPU A at 100% and CPU B at 0% yields the same return as both CPU's being at 50%

Note:: Currently not implemented

static FXuint FX::FXProcess::processorFull ( ) [inline, static]

Returns an index 0...3 of how full the processor is.

static FXfloat FX::FXProcess::hostOSMemoryLoad ( FXuval * totalPhysMem = 0 ) [static]

Returns a normalised floating-point value whereby 1.0 means full. On Windows this is the total virtual memory allocation versus physical memory installed. On Linux this is (used-cached)+swap used versus physical memory installed. If totalPhysMem is set, returns the total physical memory in the machine

static FXuint FX::FXProcess::memoryFull ( ) [inline, static]

Returns an index 0...3 of how full the memory is.

static FXfloat FX::FXProcess::hostOSDiscIOLoad ( const FXString & path ) [static]

Returns a normalised floating-point value whereby 1.0 means full.

Note:: Currently not implemented

static FXuint FX::FXProcess::discIOFull ( const FXString & path ) [inline, static]

Returns an index 0...3 of how full the disc i/o is.

static void FX::FXProcess::overrideFreeResources	(	FXfloat	memory = `-1`,
		FXfloat	processor = `-1`,
		FXfloat	discio = `-1`
	)			`[static]`

Lets you override the values returned by the free system resources functions. Use a negative number to reset to dynamic calculation

static FXuval FX::FXProcess::virtualAddrSpaceLeft ( FXuval chunk = 1 ) [static]

Returns an estimation of virtual address space remaining in this process if chunks are allocated in size chunk. How this is implemented is highly system specific and for some systems is quite hackish so the value can vary by +-5% depending on what thread is calling it and such. At least two allocations of size chunk will need to be temporarily made and the returned value assumes that there are no other allocations between that chunk and the end of address space which clearly can be wildly out. On all supported platforms actual increases in the memory usage of your process can be avoided. You probably want to avoid calling this too frequently as it involves multiple calls into kernel space.

static QValueList<MountablePartition> FX::FXProcess::mountablePartitions ( ) [static]

Returns a list of partitions on the host operating system. Note that this may not be a definitive list eg; if /etc/fstab does not map all possible partitions, then this list will be incomplete. Superuser permissions is required to get a definitive list and it isn't usually needed by applications

static void FX::FXProcess::mountPartition	(	const FXString &	partitionName,
		const FXString &	location = `FXString::nullStr()`,
		const FXString &	fstype = `FXString::nullStr()`,
		bool	readWrite = `true`
	)			`[static]`

Mounts a partition.

static void FX::FXProcess::unmountPartition ( const FXString & location ) [static]

Unmounts a partition.

static QThreadPool& FX::FXProcess::threadPool ( ) [static]

Returns the process-wide thread pool.

static UserHandedness FX::FXProcess::userHandedness ( ) [static]

Returns the "handedness" of the user.

Referenced by FX::FXWindow::userHandednessLayout().

static void FX::FXProcess::overrideUserHandedness ( UserHandedness val ) [static]

Overrides the "handedness" setting of the user.

static FXuint FX::FXProcess::screenScale ( FXuint value ) [static]

Scales your window layout distances according to the screen size - this can vary from 400% to 25%. You should not scale content size with this metric!

Referenced by FX::FXWindow::defaultPadding(), FX::FXWindow::defaultSpacing(), and FX::FXWindow::scaleLayoutValue().

static void FX::FXProcess::overrideScreenScale ( FXuint percent ) [static]

Overrides the screen size scaling factor.

static void FX::FXProcess::overrideScreenSize	(	FXint	w,
		FXint	h
	)			`[static]`

Overrides the screen size (debug only).

static void FX::FXProcess::addFatalExitUpcall ( FatalExitUpcallSpec upcallv ) [static]

Registers code to be called when a process exits, even from a hard error such as segmentation fault. The form of the code is:

    void function(bool);
    void Object::member(bool);

The parameter is true when the exit is fatal, false if the exit is normal. As this may be called in the context of a signal, do not do anything involved at all. If you want to get called on normal process exit, consider atexit() or FX::FXProcess_StaticInit.

static bool FX::FXProcess::removeFatalExitUpcall ( FatalExitUpcallSpec upcallv ) [static]

Unregisters a previously installed call upon process exit.

static QMemArray<void *> FX::FXProcess::lockedPages ( ) [static]

Returns a list of pages in this process which are locked into memory.

The documentation for this class was generated from the following file:

FXProcess.h

FX::FXProcess Class Reference

Detailed Description

Dynamic library facilities

Free system resources

Process-wide thread pool

Security:

Public Types

Public Member Functions

Static Public Member Functions

Friends

Classes

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation