The following functions are available to initialize and use Semaphore objects.
- RtCreateSemaphore is used to create a semaphore object
- RtOpenSemaphore is used to return a handle to the existing named semaphore.
- RtWaitForSingleObject is used to wait for a semaphore.
- RtWaitForMultipleObjects is used to wait for the first of several objects to become available.
Using RtCreateSemaphore
The first and most common way is for one thread in each process to call RtCreateSemaphore, passing the identical string for the parameter of RTSS semaphore name. The first thread to call RtCreateSemaphore will cause the system to create the RTSS semaphore object. As additional threads call RtCreateSemaphore, the system determines that an RTSS semaphore object with the specified name already exists; as a result, it does not create a new RTSS semaphore object but returns a process-relative handle identifying the existing RTSS semaphore object.
A thread can determine whether RtCreateSemaphore actually created a new RTSS semaphore object by calling GetLastError immediately after the call to RtCreateSemaphore. If GetLastError reports ERROR_ALREADY_EXISTS, a new RTSS semaphore object was not created.
Using RtOpenSemaphore
Another method for obtaining the handle of an RTSS semaphore object involves a call to RtOpenSemaphore. The dwDesiredAccess parameter is ignored. The lpName parameter is the zero-terminated string name of the RTSS semaphore object. When the call to RtOpenSemaphore is made, the system scans all existing RTSS semaphore objects to see if any of them have the same name indicated by lpName. If the system finds an RTSS semaphore object with the specified name, it creates a process-relative handle identifying the RTSS semaphore object 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 semaphore handle. If an RTSS semaphore object with the specified name cannot be found, null is returned.
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.
RtWaitForSingleObject waits for one RTX64 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).
RtWaitForMultipleObjects waits for up to 16 RTX64 IPC objects. The first object to become available causes the wait to be broken. The RtWaitForMultipleObjects function only supports WAIT FOR ANY object, making it possible for processing to start before all the objects the thread is waiting for are signaled.
