aMutex.h

group aMutex

Platform Independent Synchronization Primitive.

aMutex.h Provides a platform independent synchronization mechanism. The link interface and the packe fifos both use this interface for synchronization between threads. Includes facilities for creating, locking and unlocking mutex primitives.

typedef void *aMutexRef

Typedef aMutexRef Opaque pointer to cross platform Mutex.

aMutexRef aMutex_Create(const char *name)

Create a Mutex.

Creates a Mutex element and uses the character array as the name of the mutex.

Returns:

aMutexRef on success or NULL on failure.

const char *aMutex_Identifier(aMutexRef mutex)

Mutex Identifier.

Gets the character array that represents the mutex’ name.

Returns:

A const null terminated character array. This call does not copy the character array, only presents it for use.

aErr aMutex_Destroy(aMutexRef *mutex)

Mutex Destroy.

Safely destroys a MutexRef, and frees its associated memory. Free should not be called on a MutexRef directly, and all Mutexs created with aMutex_Create must use aMutex_Destroy to free associated resources properly.

Parameters:

mutex – - Valid MutexRef

Return values:

  • aErrNone – - If the Destruction was successful.

  • aErrParam – - If the MutexRef was invalid.

Returns:

Function returns aErr values.

aErr aMutex_Lock(aMutexRef mutex)

Mutex Lock.

Blocking attempt to Lock the mutex. The call will not return until, the requesting thread gains control of the mutex, and successfully locks it or some unrecoverable error occured.

Return values:

  • aErrNone – - Successfully aquired the lock.

  • aErrParam – - If the MutexRef was invalid.

Returns:

Function returns aErr values.

Returns:

aErrDuplicate - If a specific error occured locking the mutex.

aErr aMutex_TryLock(aMutexRef mutex)

Mutex TryLock.

Non Blocking attempt to Lock the mutex. The call will return immediately with aErrBusy if another process or thread owns the lock.

Return values:

  • aErrNone – - Successfully aquired the lock.

  • aErrParam – - If the MutexRef was invalid.

  • aErrBusy – - If the lock was already in use.

Returns:

Function returns aErr values.

aErr aMutex_Unlock(aMutexRef mutex)

Mutex Unlock.

Relenquish the lock on the mutex.

Return values:

  • aErrNone – - Successfully unlocked mutex.

  • aErrParam – - If the MutexRef was invalid.

  • aErrPermission – - If the lock is owned by another thread.

Returns:

Function returns aErr values.