HANDLE osCreateMutex( SYSNAME Name, BOOL InitialOwner );
The name of the mutex object (can be NULL).
If this value is TRUE, the calling task requesting the creation of the mutex object immediately gains ownership. If FALSE, the mutex is created in an unowned state. This parameter may only be set to TRUE when the function is called from a task context.
On success, the return value is a handle to the newly created mutex object. On failure, the function returns NULL_HANDLE. To retrieve extended error information, call the osGetLastError function.
This function creates a mutex object.
Mutexes are synchronization primitives used to manage access to critical sections. Code protected by a mutex-controlled critical section is guaranteed to be executed by no more than one task at any given time.
An optional name may be assigned to the mutex during creation, allowing other tasks to obtain a handle to it via the osOpenMutex function. When a mutex is no longer required, it should be closed using osCloseHandle. The mutex object is deleted only after all tasks that opened the handle have closed it. Further details are available in the system objects management section.
If no osOpen* functions are referenced in the application, the system ignores object names and the name management logic is excluded from the build. This optimization reduces the final binary size. For more information regarding object naming and opening, see the system objects management section.
The mutex can be initially owned by the creating task if the InitialOwner parameter is set to TRUE. For more information regarding mutex ownership, please refer to the mutex objects section.
This function is available only when the OS_USE_MUTEX configuration constant is set to 1.
| Version: | 1.0 |
|---|---|
| Header file: | OS_Mutex.h (include OS_API.h) |
| See also: | BOOL, FALSE, HANDLE, mutexes, NULL, NULL_HANDLE, OS_OPEN_MUTEX_FUNC, osCloseHandle, osGetLastError, osOpenMutex, SYSNAME, system objects management, TRUE |