You can use the following functions to work with mutex objects:
- RtCreateMutex is used to create a mutex object.
- RtOpenMutex is used to return a handle to the existing named mutex.
- RtReleaseMutex is used to release ownership of a mutex.
- RtWaitForSingleObject is used to wait for a mutex.
RtCreateMutex and RtOpenMutex
To synchronize threads running in multiple processes, a thread in each process must have its own process-relative handle to a single mutex object. These handles can be obtained by calling either RtCreateMutex or RtOpenMutex.
The first and most common way is for one thread in each process to call RtCreateMutex, passing a string for the parameter of mutex name. The name must be identical and use the same case and convention (ASCII or UNICODE). The first thread to call RtCreateMutex will cause the system to create the mutex object. As additional threads call RtCreateMutex, the system determines that a mutex with the specified name already exists; as a result, it does not create a new mutex object but returns a process-relative handle identifying the existing mutex object.
A thread can determine whether RtCreateMutex actually created a new mutex object by calling GetLastError right after the call to RtCreateMutex. If GetLastError reports ERROR_ALREADY_EXISTS, a new mutex object was not created.
Another method for obtaining the handle of a mutex involves a call to the RtOpenMutex. The dwDesiredAccess parameter is ignored. The lpName parameter is the zero-terminated string name of the mutex object. When the call to RtOpenMutex is made, the system scans all existing mutex objects to see if any of them have the same name. If the system finds a mutex object with the specified name, it creates a process-relative handle identifying the mutex and returns the handle to the calling thread. Any thread in the calling process can now use this handle in any function that accepts a mutex handle. If a mutex with the specified name cannot be found, null is returned.
If a mutex will only be used within a single process, the mutex object can be created without a name. In this case, only the handle is used to reference the mutex.
RtReleaseMutex
When the owning thread no longer needs to own the mutex object, it calls RtReleaseMutex. A thread that has been temporarily promoted to a higher priority uses this mechanism to release mutexes, and, when it has released all owned mutexes, eRTOS returns the thread's priority to the previous level.
While a thread has ownership of a mutex, it can specify the same mutex in additional wait function calls without blocking its execution. This prevents a thread from deadlocking itself while waiting for a mutex that it already owns. However, to release its ownership, the thread must call RtReleaseMutex once for each time that the mutex satisfied a wait.
RtWaitForSingleObject
You use RtWaitForSingleObject to wait for an interprocess communication object (IPC) to become available. IPC objects include semaphores, mutexes, and events. Mutexes are impacted by the priority promotion protocol set in the RTKernel configuration file. If a thread is waiting for a mutex, the thread that owns the mutex may have its priority raised to the same priority as the waiting thread in order to ensure the efficient operation of the real-time system.
- RtWaitForSingleObject waits for one eRTOS IPC object at a time. A thread can wait for a specified amount of time, after which processing continues even if the object is not signaled, or an infinite amount of time (the thread waits indefinitely until the object is signaled).
Note: RtWaitforSingleObjectEx performs the same function with high granularity of the time-out interval.
