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.

Return
aMutexRef on success or NULL on failure.

const char *aMutex_Identifier(aMutexRef mutex)

Mutex Identifier.

Gets the character array that represents the mutex’ name.

Return
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.

Return
Function returns aErr values.
Parameters
  • mutex: - Valid MutexRef
Return Value
  • aErrNone: - If the Destruction was successful.
  • aErrParam: - If the MutexRef was invalid.

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
Function returns aErr values.
Return
aErrDuplicate - If a specific error occured locking the mutex.
Return Value
  • aErrNone: - Successfully aquired the lock.
  • aErrParam: - If the MutexRef was invalid.

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
Function returns aErr values.
Return Value
  • aErrNone: - Successfully aquired the lock.
  • aErrParam: - If the MutexRef was invalid.
  • aErrBusy: - If the lock was already in use.

aErr aMutex_Unlock(aMutexRef mutex)

Mutex Unlock.

Relenquish the lock on the mutex.

Return
Function returns aErr values.
Return Value
  • aErrNone: - Successfully unlocked mutex.
  • aErrParam: - If the MutexRef was invalid.
  • aErrPermission: - If the lock is owned by another thread.