Creating an Event Semaphore

Processes create an event semaphore by using DosCreateEventSem. The process that controls the event or resource is usually the one that creates the semaphore, but it does not have to be.

Threads in the process that creates the semaphore do not have to open the semaphore before using it. DosCreateEventSem obtains access to the semaphore for the calling process and its threads. Threads in other processes must call DosOpenEventSem to open the semaphore before they can use it.

Event semaphores can be defined as either private or shared:

• Private semaphores are always unnamed and are therefore always identified by their handles. They can be used only by threads within a single process.

• Shared semaphores can be either named or unnamed. If named, they can be opened using either the name or the handle. The handle returned by DosOpenEventSem is then used to identify the semaphore for all other functions. Semaphore names must include the prefix \SEM32\ and must conform to file system naming conventions. Shared semaphores can be used by threads in multiple processes.

In the following code fragment, the controlling process creates a named event semaphore and posts the semaphore after writing data to a shared file:

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

    HEV hevWriteEvent;

    DosCreateEventSem("\\sem32\\wrtevent",          /* Named-shared semaphore */
                       &hevWriteEvent, 0, FALSE);   /* Initially reset        */
        .
        .
        /* Write data to shared file. */
        .
        .
    DosPostEventSem(hevWriteEvent);                 /* Posts the event        */
        .
        .    /* Continue execution. */
        .

There is a system-wide limit of 65536 (64K) shared semaphores (including mutex, event, and muxwait semaphores); in addition, each process can have up to 65536 (64K) private semaphores.

When an event semaphore is created, a flag is used to specify the initial state of the event semaphore, either reset or posted. If the initial state is reset, a thread that calls DosWaitEventSem will be blocked until a process that has access to the semaphore uses DosPostEventSem to post the event semaphore. If the initial state is posted, then a thread that calls DosWaitEventSem will return immediately to continue its execution. If the thread calling DosWaitEventSem is not in the process that created the semaphore, the thread must open the semaphore with DosOpenEventSem before calling DosWaitEventSem.

OS/2 maintains a usage count for each semaphore. DosCreateEventSem initializes the usage count to 1. Thereafter, each call to DosOpenEventSem increments the count, and each call to DosCloseEventSem decrements it.