Creating a Muxwait Semaphore

DosCreateMuxWaitSem is used to create muxwait semaphores. This function also opens (obtains access to) the semaphore for the calling process and its threads. Threads in other processes must call DosOpenMuxWaitSem to open the semaphore before they can use it in any other muxwait semaphore function.

All the semaphores in the muxwait list must be created and opened before the muxwait list can be created.

The following code fragment creates five event semaphores and a corresponding array of semaphore records. The array is used to specify the semaphores included in the muxwait semaphore in the subsequent call to DosCreateMuxWaitSem.

#define INCL_DOSSEMAPHORES   /* DOS semaphore values */
#define INCL_DOSERRORS       /* DOS error values */
#include <os2.h>
#include <stdio.h>

int main(VOID) {
 HMUX      hmuxHandAny = NULLHANDLE;      /* Muxwait handle    */
 HEV       hev[5]      = {0};             /* Event semaphores  */
 SEMRECORD apsr[5]     = {{0}};           /* Semaphore records */
 APIRET    ulrc        = NO_ERROR;        /* Return code       */
 ULONG     ulLoop      = 0;               /* Loop count        */
 ULONG     ulSem       = 0;

for (ulLoop = 0; ulLoop < 5; ulLoop++) {
    ulrc = DosCreateEventSem((PSZ) NULL,
                             &hev[ulLoop],
                             0,
                             FALSE);

    if (ulrc != NO_ERROR) {
      printf("DosCreateEventSem error:  return code = %u\n",
             ulrc);
      return 1;
    }
    apsr[ulLoop].hsemCur = (HSEM) hev[ulLoop],
    apsr[ulLoop].ulUser = 0;
} /* end for */

ulrc = DosCreateMuxWaitSem((PSZ) NULL,
                           &hmuxHandAny,
                           5L,              /* Number of semaphores in list */
                           apsr,            /* Semaphore list               */
                           DCMW_WAIT_ANY);  /* Wait for any semaphore       */

    if (ulrc != NO_ERROR) {
      printf("DosCreateMuxWaitSem error:  return code = %u\n",
             ulrc);
      return 1;
    }


ulrc = DosWaitMuxWaitSem(hmuxHandAny,
                         SEM_IMMEDIATE_RETURN,
                         &ulSem);           /* No semaphores have been posted, so
                                               we should see a timeout below...    */

    if (ulrc != ERROR_TIMEOUT) {
      printf("DosWaitMuxWaitSem error:  return code = %u\n",
             ulrc);
      return 1;
    }

ulrc = DosDeleteMuxWaitSem(hmuxHandAny,
                           apsr[0].hsemCur);

    if (ulrc != NO_ERROR) {
      printf("DosDeleteMuxWaitSem error:  return code = %u\n",
             ulrc);
      return 1;
    }

ulrc = DosCloseMuxWaitSem(hmuxHandAny);
     if (ulrc != NO_ERROR) {
       printf("DosCloseMuxWaitSem error: return code = %u\n",
              ulrc);
       return 1;
     }

return NO_ERROR;
}

Muxwait 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 DosOpenMuxWaitSem 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.

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.

The following conditions apply to the kinds of semaphores that can be included in a muxwait-semaphore list:

• The list must contain either mutex semaphores or event semaphores. It cannot contain both at the same time and it cannot contain other muxwait semaphores.

• If the muxwait semaphore is shared, then all the semaphores in the list must also be shared.

• If the muxwait semaphore is private, then the semaphores in its list can be either private or shared.

If any of these conditions is violated, ERROR_WRONG_TYPE is returned.

The muxwait list can contain a maximum of 64 event semaphores or mutex semaphores. If an attempt is made to exceed this maximum, ERROR_TOO_MANY_SEMAPHORES is returned.

If the owners of any of the mutex semaphores in the muxwait semaphore list have ended without releasing them, ERROR_SEM_OWNER_DIED is returned. The thread should call DosQueryMutexSem for each mutex semaphore in the muxwait-semaphore list so that it can determine which semaphores are in the Owner Died state.

Each mutex semaphore that returns ERROR_SEM_OWNER_DIED from the query should be closed by calling DosCloseMutexSem. Also, because semaphore handles can be reused, the mutex semaphores that are closed must be deleted from the muxwait-semaphore list by calling DosDeleteMuxWaitSem.

OS/2 maintains a usage count for each semaphore. DosCreateMuxWaitSem initializes the usage count to 1. Thereafter, each call to DosOpenMuxWaitSem increments the count, and each call to DosCloseMuxWaitSem decrements it.

One parameter of this function is a pointer to an array of SEMRECORD data structures. Each data structure contains one semaphore record for each of the semaphores to be included in the muxwait semaphore. A semaphore record contains the handle and a programmer-defined identifier for that semaphore.