Mutex Functions

You can use the following functions to work with mutex objects:

RtCreateMutex and RtOpenMutex

To synchronize threads running in multiple processes, including RTSS processes and Win32 processes, a thread in each process must have its own process-relative handle to a single RTSS 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 RTSS 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 RTSS mutex object. As additional threads call RtCreateMutex, the system determines that an RTSS mutex with the specified name already exists; as a result, it does not create a new RTSS mutex object but returns a process-relative handle identifying the existing RTSS mutex object.

A thread can determine whether RtCreateMutex actually created a new RTSS mutex object by calling GetLastError right after the call to RtCreateMutex. If GetLastError reports ERROR_ALREADY_EXISTS, a new RTSS mutex object was not created.

Another method for obtaining the handle of an RTSS mutex involves a call to the RtOpenMutex. The dwDesiredAccess parameter is ignored. The lpName parameter is the zero-terminated string name of the RTSS mutex object. When the call to RtOpenMutex is made, the system scans all existing RTSS mutex objects to see if any of them have the same name. If the system finds an RTSS mutex object with the specified name, it creates a process-relative handle identifying the RTSS 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 an RTSS mutex handle. If an RTSS 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, RTX 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 and RtWaitForMultipleObjects

You use RtWaitForSingleObject and RtWaitForMultipleObjects to wait for an interprocess communication object (IPC) to become available. IPC objects include semaphores, mutexes, and events. 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 realtime system.