Resetting an Event Semaphore

DosResetEventSem resets an event semaphore if it is not already reset, and returns the number of times the semaphore was posted since it was last reset. All threads that subsequently call DosWaitEventSem for this semaphore will be blocked.

Any thread belonging to the process that created the event semaphore can change the state of the semaphore to reset by calling DosResetEventSem. Threads in other processes can also call DosResetEventSem, but they must first gain access to the semaphore by calling DosOpenEventSem.

When an event semaphore is in the reset state, any thread that calls DosWaitEventSem to wait for the semaphore will be blocked. When the event semaphore is posted, all of the threads that are waiting for the semaphore are released to continue execution.

The following code fragment resets an event semaphore. Assume that the handle of the semaphore has been placed into HEV already.

    #define INCL_DOSSEMAPHORES   /* Semaphore values */
    #include <os2.h>
    #include <stdio.h>

    HEV     hev;        /* Event semaphore handle                        */
    ULONG   ulPostCt;   /* Post count for the event semaphore (returned) */
    APIRET  ulrc;       /* Return code                                   */

    ulrc = DosResetEventSem(hev, &ulPostCt);

    if (ulrc != 0) {
        printf("DosResetEventSem error: return code = %ld",
               ulrc);
        return;
    }

DosResetEventSem returns the post count of the event semaphore and resets the post count to 0. The post count is the number of times the semaphore has been posted (using DosPostEventSem) since the last time the semaphore was in the reset state. (An event semaphore can be reset when it is created, as well as by calling DosResetEventSem.) The post count can also be obtained by calling DosQueryEventSem.

If the event semaphore is already reset when DosResetEventSem is called, ERROR_ALREADY_RESET is returned, along with a post count of 0. The semaphore is not reset a second time.