Allocates and initializes a mutex.
#include <nks/synch.h>
NXMutex_t *NXMutexAlloc (
unsigned long flags,
NXHierarchy_t hierarchy,
const NXLockInfo_t *info);
(IN) Specifies the special attributes for the mutex and determines whether a mutex can be used recursively. By default (flags contains zero), a mutex is nonrecursive. If you want a recursive mutex, set flags to NX_MUTEX_RECURSIVE (0x00000001).
(IN) Specifies the hierarchy value to be associated with the mutex. It specifies the order in which this mutex can be acquired relative to other mutexes a context can own. If a context wants to acquire a mutex unconditionally, this value for the mutex being acquired must be greater than the value of any mutexes that the context is currently holding.
(IN) Points to the information block to be associated with the mutex.
If successful, returns a pointer to the allocated mutex; otherwise, returns a NULL pointer.
NXMutexAlloc allocates and initializes a mutually exclusive lock. Mutexes are acquired by threads on behalf of the context that they might be hosting.
NOTE:Because this function allocates and initializes, it should not be followed by a call to NXMutexInit.
Imposing strict ordering among all locks in the application that can be held by a context at the same time avoids deadlock. Hierarchy violations are checked only if the application is built with the compilation options, DEBUG and _LOCKTEST.
Nonrecursive mutexes can be implemented to work faster.
NXMutexAlloc cannot return an error. A NULL return can mean a failure by the implementation to allocate memory or an illegal flags value. It can also mean that the calling thread does not have sufficient NKS context or that the function was called at interrupt time.
For sample code, see Mutex.c.