PTE: Projects/pthreads/pte_generic

typedef int(* pte_osThreadEntryPoint)(void *params)

Enumerator:

PTE_OS_OK	Operation completed successfully
PTE_OS_NO_RESOURCES	Operation failed because there insufficient resources
PTE_OS_GENERAL_FAILURE	Operation failed due to a general failure
PTE_OS_TIMEOUT	Operation did not complete because a user specified timeout expired.
PTE_OS_INTERRUPTED	The operation was interrupted before it could complete.
PTE_OS_INVALID_PARAM	An invalid parameter was specified

int pte_osAtomicCompareExchange	(	int *	pdest,
		int	exchange,
		int	comp
	)

Performs an atomic compare-and-exchange oepration on the specified value. That is:

 origVal = *pdest
 if (*pdest == comp)
   then *pdest = exchange
 return origVal

Parameters:

	pdest	Pointer to the destination value.
	exchange	Exchange value (value to set destination to if destination == comparand)
	comp	The value to compare to destination.

Returns:: Original value of destination

int pte_osAtomicDecrement ( int * pdest )

Decrements the destination.

 origVal = *pdest
 *pdest++
 return origVal

Parameters:

pdest

Destination value to decrement

Returns:: Original destination value

int pte_osAtomicExchange	(	int *	pTarg,
		int	val
	)

Sets the target to the specified value as an atomic operation.

 origVal = *ptarg
 *ptarg = val
 return origVal

Parameters:

	pTarg	Pointer to the value to be exchanged.
	val	Value to be exchanged

Returns:: original value of destination

int pte_osAtomicExchangeAdd	(	int volatile *	pdest,
		int	value
	)

Adds the value to target as an atomic operation

 origVal = *pdest
 *pAddend += value
 return origVal

Parameters:

	pdest	Pointer to the variable to be updated.
	value	Value to be added to the variable.

Returns:: Original value of destination

pte_osResult pte_osInit ( void )

Provides a hook for the OSAL to implement any OS specific initialization. This is guaranteed to be called before any other OSAL function.

pte_osResult pte_osMutexCreate ( pte_osMutexHandle * pHandle )

Creates a mutex

Parameters:

pHandle

Set to the handle of the newly created mutex.

Returns:: PTE_OS_OK - Mutex successfully created
PTE_OS_NO_RESOURCESs - Insufficient resources to create mutex

pte_osResult pte_osMutexDelete ( pte_osMutexHandle handle )

Deletes a mutex and frees any associated resources.

Parameters:

handle

Handle of mutex to delete.

Returns:: PTE_OS_OK - Mutex successfully deleted.

pte_osResult pte_osMutexLock ( pte_osMutexHandle handle )

Locks the mutex

Parameters:

handle

Handle of mutex to lock.

Returns:: PTE_OS_OK - Mutex successfully locked.

pte_osResult pte_osMutexTimedLock	(	pte_osMutexHandle	handle,
		unsigned int	timeoutMsecs
	)

Locks the mutex, returning after timeoutMsecs if the resources is not available. Can be used for polling mutex by using timeoutMsecs of zero.

Parameters:

	handle	Handle of mutex to lock.
	timeoutMsecs	Number of milliseconds to wait for resource before returning.

Returns:: PTE_OS_OK - Mutex successfully locked.
PTE_OS_TIMEOUT - Timeout expired before lock was obtained.

pte_osResult pte_osMutexUnlock ( pte_osMutexHandle handle )

Unlocks the mutex

Parameters:

handle

Handle of mutex to unlock

Returns:: PTE_OS_OK - Mutex successfully unlocked.

pte_osResult pte_osSemaphoreCancellablePend	(	pte_osSemaphoreHandle	handle,
		unsigned int *	pTimeout
	)

Acquire a semaphore, returning after timeoutMsecs if the semaphore is not available. Can be used for polling a semaphore by using timeoutMsecs of zero. Call must return immediately if pte_osThreadCancel() is called on the thread waiting for the semaphore.

Parameters:

	handle	Handle of semaphore to acquire.
	pTimeout	Pointer to the number of milliseconds to wait to acquire the semaphore before returning. If set to NULL, wait forever.

Returns:: PTE_OS_OK - Semaphore successfully acquired.
PTE_OS_TIMEOUT - Timeout expired before semaphore was obtained.

pte_osResult pte_osSemaphoreCreate	(	int	initialValue,
		pte_osSemaphoreHandle *	pHandle
	)

Creates a semaphore

Parameters:

	initialValue	Initial value of the semaphore
	pHandle	Set to the handle of the newly created semaphore.

Returns:: PTE_OS_OK - Semaphore successfully created
PTE_OS_NO_RESOURCESs - Insufficient resources to create semaphore

pte_osResult pte_osSemaphoreDelete ( pte_osSemaphoreHandle handle )

Deletes a semaphore and frees any associated resources.

Parameters:

handle

Handle of semaphore to delete.

Returns:: PTE_OS_OK - Semaphore successfully deleted.

pte_osResult pte_osSemaphorePend	(	pte_osSemaphoreHandle	handle,
		unsigned int *	pTimeout
	)

Acquire a semaphore, returning after timeoutMsecs if the semaphore is not available. Can be used for polling a semaphore by using timeoutMsecs of zero.

Parameters:

	handle	Handle of semaphore to acquire.
	pTimeout	Pointer to the number of milliseconds to wait to acquire the semaphore before returning. If set to NULL, wait forever.

Returns:: PTE_OS_OK - Semaphore successfully acquired.
PTE_OS_TIMEOUT - Timeout expired before semaphore was obtained.

pte_osResult pte_osSemaphorePost	(	pte_osSemaphoreHandle	handle,
		int	count
	)

Posts to the semaphore

Parameters:

	handle	Semaphore to release
	count	Amount to increment the semaphore by.

Returns:: PTE_OS_OK - semaphore successfully released.

pte_osResult pte_osThreadCancel ( pte_osThreadHandle threadHandle )

Cancels the specified thread. This should cause pte_osSemaphoreCancellablePend() and for pte_osThreadCheckCancel() to return PTE_OS_INTERRUPTED.

Parameters:

threadHandle

handle to the thread to cancel.

Returns:: Thread successfully canceled.

pte_osResult pte_osThreadCheckCancel ( pte_osThreadHandle threadHandle )

Check if pte_osThreadCancel() has been called on the specified thread.

Parameters:

threadHandle

handle of thread to check the state of.

Returns:: PTE_OS_OK - Thread has not been cancelled
PTE_OS_INTERRUPTED - Thread has been cancelled.

pte_osResult pte_osThreadCreate	(	pte_osThreadEntryPoint	entryPoint,
		int	stackSize,
		int	initialPriority,
		void *	argv,
		pte_osThreadHandle *	ppte_osThreadHandle
	)

Creates a new thread. The thread must be started in a suspended state - it will be explicitly started when pte_osThreadStart() is called.

Parameters:

	entryPoint	Entry point to the new thread.
	stackSize	The initial stack size, in bytes. Note that this can be considered a minimum - for instance if the OS requires a larger stack space than what the caller specified.
	initialPriority	The priority that the new thread should be initially set to.
	argv	Parameter to pass to the new thread.
	ppte_osThreadHandle	set to the handle of the new thread.

Returns:: PTE_OS_OK - New thread successfully created.
PTE_OS_NO_RESOURCESs - Insufficient resources to create thread

pte_osResult pte_osThreadDelete ( pte_osThreadHandle handle )

Frees resources associated with the specified thread. This is called after the thread has terminated and is no longer needed (e.g. after pthread_join returns). This call will always be made from a different context than that of the target thread.

void pte_osThreadExit ( )

Causes the current thread to stop executing.

Returns:: Never returns (thread terminated)

pte_osResult pte_osThreadExitAndDelete ( pte_osThreadHandle handle )

Frees resources associated with the specified thread and then causes the thread to exit. This is called after the thread has terminated and is no longer needed (e.g. after pthread_join returns). This call will always be made from the context of the target thread.

int pte_osThreadGetDefaultPriority ( )

Returns the priority that should be used if the caller to pthread_create doesn't explicitly set one.

pte_osThreadHandle pte_osThreadGetHandle ( void )

Returns the handle of the currently executing thread.

int pte_osThreadGetMaxPriority ( )

Returns the maximum allowable priority

int pte_osThreadGetMinPriority ( )

Returns the minimum allowable priority

int pte_osThreadGetPriority ( pte_osThreadHandle threadHandle )

Returns the priority of the specified thread.

pte_osResult pte_osThreadSetPriority	(	pte_osThreadHandle	threadHandle,
		int	newPriority
	)

Sets the priority of the specified thread.

Returns:: PTE_OS_OK - thread priority successfully set

void pte_osThreadSleep ( unsigned int msecs )

Causes the current thread to sleep for the specified number of milliseconds.

pte_osResult pte_osThreadStart ( pte_osThreadHandle osThreadHandle )

Starts executing the specified thread.

Parameters:

osThreadHandle

handle of the thread to start.

Returns:: PTE_OS_OK - thread successfully started.

pte_osResult pte_osThreadWaitForEnd ( pte_osThreadHandle threadHandle )

Waits for the specified thread to end. If the thread has already terminated, this returns immediately.

Parameters:

threadHandle

Handle fo thread to wait for.

Returns:: PTE_OS_OK - specified thread terminated.

pte_osResult pte_osTlsAlloc ( unsigned int * pKey )

Allocates a new TLS key.

Parameters:

pKey

On success will be set to the newly allocated key.

Returns:: PTE_OS_OK - TLS key successfully allocated.
PTE_OS_NO_RESOURCESs - Insufficient resources to allocate key (e.g. maximum number of keys reached).

pte_osResult pte_osTlsFree ( unsigned int key )

Frees the specified TLS key.

Parameters:

index

TLS key to free

Returns:: PTE_OS_OK - TLS key was successfully freed.

void* pte_osTlsGetValue ( unsigned int key )

Retrieves the thread specific value for the specified key for the currently executing thread. If a value has not been set for this key, NULL should be returned (i.e. TLS values default to NULL).

Parameters:

index

The TLS key for the value.

Returns:: The value associated with key for the current thread.

void pte_osTlsInit ( void )

Initializes the OS TLS support. This is called by the PTE library prior to performing ANY TLS operation.

pte_osResult pte_osTlsSetValue	(	unsigned int	key,
		void *	value
	)

Sets the thread specific value for the specified key for the currently executing thread.

Parameters:

	index	The TLS key for the value.
	value	The value to save


Misc

enum	pte_osResult { PTE_OS_OK = 0, PTE_OS_NO_RESOURCES, PTE_OS_GENERAL_FAILURE, PTE_OS_TIMEOUT, PTE_OS_INTERRUPTED, PTE_OS_INVALID_PARAM }
pte_osResult	pte_osInit (void)
Threads

typedef int(*	pte_osThreadEntryPoint )(void *params)
pte_osResult	pte_osThreadCreate (pte_osThreadEntryPoint entryPoint, int stackSize, int initialPriority, void argv, pte_osThreadHandle ppte_osThreadHandle)
pte_osResult	pte_osThreadStart (pte_osThreadHandle osThreadHandle)
void	pte_osThreadExit ()
pte_osResult	pte_osThreadWaitForEnd (pte_osThreadHandle threadHandle)
pte_osThreadHandle	pte_osThreadGetHandle (void)
int	pte_osThreadGetPriority (pte_osThreadHandle threadHandle)
pte_osResult	pte_osThreadSetPriority (pte_osThreadHandle threadHandle, int newPriority)
pte_osResult	pte_osThreadDelete (pte_osThreadHandle handle)
pte_osResult	pte_osThreadExitAndDelete (pte_osThreadHandle handle)
pte_osResult	pte_osThreadCancel (pte_osThreadHandle threadHandle)
pte_osResult	pte_osThreadCheckCancel (pte_osThreadHandle threadHandle)
void	pte_osThreadSleep (unsigned int msecs)
int	pte_osThreadGetMaxPriority ()
int	pte_osThreadGetMinPriority ()
int	pte_osThreadGetDefaultPriority ()
Functions
Mutexes

pte_osResult	pte_osMutexCreate (pte_osMutexHandle *pHandle)
pte_osResult	pte_osMutexDelete (pte_osMutexHandle handle)
pte_osResult	pte_osMutexLock (pte_osMutexHandle handle)
pte_osResult	pte_osMutexTimedLock (pte_osMutexHandle handle, unsigned int timeoutMsecs)
pte_osResult	pte_osMutexUnlock (pte_osMutexHandle handle)
Semaphores

pte_osResult	pte_osSemaphoreCreate (int initialValue, pte_osSemaphoreHandle *pHandle)
pte_osResult	pte_osSemaphoreDelete (pte_osSemaphoreHandle handle)
pte_osResult	pte_osSemaphorePost (pte_osSemaphoreHandle handle, int count)
pte_osResult	pte_osSemaphorePend (pte_osSemaphoreHandle handle, unsigned int *pTimeout)
pte_osResult	pte_osSemaphoreCancellablePend (pte_osSemaphoreHandle handle, unsigned int *pTimeout)
Thread Local Storage

pte_osResult	pte_osTlsSetValue (unsigned int key, void *value)
void *	pte_osTlsGetValue (unsigned int key)
void	pte_osTlsInit (void)
pte_osResult	pte_osTlsAlloc (unsigned int *pKey)
pte_osResult	pte_osTlsFree (unsigned int key)
Atomic operations

int	pte_osAtomicExchange (int *pTarg, int val)
int	pte_osAtomicCompareExchange (int *pdest, int exchange, int comp)
int	pte_osAtomicExchangeAdd (int volatile *pdest, int value)
int	pte_osAtomicDecrement (int *pdest)

Projects/pthreads/pte_generic_osal.h File Reference

Misc

Threads

Functions

Typedef Documentation

Enumeration Type Documentation

Function Documentation