Errors
PIDLL_delete
PIDLL_getAddress
PIDLL_getErrorDescription
PIDLL_getSystemHandle()
PIDLL_isLoaded
PIDLL_new
PIFInfo_delete
PIFInfo_exists
PIFInfo_getAlternateName
PIFInfo_getExtension
PIFInfo_getFirstFileInDirectory
PIFInfo_getLastModified
PIFInfo_getName
PIFInfo_getNextFileInDirectory
PIFInfo_getPath
PIFInfo_getPathRoot
PIFInfo_getSize
PIFInfo_isDirectory
PIFInfo_isExecutable
PIFInfo_isLink
PIFInfo_isReadable
PIFInfo_isRegular
PIFInfo_isWritable
PIFInfo_new
PIFMap_delete
PIFMap_lock
PIFMap_new
PIFMap_unlock
PIFile_close
PIFile_open
PIFile_read
PIFile_unlink
PIFile_write
PIFile_writeAtomic
PIPlatform_advisaryLockFd
PIPlatform_advisaryUnlockFd
PIPlatform_afterUnsafeBlock
PIPlatform_allocLocalMutex
PIPlatform_allocLocalSemaphore
PIPlatform_beforeUnsafeBlock
PIPlatform_catchExceptions
PIPlatform_enter
PIPlatform_getCurrentDirectory
PIPlatform_getDescription
PIPlatform_getDirectorySeparator
PIPlatform_getLastError
PIPlatform_getProcess
PIPlatform_getProcessId
PIPlatform_getUniqueId
PIPlatform_pollFD
PIPlatform_pollNetFD
PIPlatform_pollPipeFD
PIPlatform_setLastError
PIPlatform_sleep
PIPlatform_waitForProcess
PISync_delete
PISync_lock
PISync_tryLock
PISync_unlock
PIThread_begin
PIThread_dbgDump
PIThread_delete
PIThread_destroyThreadKey
PIThread_getCurrent
PIThread_getData
PIThread_getMain
PIThread_getPriority
PIThread_getSystemHandle
PIThread_initThreadKey
PIThread_new
PIThread_resume
PIThread_setData
PIThread_setPriority
PIThread_suspend
PIThread_terminate
PIThread_userYield
PIThread_waitForThread
PIThread_yield
PITimer_delete
PITimer_elapsed
PITimer_new
PITimer_reset
PIUtil_free
PIUtil_malloc
PIUtil_strdup
PIUtil_stricmp
PIUtil_strncmpi


Name:
Errors

Synopsis:

Description:

Notes:
Error codes are maintained on a per-thread basis and can be set and examined using PIPlatform_getLastError() and PIPlatform_setLastError() respectively. The following are the error codes used and thier meanings.
PIAPI_ERROR an unspecified error, use operating system facilities to further isolate the error.
PIAPI_EXHAUSTED memory or disk space exhausted.
PIAPI_EINVAL invalid parameter
PIAPI_NOTSUPPORTED unimplemented facilitiy
PIAPI_EEXIST a file or other object cannot be created because some object already exists which the creation would corrupt.
PIAPI_EACCES access denied
PIAPI_EINIT library not correctly initialised.
PIAPI_DEADLOCK action would leave no runnable threads.


Name:
PIDLL_delete

Synopsis:
int PIDLL_delete( PIDLL *pDLL )

Description:
Destroys and free memory associated with the dynamic link object pDLL.

Notes:
Whether or not the DLL is unloaded from the address space of the process is implementation specific. Typically a DLL only becomes unloaded when the load reference count reaches zero.

Return Values:
On success PIDLL_delete() returns zero (PIAPI_COMPLETED).

Errors:
On error PIDLL_delete() returns a negative value. More specific error information can be retrieved using PIPlatform_getLastError().

See Also:
PIDLL_new

Return to index


Name:
PIDLL_getAddress

Synopsis:
void *PIDLL_getAddress( PIDLL *pDLL, const char *pSymbolName )

Description:
Returns the address of symbol pSymbolName is the DLL pDLL.

Notes:
This function is intended primarily for retrieving the address of functions with "C" linkage.

Return Values:
On success PIDLL_getAddress() returns a pointer to the memory address of the required symbol.

Errors:
PIDLL_getAddress returns NULL if the address of the function could not be retrieved. More specific error information can be retrieved using PIPlatform_getLastError(). Additionally the PIDLL_getErrorDescription() can be used to get an english description of the last error.

See Also:

Return to index


Name:
PIDLL_getErrorDescription

Synopsis:
const char *PIDLL_getErrorDescription( const PIDLL *pDLL )

Description:
Returns an english description of the last error which occurred when performing a DLL operation.

Notes:
The error message string is allocate by the DLL object and is invalided by invoking another operation on that DLL or destroying the DLL object with PIDLL_delete().

Return Values:
PIDLL_getErrorDescription() always returns an error description.

Errors:
None.

See Also:

Return to index


Name:
PIDLL_getSystemHandle()

Synopsis:
void *PIDLL_getSystemHandle( const PIDLL *pDLL )

Description:
Returns the operating system specific handle of the DLL.

Notes:

Return Values:
Returns the operating system specific handle of the DLL.

Errors:
None.

See Also:

Return to index


Name:
PIDLL_isLoaded

Synopsis:
int PIDLL_isLoaded( const PIDLL *pDLL )

Description:
Indicates whether or not a new DLL object actually represents a loaded dynamic link library.

Notes:

Return Values:
PIDLL_isLoaded() returns either PIAPI_TRUE or PIAPI_FALSE. If PIAPI_FALSE is returned and no error code is set (see below), the function PIDLL_getErrorDescription() can be used to get a text description of the reason the library could not be loaded.

Errors:
On error PIDLL_isLoaded() returns PIAPI_FALSE and sets the error code to a value other than PIAPI_COMPLETED. This error code may be retrieved using PIPlatform_getLastError().

See Also:
PIDLL_new

Return to index


Name:
PIDLL_new

Synopsis:
PIDLL *PIDLL_new( const char *pPath )

Description:
Create a new dynamic link library object by loading the library pointed to by pPath.

Notes:

Return Values:
On success PIDLL_new returns a pointer to a new dynamic link library.

Errors:
If pPath is NULL or memory cannot be allocated PIDLL_new() will return NULL. More specific error information can be retrieved using PIPlatform_getLastError().

See Also:
PIDLL_delete

Return to index


Name:
PIFInfo_delete

Synopsis:
int PIFInfo_delete( PIFInfo *pFileInfo );

Description:
Destroys an PIFInfo object and free any memory associated with it.

Notes:
Using pFileInfo for any further operations after PIFInfo_delete() has been used will cause undefined behaviour.

Return Values:
On success PIFInfo_delete() returns zero (PIAPI_COMPLETED).

Errors:
On error PIFInfo_delete() will return a non-zero value. The function PIPlatform_getLastError() can be used to retreve more specific error information.

See Also:
PIFInfo_new

Return to index


Name:
PIFInfo_exists

Synopsis:
int PIFInfo_exists( PIFInfo *pFileInfo )

Description:
Specifies whether or not the file information object pFileInfo refers to a file that actually exists.

Notes:
Always compare this return code against PIAPI_TRUE as some error return value may be non-negative.

Return Values:
On success PIFInfo_exists() returns either PIAPI_TRUE or PIAPI_FALSE, indicating whether or not a file respresented by pFileInfo exists.

Errors:
This function does not generate an error.

See Also:
PIFInfo_isRegular PIFInfo_isReadable PIFInfo_isDirectory PIFInfo_isLink

Return to index


Name:
PIFInfo_getAlternateName

Synopsis:
const char *PIFInfo_getAlternateName( PIFInfo *pFileInfo )

Description:
Returns the alternet name of the file referred to by pFileInfo.

Notes:
Some operating systems maintain alternate filenames for files. This function can be used to access the alternate filename. When the operating system does not define an alternate file PIFInfo_getAlternateName() behaves as PIFInfo_getName().

Return Values:
On sucess PIFInfo_getAlternateName() returns a non-NULL pointer to the alternate filename.

Errors:
On error PIFInfo_getAlternateName() returns NULL. The function PIPlatform_getLastError() can be used to retrieve more specific error information.

See Also:
PIFInfo_getPath

Return to index


Name:
PIFInfo_getExtension

Synopsis:
const char *PIFInfo_getExtension( PIFInfo *pFileInfo )

Description:
Returns the extension of the file represented by pFileInfo. A file extension is the sequence of characters following the last period ('.') in the filename, when scanning left to right.

Notes:
PIFInfo_getExtension() may operate correctly even when pFileInfo does not represent a real file. The returned value is a pointer to a component of the filename as represented internally in the PIFInfo object. Some functions such as PIFInfo_delete() will cause this pointer to become invalid.

Return Values:
On success PIFInfo_getExtension() returns the extension of the file. If the file does not have an extension this will be the empty string ("").

Errors:
If pFileInfo is NULL an error occurs PIFInfo_getExtension() returns NULL. More specific error information can be retrieved using PIPlatform_getLastError().

See Also:
PIFInfo_getPath

Return to index


Name:
PIFInfo_getFirstFileInDirectory

Synopsis:
PIFInfo *PIFInfo_getFirstFileInDirectory( PIFInfo *pFileInfo )

Description:
Returns a new PIFInfo object which contains information about the first file in the directory referred to by pFileInfo. This object can be used in subsequent calls to PIFInfo_getNextFileInDirectory() to iterate through all files in a directory.

Notes:
PIFInfo_getFirstFileInDirectory() allocates a new PIFInfo object, distinct from pFileInfo which must be seperately destroyed using PIFInfo_delete().

Return Values:
On success PIFInfo_getFirstFileInDirectory() returns a non-NULL pointer to a valid PIFInfo object.

Errors:
On error PIFInfo_getFirstFileInDirectory() returns NULL and PIPlatform_getLastError() can be used to retrieve an error code indicating the reason for the failure.

See Also:
PIFInfo_getNextFileInDirectory

Return to index


Name:
PIFInfo_getLastModified

Synopsis:
PIPLATFORM_TIME PIFInfo_getLastModified( PIFInfo *pFileInfo )

Description:
Gives the time of the last modification to the file specified by pFileInfo.

Notes:
Time is measured in seconds elapsed since 00:00:00 UTC, Jan. 1, 1970.

Return Values:
On success PIFInfo_getLastModified() returns the time of the last modification to the file pFileInfo. On error PIFInfo_getLastModified() returns 0.

Errors:
PIPlatform_getLastError() can be examined to distinguish an error condition from a file which was last modified at exactly 00:00:00 UTC, Jan. 1, 1970.

See Also:

Return to index


Name:
PIFInfo_getName

Synopsis:
const char *PIFInfo_getName( PIFInfo *pFileInfo )

Description:
Returns the name of the file referred to by pFileInfo.

Notes:

Return Values:
On sucess PIFInfo_getName() returns a non-NULL pointer to the filename.

Errors:
On error PIFInfo_getName() returns NULL. The function PIPlatform_getLastError() can be used to retrieve more specific error information.

See Also:
PIFInfo_getPath

Return to index


Name:
PIFInfo_getNextFileInDirectory

Synopsis:
int PIFInfo_getNextFileInDirectory( PIFInfo *pFileInfo )

Description:
Makes pFileInfo point to the next file in the directory. The object referred to by pFileInfo must have been created with a call to PIFInfo_getFirstFileInDirectory().

Notes:
If pFileInfo refers the last file in the directory, PIFInfo_getNextFileInDirectory() returns PIAPI_FALSE and pFileInfo does no refer to a valid file.

Return Values:
On success PIFInfo_getNextFileInDirectory() returns PIAPI_TRUE and pFileInfo points to the next file in the directory. If there are no other files in the directory or an error occurs PIFInfo_getNextFileInDirectory() returns PIAPI_FALSE. The object pFileInfo should be destroy using PIFInfo_delete() when it is no longer needed.

Errors:
On error PIFInfo_getNextFileInDirectory() returns PIAPI_FALSE and PIPlatform_getLastError() returns a value other than PIAPI_COMPLETED indicating which error occurred.

See Also:
PIFInfo_getFirstFileInDirectory

Return to index


Name:
PIFInfo_getPath

Synopsis:
const char *PIFInfo_getPath( PIFInfo *pFileInfo )

Description:
Returns the full path to the file referred to by pFileInfo.

Notes:

Return Values:
On sucess PIFInfo_getPath() returns a non-NULL pointer to the files path.

Errors:
On error PIFInfo_getPath() returns NULL. The function PIPlatform_getLastError() can be used to retrieve more specific error information.

See Also:
PIFInfo_getName

Return to index


Name:
PIFInfo_getPathRoot

Synopsis:
const char *PIFInfo_getPathRoot( PIFInfo *pFileInfo )

Description:
Returns the file path to the directory containing the file referred to by pFileInfo.

Notes:

Return Values:
On sucess PIFInfo_getPathRoot() returns a non-NULL pointer.

Errors:
On error PIFInfo_getPathRoot() returns NULL. The function PIPlatform_getLastError() can be used to retrieve more specific error information.

See Also:
PIFInfo_getPath

Return to index


Name:
PIFInfo_getSize

Synopsis:
PIPLATFORM_FSIZE PIFInfo_getSize( PIFInfo *pFileInfo )

Description:
Specifies the size of the file represented by file information object pFileInfo.

Notes:
PIPlatform_getLastError() must be used to distinguish an error condition from a zero length file.

Return Values:
On success PIFInfo_getSize() returns the file size. On failure PIFInfo_getSize() returns 0.

Errors:
PIPlatform_getLastError() can be examined to distinguish an error condition from a zero byte file. PIFInfo_getSize() will set the thread specific error code to PIAPI_COMPLETED before attempting to get the file size. If PIPlatform_getLastError() returns 0 (PIAPI_COMPLETED) then no error occured. See 'Errors' for a full description of possible errors.

See Also:
PIFInfo_getExtension PIFInfo_getName

Return to index


Name:
PIFInfo_isDirectory

Synopsis:
int PIFInfo_isDirectory( PIFInfo *pFileInfo )

Description:
Specifies whether or not the file information object pFileInfo refers to a directory.

Notes:

Return Values:
On success PIFInfo_isDirectory() returns either PIAPI_TRUE or PIAPI_FALSE, indicating whether or not a file respresented by pFileInfo is a directory.

Errors:
This function does not generate an error.

See Also:
PIFInfo_exists PIFInfo_isRegular PIFInfo_isReadable PIFInfo_isLink

Return to index


Name:
PIFInfo_isExecutable

Synopsis:
int PIFInfo_isExecutable( PIFInfo *pFileInfo )

Description:
Specifies whether or not the file information object pFileInfo refers to a file that may be executed as a program.

Notes:
The execute status of a file is effected by its permissions, the user privilages of the executing program and the exclusive lock status of the file.

Return Values:
On success PIFInfo_isExecutable() returns either PIAPI_TRUE or PIAPI_FALSE, indicating whether or not a file respresented by pFileInfo may be executed.

Errors:
This function does not generate an error.

See Also:
PIFInfo_exists PIFInfo_isRegular PIFInfo_isReadable PIFInfo_isWritable PIFInfo_isDirectory PIFInfo_isLink

Return to index


Name:
PIFInfo_isLink

Synopsis:
int PIFInfo_isLink( PIFInfo *pFileInfo )

Description:
Specifies whether or not the file information object pFileInfo refers to a symbolic link.

Notes:

Return Values:
On success PIFInfo_isLink() returns either PIAPI_TRUE or PIAPI_FALSE, indicating whether or not a file respresented by pFileInfo is a symbolic link.

Errors:
This function does not generate an error.

See Also:
PIFInfo_exists PIFInfo_isRegular PIFInfo_isReadable PIFInfo_isDirectory

Return to index


Name:
PIFInfo_isReadable

Synopsis:
int PIFInfo_isReadable( PIFInfo *pFileInfo )

Description:
Specifies whether or not the file information object pFileInfo refers to a file that may be opened for reading.

Notes:
The readibility of a file is effected by its permissions, the user privilages of the executing program and the exclusive lock status of the file.

Return Values:
On success PIFInfo_isReadable() returns either PIAPI_TRUE or PIAPI_FALSE, indicating whether or not a file respresented by pFileInfo may be opened for reading.

Errors:
This function does not generate an error.

See Also:
PIFInfo_exists PIFInfo_isRegular PIFInfo_isExecutable PIFInfo_isWritable PIFInfo_isDirectory PIFInfo_isLink

Return to index


Name:
PIFInfo_isRegular

Synopsis:
int PIFInfo_isRegular( PIFInfo *pFileInfo )

Description:
Specifies whether or not the file information object pFileInfo refers to a file that is a regular file.

Notes:
Directories and symbolic links are some of the valid PIFInfo objects that are not regular files.

Return Values:
On success PIFInfo_isRegular() returns either PIAPI_TRUE or PIAPI_FALSE, indicating whether or not a file respresented by pFileInfo is a regular file.

Errors:
This function does not generate an error.

See Also:
PIFInfo_exists PIFInfo_isReadable PIFInfo_isDirectory PIFInfo_isLink

Return to index


Name:
PIFInfo_isWritable

Synopsis:
int PIFInfo_isWritable( PIFInfo *pFileInfo )

Description:
Specifies whether or not the file information object pFileInfo refers to a file that may be opened for writting.

Notes:
The readibility of a file is effected by its permissions, the user privilages of the executing program and the types of locks held on the file.

Return Values:
On success PIFInfo_isWritable() returns either PIAPI_TRUE or PIAPI_FALSE, indicating whether or not a file respresented by pFileInfo may be opened for writting.

Errors:
This function does not generate an error.

See Also:
PIFInfo_exists PIFInfo_isRegular PIFInfo_isReadable PIFInfo_isExecutable PIFInfo_isDirectory PIFInfo_isLink

Return to index


Name:
PIFInfo_new

Synopsis:
PIFInfo *PIFInfo_new( const char *pPath )

Description:
Create a new file information object.

Notes:
This object should be deleted with PIFInfo_delete() when it is no longer needed.

Return Values:
On success PIFInfo_new() return a pointer to a new PIFInfo object.

Errors:
NULL will be returned if an pPath is NULL or memory could not be allocated for the new PIFInfo object. More specific error information can be retrieved using PIPlatform_getLastError().

See Also:
PIFInfo_delete

Return to index


Name:
PIFMap_delete

Synopsis:
int PIFMap_delete( PIFMap *pMappedFile )

Description:
Destroys and free memory associated with the mapped file object pMappedFile.

Notes:

Return Values:
On success PIFMap_delete() returns zero (PIAPI_COMPLETED).

Errors:
On error PIFMap_delete() returns a negative value. More specific error information can be retrieved using PIPlatform_getLastError().

See Also:
PIFMap_new

Return to index


Name:
PIFMap_lock

Synopsis:
void *PIFMap_lock( PIFMap *pMappedFile, int *piLength )

Description:
Locks a mapped file object in memory and returns a pointer to the first byte. If piLength is not NULL the length of the mapped file will be written in the location it points at.

Notes:
PIFMap_lock() maps the file in read only mode. When the address of the file map is no longer needed the mapped file object should be unlocked using PIFMap_unlock(). PIFMap_lock() and PIFMap_unlock() may be invoked any number of times in order.

Return Values:
On success PIFMap_lock() returns a pointer to a memory address where the file has been mapped.

Errors:
PIFMap_lock() returns NULL if pMappedFile is NULL or an error occurred. More specific error information can be retrieved using PIPlatform_getLastError().

See Also:
PIFMap_unlock

Return to index


Name:
PIFMap_new

Synopsis:
PIFMap *PIFMap_new( const PIFInfo *pFileInfo )

Description:
Create a new mapped file object to map a file into virtual memory.

Notes:
The mapped file object should be destroyed using PIFMap_delete() when it is no longer needed.

Return Values:
On success PIFInfo returns a pointer to a new mapped file object.

Errors:
If pFileInfo is NULL or memory cannot be allocated PIFMap_new() will return NULL. More specific error information can be retrieved using PIPlatform_getLastError().

See Also:
PIFMap_delete

Return to index


Name:
PIFMap_unlock

Synopsis:
int PIFMap_unlock( PIFMap *pMappedFile )

Description:
Unlocks the mapped file object pMappedFile. This invalidates any memory pointer obtained from PIFMap_lock().

Notes:
The use of lock and unlock on a file mapping object allows some operating systems to more efficiently manage system resources. It is an error to invoke PIFMap_unlock() on a file mapping object that has not been locked with PIFMap_lock().

Return Values:
On success PIFMap_unlock() returns zero (PIAPI_COMPLETED).

Errors:
On error PIFMap_unlock() returns a negative value. More specific error information can be retrieved using PIPlatform_getLastError().

See Also:
PIFMap_lock

Return to index


Name:
PIFile_close

Synopsis:
int PIFile_close( PIPLATFORM_FD tFD )

Description:
Closes a platform specific file descriptor opened by PIFile_open().

Notes:

Return Values:
On success PIFile_close() returns zero (PIAPI_COMPLETED).

Errors:
On error PIFile_close() does not return PIAPI_COMPLETED. The function PIPlatform_getLastError() can be used to retrieve more specific error information.

See Also:
PIFile_open

Return to index


Name:
PIFile_open

Synopsis:
PIPLATFORM_FD PIFile_open( const char *pPath, const char *pFlags )

Description:
Open a new platform specific file handle to the file identified by the path pPath. The value pFlags is a sequence of characters with the following meanings. "W" - open file in write mode overwritting any previous file with the same path. "A" - open the file in write mode appending to any file with the same path. "R" can be specified for opening a file for reading. "N" indicates that the file should not be opened if it already exists (must not alreadu exist). In all cases With the exception of when the "N" flag is present, a new file will be created if it did not exist.

Flags are not case sensitive.

Notes:
PIPLATFORM_FD, is an operating system specific handle or descriptor, other operations may be performed on this object by casting this value to the type associated with operating system specific descriptors and using system calls. PIFile_* functions are primarily intented for creating and appended file optimally with synchronization amoungst write operations from multiple threads and processes, however they may also be used for simple unbuffering readonly access to existing files. The function PIFile_close() should be used to close a file handle when it is no longer needed. File handles should be considered an easily exhaustable resource, and omitting to match successful PIFile_open() calls with calls to PIFile_close() is a serious resource leak.

Return Values:
The values returned from PIFile_open should be compared with the PIPLATFORM_FD_INVALID to determine if an error occurred, i.e.

		PIPLATFORM_FD tFD;
		if ((tFD = PIFile_open( "/tmp/dummy.txt", "w" ))==PIPLATFORM_FD_INVALID)
			{
			/.* --- handle error --- *./
			int iErrorCode = PiPlatform_getLastError();

			...

			}
		else
			{
			/.* --- tFD is a valid file handle --- *./

			...

			PIFile_close( tFD );
			};

Errors:
More specific error information can be retrieved using PIPlatform_getLastError().

See Also:
PIFile_close

Return to index


Name:
PIFile_read

Synopsis:
int PIFile_read( PIPLATFORM_FD tFD, int iLength, void *pData )

Description:
Read the data block of Length bytes from the file referenced by the descriptor tFD.

Notes:
The function PIPlatform_PollFD() may to used yield processing to another thread if the read operation would block.

Return Values:
On success PIFile_read() returns zero (PIAPI_COMPLETED).

Errors:
On error, the function PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIFile_write PIFile_writeAtomic

Return to index


Name:
PIFile_unlink

Synopsis:
int PIFile_unlink( const char *pPath )

Description:
Unlink or delete a file.

Notes:

Return Values:
On success PIFile_unlink() returns zero (PIAPI_COMPLETED).

Errors:
On error PIFile_unlink() does not return PIAPI_COMPLETED. The function PIPlatform_getLastError() can be used to retrieve more specific error information.

See Also:
PIFile_open

Return to index


Name:
PIFile_write

Synopsis:
int PIFile_write( PIPLATFORM_FD tFD, int iLength, const void *pData )

Description:
Write the data block of Length bytes to the file referenced by the descriptor tFD.

Notes:
The function PIPlatform_PollFD() may to used yield processing to another thread if the write operation would block.

Return Values:
On success PIFile_write() returns zero (PIAPI_COMPLETED).

Errors:
On error, the function PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIFile_read PIFile_writeAtomic

Return to index


Name:
PIFile_writeAtomic

Synopsis:
int PIFile_writeAtomic( PIPLATFORM_FD tFD, int iLength, const void *pData )

Description:
Write the data block if Length bytes to the file referenced by the descriptor tFD. The write operation is atomic, meaning that descriptor will be locked using a platform specific method to ensure the block of a data is written correctly in an environment where multiple processes and threads are competing to write to the file.

Notes:
This function will only gaurentee synchronized writes amoungst processes on POSIX compliant platforms. On other platforms only thread synchronization is performed.

Return Values:
On success PIFile_writeAtomic() returns zero (PIAPI_COMPLETED).

Errors:
On error, the function PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIFile_read PIFile_write

Return to index


Name:
PIPlatform_advisaryLockFd

Synopsis:
PIPlatform_advisaryLockFd( PIPLATFORM_FD tFD )

Description:
Place an advisary lock on a file descriptor, blocking until the the lock can be obtained. The blocking is performed in an efficient manner for the process and thread model beng used.

Notes:

Return Values:
On success PIPlatform_advisaryLockFd() returns zero (PIAPI_COMPLETED).

Errors:
On error, the function PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIPlatform_advisaryUnlockFd

Return to index


Name:
PIPlatform_advisaryUnlockFd

Synopsis:
PIPlatform_advisaryUnlockFd( PIPLATFORM_FD tFD )

Description:
Release an advisary lock from a file descriptor, previously placed with PIPlatform_advisaryLockFd().

Notes:

Return Values:
On success PIPlatform_advisaryUnlockFd() returns zero (PIAPI_COMPLETED).

Errors:
On error, the function PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIPlatform_advisaryLockFd

Return to index


Name:
PIPlatform_afterUnsafeBlock

Synopsis:
int PIPlatform_afterUnsafeBlock()

Description:
Ends a block protected by reentrance with PIPlatform_beforeUnsafeBlock().

Notes:

Return Values:
Returns 0 on success.

Errors:
On error a non-zero value is returned, the function PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIPlatform_beforeUnsafeBlock

Return to index


Name:
PIPlatform_allocLocalMutex

Synopsis:
PISync *PIPlatform_allocLocalMutex()

Description:
Returns a new local mutex which can be used to synchronize threads of control within a process.

Notes:
The synchronization object should be destroyed using PISync_delete() when it is no longer needed.

Return Values:
Returns a pointer to a new synchronization object or NULL on error.

Errors:
NULL may be returned if a new syncronization object could not be created due to exhausted memory, kernel mutexes or user mutexes. More information can be retrieved using PIPlatform_getLastError().

See Also:
PISync_lock PISync_unlock PISync_tryLock PISync_delete

Return to index


Name:
PIPlatform_allocLocalSemaphore

Synopsis:
PISync *PIPlatform_allocLocalSemaphore( int iInitalCount, int iMaxCount )

Description:
Returns a new local semaphore which can be used to synchronize threads of control within a process.

Notes:
The synchronization object should be destroyed using PISync_delete() when it is no longer needed.

Return Values:
Returns a pointer to a new synchronization object or NULL on error.

Errors:
NULL may be returned if a new syncronization object could not be created due to exhausted memory, kernel semaphores or user semaphores. More specific error information can be retrieved using PIPlatform_getLastError().

See Also:
PISync_lock PISync_unlock PISync_tryLock PISync_delete

Return to index


Name:
PIPlatform_beforeUnsafeBlock

Synopsis:
int PIPlatform_beforeUnsafeBlock()

Description:
Protects reentrance into non-thread safe blocks by blocking on a semaphore.

Notes:
Calls to PIPlatform_beforeUnsafeBlock() must be matched by calls to PIPlatform_afterUnsafeBlock().

Return Values:
Returns 0 on success.

Errors:
On error a non-zero value is returned, the function PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIPlatform_afterUnsafeBlock

Return to index


Name:
PIPlatform_catchExceptions

Synopsis:
void PIPlatform_catchExceptions( void (*)(void *)pFn, void *pArg )

Description:
This function does execute the function pFN with argument pArg using low level error handling in the Pi3 platform.

Notes:
The function is used internally by PIProgram_enter.

Return Values:

Errors:
This function does not generate an error.

See Also:

Return to index


Name:
PIPlatform_enter

Synopsis:
int PIPlatform_enter( const char *pArgv0, int iVersion, PIPlatformFn fn )

Description:
Initializes the platform facilities including user context threads and custom memory management, then calls the user supplied function fn. PIPlatform_enter() cleans platform facilities before returning.

Notes:
The parameter pArgv0 should be passed argv[0] from the main() entry point to the program, as certain implementations of dynamic loading require this. However this is not essential to the functioning of most platform functionality and NULL may be passed instead. The constant PLATFORM_VERSION_1_0 should be used as parameter iVersion to this function. A typical use of this function is to invoke it immediately on entering main() or equivalent function. The function fn is run in the main thread with initial priority PITHREAD_PRIORIY_MED.

	/* --- globals --- */
	int iArgc;
	char **ppArgv;
	int iRet;
	
	/* --- Main program function --- */
	void foo()
	{

		/* ... */

		iRet = 0;
	}

	/* --- initialize the platform and invoke foo() --- */
	int main( int iArgc, char *ppArgv[] )
	{
	iArgc = iTheArgc;
	ppArgv = ppTheArgv;
	if ( PIPlatform_enter( ppArgv[0], PLATFORM_VERSION_1_0, foo ) )
		{
		printf( "Error initializing platform\n" );
		return 0;
		};
	return iRet;
	}

Return Values:
PIPlatform_enter() returns zero (PIAPI_COMPLETED) on success.

Errors:
On error PIPlatform_enter() returns a negative value. More error information can be retrieved using PIPlatform_getLastError().

See Also:
PIPlatform_getDescription

Return to index


Name:
PIPlatform_getCurrentDirectory

Synopsis:
int PIPlatform_getCurrentDirectory( char *pBuffer, int iMaxLen )

Description:
Retrieve the current directory for the process and write it into the buffer pBuffer up to iMaxLen characters.

Notes:
The buffer pBuffer may not be null terminated if the length of the current directory is greater than or equal to iMaxLen.

Return Values:
Returns the length of the current directory. Although no more than iMaxLen characters will be written into pBuffer, PIPlatform_getCurrentDirectory() may return a length greater than iMaxLen.

Errors:
On error PIPlatform_getCurrentDirectory() returns 0. PIPlatform_getLastError() can be used to get more specific error information.

See Also:

Return to index


Name:
PIPlatform_getDescription

Synopsis:
const char *PIPlatform_getDescription()

Description:
Returns a string which describes the range of operating systems and machine/processor sets for which this build is compatible.

Notes:
The description is of the form Operating system ( machine processor )

Return Values:
Returns an internally allocated pointer to a string. The caller should not modify this string.

Errors:
PIPlatform_getDescription returns NULL if PIPlatform_Init() has not been called. More error information can be retrieved using PIPlatform_getLastError().

See Also:
PIPlatform_enter

Return to index


Name:
PIPlatform_getDirectorySeparator

Synopsis:
char PIPlatform_getDirectorySeparator()

Description:
Retrieve the directory separator character for this platform.

Notes:

Return Values:
Returns the operating system dependant directory separator character.

Errors:
On error PIPlatform_getDirectorySeparator() returns 0.

See Also:

Return to index


Name:
PIPlatform_getLastError

Synopsis:
int PIPlatform_getLastError()

Description:
Returns the last error code for the current thread.

Notes:
Error codes are only set on error. Except where noted they are not cleared on success.

Return Values:
PIPlatform_getLastError() always returns the last error code.

Errors:
This function does not generate an error.

See Also:
PIPlatform_setLastError Errors

Return to index


Name:
PIPlatform_getProcess

Synopsis:
int PIPlatform_getProcess()

Description:
Retrieve the platform specific identifier or handle for the current process.

Notes:

Return Values:
Idenifier or handle of Current process.

Errors:
PIPlatform_getProcess() does not generate errors.

See Also:
PIPlatform_getProcessId

Return to index


Name:
PIPlatform_getProcessId

Synopsis:
int PIPlatform_getProcessId()

Description:
Retrieve the platform specific identifier for the current process.

Notes:
PIPlatform_getProcessId() differs from PIPlatform_getProcess() in that PIPlatform_getProcessId() always returns an integer process index that can be used to reference a specific process across all processes. PIPlatform_getProcess() returns the native reference to a process and may only be valid within the process space of the current process.

Return Values:
Identifier for the Current process.

Errors:
PIPlatform_getProcessId() does not generate errors.

See Also:
PIPlatform_getProcess

Return to index


Name:
PIPlatform_getUniqueId

Synopsis:
int PIPlatform_getUniqueId(const char *szBuf, unsigned int iLen)

Description:
Generates a new id that is a sequence of hexadecimal digits guaranteed to be unique for the lifetime of this object.

Notes:
None.

Return Values:
If PIAPI_COMPLETED is returned, szBuf contains the unique Id. If iLen is set to 0 the required size of szBuf is returned.

Errors:
PIAPI_ERROR may be returned if an unique identifier couldn't created or PIAPI_EINVAL if the buffer is to small. More information can be retrieved using PIPlatform_getLastError().

See Also:
PIPlatform_enter

Return to index


Name:
PIPlatform_pollFD

Synopsis:
int PIPlatform_pollFD( PIPLATFORM_FD fd, int iFlags, int iTimeout )

Description:
Waits for the activity on the specified file descriptor. The value iFlags is formed by OR'ing together any combination of the values PIPLATFORM_POLL_READ and PIPLATFORM_POLL_WRITE. The value piTimeout is a pointer to an integer containing a time to wait in seconds.

Notes:
A value of PIPLATFORM_NOTIMEOUT for iTimeout specifies no timeout. A value of PIPLATFORM_NOWAIT for iTimeout specifies that PIPlatform_pollNetFD() should test for activity on fd but return immediately even if there is none. On systems where differences between sockets and file descriptors are transparent, PIPlatform_pollFD() is implemented using PIPlatform_pollNetFD(). On other systems PIPlatform_pollFD() may not be implemented, see below under 'Errors'.

Return Values:
On success PIPlatform_pollFD() returns a value formed by OR'ing some of the values PIPLATFORM_POLL_READ and PIPLATFORM_POLL_WRITE together indicating which operations may be performed on file description fd without blocking. If the specified timeout period expires, PIPlatform_pollFD() returns a value of zero.

Errors:
On failure PIPlatform_pollNetFD() returns a negative value. More specific error information can be retreived using PIPlatform_getLastError(). On some systems PIPlatform_pollFD() is not yet implemented, in this case a value of PIAPI_ERROR will be returned and PIPlatform_getLastError() will return a value of PIAPI_NOTSUPPORTED.

See Also:
PIPlatform_pollNetFD PIPlatform_pollPipeFD PIPlatform_sleep

Return to index


Name:
PIPlatform_pollNetFD

Synopsis:
int PIPlatform_pollNetFD( PIPLATFORM_NETFD fdSocket, int iFlags, int iTimeout )

Description:
Waits for the activity on the specified network file descriptor (socket). The value iFlags is formed by OR'ing together any combination of the values PIPLATFORM_POLL_READ and PIPLATFORM_POLL_WRITE. The value piTimeout is a pointer to an integer containing a time to wait in seconds.

Notes:
A value of PIPLATFORM_NOTIMEOUT for iTimeout specifies no timeout. A value of PIPLATFORM_NOWAIT for iTimeout specifies that PIPlatform_pollNetFD() should test for activity on fdSocket but return immediately even if there is none.

Return Values:
On success PIPlatform_pollNetFD() returns a value formed by OR'ing some of the values PIPLATFORM_POLL_READ and PIPLATFORM_POLL_WRITE together indicating which operations may be performed on socket fdSocket without blocking. If the specified timeout period expires, PIPlatform_pollNetFD() returns a value of zero.

Errors:
On failure PIPlatform_pollNetFD() returns a negative value. More specific error information can be retreived using PIPlatform_getLastError().

See Also:
PIPlatform_pollFD PIPlatform_pollPipeFD PIPlatform_sleep

Return to index


Name:
PIPlatform_pollPipeFD

Synopsis:
int PIPlatform_pollPipeFD( PIPLATFORM_FD fd, int iFlags, int iTimeout )

Description:
Waits for activity on the specified pipe. The value iFlags is formed by OR'ing together any combination of the values PIPLATFORM_POLL_READ and PIPLATFORM_POLL_WRITE. The value piTimeout is a pointer to an integer containing a time to wait in seconds.

Notes:
A value of PIPLATFORM_NOTIMEOUT for iTimeout specifies no timeout. A value of PIPLATFORM_NOWAIT for iTimeout specifies that PIPlatform_pollNetFD() should test for activity on fd but return immediately even if there is none. On systems where differences between pipes and file descriptors are transparent, PIPlatform_pollPipeFD() is implemented using PIPlatform_pollFD(). On other systems PIPlatform_pollPipeFD() may not be implemented, see below under 'Errors'.

Return Values:
On success PIPlatform_pollPipeFD() returns a value formed by OR'ing some of the values PIPLATFORM_POLL_READ and PIPLATFORM_POLL_WRITE together indicating which operations may be performed on pipe fd without blocking. If the specified timeout period expires, PIPlatform_pollPipeFD() returns a value of zero.

Errors:
On failure PIPlatform_pollNetFD() returns a negative value. More specific error information can be retreived using PIPlatform_getLastError(). On some systems PIPlatform_pollPipeFD() is not yet implemented, in this case a value of PIAPI_ERROR will be returned and PIPlatform_getLastError() will return a value of PIAPI_NOTSUPPORTED.

See Also:
PIPlatform_pollPipeFD IPlatform_pollNetFD PIPlatform_sleep

Return to index


Name:
PIPlatform_setLastError

Synopsis:
void PIPlatform_setLastError( int iErrorCode )

Description:
Set the error code for this thread. Subsequent calls to PIPlatform_getLastError() will return this error code.

Notes:

Return Values:
PIPlatform_setLastError() does not return a value.

Errors:
This function does not generate an error.

See Also:
PIPlatform_getLastError Errors

Return to index


Name:
PIPlatform_sleep

Synopsis:
int PIPlatform_sleep( int iMilliseconds )

Description:
Causes the current thread to sleep for at least iMilliseconds thousandths of a second. The current thread may sleep for longer than the specified time period. This is particularly true where user context threads are in use.

Notes:
If user context threads are being used and no other threads are runnable PIPlatform_sleep() will cause the process to enter a 'tight loop'. This may be expensive on CPU utilization with some programs.

Return Values:
On success PIPlatform_sleep() returns a value of 0.

Errors:
On failure PIPlatform_sleep() returns a negative value. PIPlatform_getLastError() returns more specific error information.

See Also:
PIPlatform_pollNetFD PIPlatform_pollFD

Return to index


Name:
PIPlatform_waitForProcess

Synopsis:
int PIPlatform_waitForProcess( int tProcess, int iFlags, int iTimeout )

Description:
Cause the current thread to sleep until the process specified by the operating system specific identifier or handle (tProcess) has terminated. iFlags is reserved for future use and should always be 0. iTimeout specifies the maximum time to wait, measured in seconds.

Notes:
The parameter iFlags must be passed the value 0.

Return Values:
Returns PIAPI_COMPLETED on success, PIAPI_TIMEOUT on timeout, otherwise PIAPI_ERROR.

Errors:
On error PIAPI_ERROR is returned. The function PIPlatform_getLastError() can be used to retreive more specific error information.

See Also:

Return to index


Name:
PISync_delete

Synopsis:
int PISync_delete( PISync *pSync )

Description:
Destroy's a synchronization object.

Notes:

Return Values:
PISync_delete returns zero (PIAPI_COMPLETED) on success.

Errors:
PIAPI_ERROR an error occurred. PIPlatform_getLastError() can be used to obtain more detailed error information.

See Also:
PIPlatform_allocLocalMutex PIPlatform_allocLocalSemaphore

Return to index


Name:
PISync_lock

Synopsis:
int PISync_lock( PISync *pSync )

Description:
Attempts to grap a mutex resource or increment the count on a semaphore resource. If the lock cannot be obtained PISync_lock() will block until it is obtained.

Notes:
The behaviour of PISync_lock depends on the type of the synchronization object pSync. PISync_delete() should be used to destroy a synchronization object when it is no longer needed.

Return Values:
PISync_lock returns zero (PIAPI_COMPLETED) on success.

Errors:
PIAPI_ERROR an error occurred. PIPlatform_getLastError() can be used to obtain more detailed error information.

See Also:
PISync_lock PISync_tryLock PISync_unlock

Return to index


Name:
PISync_tryLock

Synopsis:
int PISync_tryLock( PISync *pSync )

Description:
Attempts to grap a mutex resource or increment the count on a semaphore resource. If the lock cannot be immediately obtained PISync_lock() will return without blocking.

Notes:
The behaviour of PISync_tryLock depends on the type of the synchronization object pSync. PISync_delete() should be used to destroy a synchronization object when it is no longer needed.

Return Values:
PISync_tryLock returns zero (PIAPI_COMPLETED) if the lock was obtained or PIAPI_WOULDBLOCK if the lock could not be obtained.

Errors:
PIAPI_ERROR an error occurred. PIPlatform_getLastError() can be used to obtain more detailed error information.

See Also:
PISync_lock PISync_tryLock PISync_unlock

Return to index


Name:
PISync_unlock

Synopsis:
int PISync_unlock( PISync *pSync )

Description:
Free's a lock that was placed on a mutex synchronization object or increments the free count of a semaphore synchronization object. This function removes the lock placed by PISync_lock() or PISync_tryLock().

Notes:
The behaviour of PISync_unlock depends on the type of the synchronization object pSync. PISync_delete() should be used to destroy a synchronization object when it is no longer needed.

Return Values:
PISync_unlock returns zero (PIAPI_COMPLETED) on success.

Errors:
PIAPI_ERROR an error occurred. PIPlatform_getLastError() can be used to obtain more detailed error information.

See Also:
PISync_lock PISync_tryLock PISync_unlock

Return to index


Name:
PIThread_begin

Synopsis:
int PIThread_begin( PIThread *pThread, PIThreadFn fnEntry, unsigned long ulData, int iPriority, int iFlags )

Description:
Schedules the thread object pThread to be executed. The entry point function fnEntry will invoked with the argument ulData. The value iPriority can be one of the thread priority values described in PIThread_setPriority() and indicates the initial priority at which the thread runs. The value of iFlags is formed by OR'ing together zero or more of the following values:- PITHREAD_FLAGS_SUSPENDED The thread not run until PIThread_resume()

Notes:
The thread object pThread can be a newly created object from PIThread_new() or a previously run thread which has terminated.

Return Values:
On success PIThread_begin() returns zero (PIAPI_COMPLETED).

Errors:
PIAPI_ERROR if an error occurred. PIPlatform_getLastError() can be used to obtain more detailed error information.

See Also:
PIThread_terminate PIThread_waitForThread

Return to index


Name:
PIThread_dbgDump

Synopsis:
void PIThread_dbgDump( const char *pDumpFile )

Description:
Opens the specified file for write append and writes internal information on thread status within the program. If pDumpFile is NULL, information will be written to the stdout stream.

Notes:
This function is mainly for getting verbose information on thread scheduling when the internal user thread implementation is being used. If operating system kernel threads are used this debugging information will be terse.

Return Values:
PIThread_dbgDump does not return a value.

Errors:
PIThread_dbgDump does not return errors. PIPlatform_getLastError() can be used to get more specific error information.

See Also:

Return to index


Name:
PIThread_delete

Synopsis:
int PIThread_delete( PIThread *pThread )

Description:
Destroys a thread object, and invalidates the pointer pThread.

Notes:
If pThread has not terminated, PIThread_delete() will kill the thread and poll for its termination using PIThread_terminate() and PIThread_waitForThread(). PIThread_delete completely invalidates the pointer pThread, the results are undefined if the pointer pThread is used in a thread function again. A defensive use of this function would set pThread to NULL after PIThread_delete() has been successfully completed.

Return Values:
On success PIThread_delete() returns zero (PIAPI_COMPLETED).

Errors:
PIAPI_ERROR if an error occurred. PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIThread_new

Return to index


Name:
PIThread_destroyThreadKey

Synopsis:
int PIThread_destroyThreadKey( int iKey )

Description:
Destroy the thread key (index) iKey. This key can subsequently be reassigned by PIThread_initThreadKey().

Notes:

Return Values:
On success PIThread_destroyThreadKey() returns zero (PIAPI_COMPLETED).

Errors:
On failure PIThread_destroyThreadKey() returns PIAPI_ERROR. PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIThread_initThreadKey

Return to index


Name:
PIThread_getCurrent

Synopsis:
PIThread *PIThread_getCurrent()

Description:
Returns a pointer to the currently executing thread object.

Notes:

Return Values:
On success PIThread_getCurrent() returns the non-NULL pointer to the currently executing thread object.

Errors:
NULL if an error occurs. PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIThread_getMain

Return to index


Name:
PIThread_getData

Synopsis:
void *PIThread_getData( PIThread *pThread, int iKey )

Description:
Returns the thread local data for the thread referenced by pThread at key iKey. This is the value previously set by PIThread_setData() for this thread and key.

Notes:
All thread local data is zero initialized by PIThread_new(). It is undefined whether using PIThread_terminate() followed by PIThread_begin() will modify thread local data when used to reuse a thread.

Return Values:
On success PIThread_getData() returns the thread local data for this thread object at the specified key and PIPlatform_getLastError() will return PIAPI_COMPLETED.

Errors:
On error PIThread_getData() will return NULL and PIPlatform_getLastError() will return a specific error code.

See Also:
PIThread_setData

Return to index


Name:
PIThread_getMain

Synopsis:
PIThread *PIThread_getMain()

Description:
Returns a pointer to the main thread for the process.

Notes:

Return Values:
On success PIThread_getMain() returns the non-NULL pointer to the main thread object.

Errors:
NULL if an error occurs. PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIThread_getCurrent

Return to index


Name:
PIThread_getPriority

Synopsis:
int PIThread_getPriority( PIThread *pThread, int *piPriority )

Description:
Returns the priority of the thread pThread. piPriority points to the location where the priority will be written.

Notes:
See PIThread_setPriority() for a description of thread priorities.

Return Values:
On success PIThread_getPriority() write the thread priority into piPriority and returns zero (PIAPI_COMPLETED).

Errors:
PIAPI_ERROR if an error occurs. PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIThread_setPriority

Return to index


Name:
PIThread_getSystemHandle

Synopsis:
void *PIThread_getSystemHandle( PIThread *pThread )

Description:
Returns the implementation specific handle or pointer of the thread. This value can be used to reference the thread in additional thread library functions supplied by the operating system.

Notes:
The value returned by PIThread_getSystemHandle() must be cast to the appriopriate type e.g. 'thread_t', 'HANDLE'.

Return Values:
On success PIThread_getSystemHandle() returns the specific operating system handle of the thread.

Errors:
The function PIPlatform_getLastError() must be used to determine if a handle value of NULL is an error or the valid system dependant handle of the current thread. PIPlatform_getLastError() can be used to get more specific error information.

See Also:

Return to index


Name:
PIThread_initThreadKey

Synopsis:
int PIThread_initThreadKey()

Description:
Returns a new key (index) that can be used in PIThread_setData() and PIThread_getData() to save and retrieve thread local data.

Notes:

Return Values:
On success PIThread_initThreadKey() returns a non-negative thread key.

Errors:
On failure PIThread_initThreadKey() returns a negative number. PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIThread_destroyThreadKey

Return to index


Name:
PIThread_new

Synopsis:
PIThread *PIThread_new( PIMemoryPool *pPool, int iStackSize )

Description:
Creates and initializes a new thread object. The function PIThread_begin() can be used to run the thread. The parameters pPool and iStackSize are for future use but the values NULL and 0 respectively should be used to ensure future compatibility.

Notes:
If successful a new thread object will be created but will not be executed. The pointer to the thread object remains valid until PIThread_delete() is called.

Return Values:
On success PIThread_new() returns a pointer to a new thread object.

Errors:
On error PIThread_new() returns NULL. PIPlatform_getLastError() can be used to obtain more detailed error information.

See Also:
PIThread_delete

Return to index


Name:
PIThread_resume

Synopsis:
int PIThread_resume( pThread )

Description:
Resumes execution of a thread.

Notes:

Return Values:
PIThread_resume() returns zero (PIAPI_COMPLETED) if the thread was succesfully resumed or if the thread was not suspended.

Errors:
PIAPI_ERROR if an error occurred. PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIThread_suspend

Return to index


Name:
PIThread_setData

Synopsis:
int PIThread_setData( PIThread *pThread, int iKey, void *pData )

Description:
Sets the local data to pData for the thread referenced by pThread at the key iKey.

Notes:

Return Values:
On success PIThread_setData() returns zero (PIAPI_COMPLETED).

Errors:
PIAPI_ERROR if an error occurred. PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIThread_getData

Return to index


Name:
PIThread_setPriority

Synopsis:
int PIThread_setPriority( PIThread *pThread, int iNewPriority )

Description:
Set the priority of the thread pThread. The following are valid priority values. PITHREAD_PRIORITY_LOWEST PITHREAD_PRIORITY_LOW PITHREAD_PRIORITY_MED PITHREAD_PRIORITY_HIGH PITHREAD_PRIORITY_HIGHEST

Notes:
The precise behaviour of threads and thread priorities varies greatly across implementations. In general a higher priority thread will be scheduled before and run for longer than a lower priority thread. However whether or not a lower priority thread with be scheduled AT ALL when higher priority threads are runnable is implementation defined. The main thread initially runs at priority PITHREAD_PRIORITY_MED.

Return Values:
On success PIThread_setPriority() returns zero (PIAPI_COMPLETED).

Errors:
PIAPI_ERROR if an error occurs. PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIThread_getPriority

Return to index


Name:
PIThread_suspend

Synopsis:
int PIThread_suspend( PIThread *pThread )

Description:
Suspends execution of the thread pThread.

Notes:

Return Values:
PIThread_suspend() return zero (PIAPI_COMPLETED) if the thread was succesfully suspended or if the thread had previously been suspended.

Errors:
PIAPI_ERROR if an error occurred. PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIThread_resume

Return to index


Name:
PIThread_terminate

Synopsis:
int PIThread_terminate( PIThread *pThread, unsigned long ulExitCode )

Description:
Schedules the specified thread for termination. The thread will exit with the status code ulExitCode.

Notes:
** IMPORTANT ** Use of this function is not recommended as the target thread will usually have no opportunity to cleanup critical activity or synchronized actions it may be performing. This can cause the state of global objects to become unstable. This is true for user context threads, and particularly true for some operating system threads implementations. PIThread_terminate is not guaranteed to wait for the thread to terminate. Use the function PIThread_waitForThread() after PIThread_terminate() to poll for the termination of another thread. If pThread is the main thread then the following actions will also occur in the following order:

Return Values:
On success PIThread_terminate returns zero (PIAPI_COMPLETED).

Errors:
PIAPI_ERROR an error occurred. PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIThread_begin PIThread_waitForThread

Return to index


Name:
PIThread_userYield

Synopsis:
int PIThread_userYield()

Description:
Yield processing to another user thread. This function has no effect when multi-threading is implemented with operating system specific kernel threads. When multithreading is implemented with user context threads this function will behave like PIThread_Yield().

Notes:
Unlike kernel supplied threads (operating system specific) user context threads will not context switch until a synchronization function, such as PISync_lock(), PIPlatform_pollNetFD() is invoked. In code which does not use these synchronization functions (such as complex mathematical algorithms) one thread would monopolize all the processing in the application. PIThread_userYield() can be inserted into such code as a portable way to force preemptive thread behaviour in a non-preemptive threads environment without added unnecessary PIThread_Yield() calls to kernel multithreading environments.

Return Values:
On success PIThread_userYield() returns zero (PIAPI_COMPLETED).

Errors:
PIAPI_ERROR if an error occurred. PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIThread_yield

Return to index


Name:
PIThread_waitForThread

Synopsis:
int PIThread_waitForThread( PIThread *pThread );

Description:
Suspends execution of the current thread until the thread referenced by pThread has terminated.

Notes:
PIThread_waitForThread() does not attempt to terminate the thread referenced by pThread, the function PIThread_terminate() can be used for that.

Return Values:
PIThread_waitForThread() returns zero (PIAPI_COMPLETED) if the thread referenced by pThread has terminated.

Errors:
PIAPI_ERROR if an error occurred. PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIThread_terminate

Return to index


Name:
PIThread_yield

Synopsis:
int PIThread_yield()

Description:
Yield processing to another thread.

Notes:
PIThread_yield() does not attempt to terminate the thread referenced by pThread, the function PIThread_terminate() can be used for that. When multithreading is implemented using the kernel threads implementation of the current operating system with function will invoke the appropriate theads system call to cause the current thread to yield. PIThread_yield() does not guarantee that the current thread will yield. This is especially true when no other threads of equal or greater priority are runnable.

Return Values:
On success PIThread_yield() returns zero (PIAPI_COMPLETED).

Errors:
PIAPI_ERROR if an error occurred. PIPlatform_getLastError() can be used to get more specific error information.

See Also:
PIThread_userYield

Return to index


Name:
PITimer_delete

Synopsis:
int PITimer_delete( PITimer *pTimer )

Description:
Destroys a timer object and deallocates memory associated with it.

Notes:

Return Values:
Returns PIAPI_COMPLETED on success.

Errors:
On error PIAPI_ERROR is returned. The function PITimer_getLastError() returns more specific error information.

See Also:
PITimer_new

Return to index


Name:
PITimer_elapsed

Synopsis:
int PITimer_elapsed( PITimer *pTimer, long *plSeconds, long *plMicroSeconds )

Description:
Returns the number of seconds and microseconds elapsed since the timer was last reset.

Notes:
If plSeconds is NULL, the number of seconds will not be set. If plMicroSeconds is NULL, the number of microseconds will not be set.

Return Values:
Returns PIAPI_COMPLETED on success.

Errors:
On error PIAPI_ERROR is returned. The function PITimer_getLastError() returns more specific error information.

See Also:
PITimer_reset

Return to index


Name:
PITimer_new

Synopsis:
PITimer *PITimer_new()

Description:
Allocates and returns a pointer to a new timer object.

Notes:
Timer internals and API functions support microsecond resolution, however, most operating systems will not support this granularity. Actual timer resolution is operating system dependant.

Return Values:
Returns a pointer to a new Timer object.

Errors:
On error PITimer_new() returns NULL. The function PITimer_getLastError() can be used to get more specific error information.

See Also:
PITimer_delete

Return to index


Name:
PITimer_reset

Synopsis:
int PITimer_reset( PITimer *pTimer )

Description:
Reset the timer to 0 seconds and 0 microseconds.

Notes:

Return Values:
Returns PIAPI_COMPLETED on success.

Errors:
On error PIAPI_ERROR is returned. The function PITimer_getLastError() returns more specific error information.

See Also:
PITimer_elapsed

Return to index


Name:
PIUtil_free

Synopsis:
void PIUtil_free( void *pV )

Description:
Deallocate memory allocated by another function with the PIUtil_ prefix.

Notes:

Return Values:
PIUtil_free() does not return a value.

Errors:
None.

See Also:
PIUtil_malloc

Return to index


Name:
PIUtil_malloc

Synopsis:
void *PIUtil_malloc( unsigned long lSize )

Description:
Allocate memory.

Notes:
Memory allocated with PIUtil_malloc() should be freed with PIUtil_free().

Return Values:
On success this function returns a non-NULL pointer to a memory area of size equal to or greater than lSize.

Errors:
PIUtil_malloc() returns NULL if the requested memory could not be allocated. More error information is available via PIPlatform_getLastError().

See Also:
PIUtil_free

Return to index


Name:
PIUtil_strdup

Synopsis:
char *PIUtil_strdup( const char *pS )

Description:
Duplicate a NULL terminated character array.

Notes:
The function PIUtil_free() should be used to deallocate memory allocated via PIUtil_strdup().

Return Values:
On success PIUtil_strdup returns a copy of the character array pS.

Errors:
On error PIUtil_strdup() returns NULL. More information is available via PIPlatform_getLastError().

See Also:
PIUtil_free

Return to index


Name:
PIUtil_stricmp

Synopsis:
int PIUtil_stricmp( const char *pS1, const char *pS2 )

Description:
Compare two strings without case sensitivity.

Notes:
The result is undefined if either parameter is NULL.

Return Values:
This function returns the following values

Errors:
There are no error return codes from this function.

See Also:

Return to index


Name:
PIUtil_strncmpi

Synopsis:
int PIUtil_strncmpi( const char *pS1, const char *pS2, int iLen )

Description:
Compare two strings without case sensitivity up to iLen characters.

Notes:
The result is undefined if either parameter is NULL.

Return Values:
This function returns the following values

Errors:
There are no error return codes from this function.

See Also:

Return to index