DosSemRequest

This call obtains a semaphore and sets the semaphore as owned by the thread that requested it.

Syntax

DosSemRequest (SemHandle, Timeout)

Parameters

SemHandle (HSEM) - input 

Reference to the semaphore.

For a system semaphore, this reference is the handle returned by a DosCreateSem or DosOpenSem request that granted the requesting thread access to the semaphore.

For a RAM semaphore, this reference is the address of a doubleword of storage, allocated and initialized to zero by the application. This sets the semaphore as unowned. Other than initializing the doubleword to zero, an application must not modify a RAM semaphore directly; instead it manipulates the semaphore with semaphore function calls.

Timeout (LONG) - input 

Action taken by the requesting thread when the semaphore is owned by another thread. The values that can be specified are:

-1 - The requesting thread waits indefinitely for the semaphore to be cleared.

0 - The requesting thread returns immediately.

>0 - The requesting thread waits the indicated number of milliseconds for the semaphore to be cleared before resuming execution.

Return Code

rc (USHORT) - return

Return code descriptions are:

• 0 NO_ERROR
• 95 ERROR_INTERRUPT
• 100 ERROR_TOO_MANY_SEMAPHORES
• 105 ERROR_SEM_OWNER_DIED
• 121 ERROR_SEM_TIMEOUT

Remarks

Typically, DosSemRequest is called to set a semaphore for the purpose of accessing a protected resource. DosSemRequest checks the status of the semaphore. If the semaphore is not set (that is, not owned) by another thread, DosSemRequest sets the semaphore as owned by the current thread and returns immediately to the caller.

If the semaphore is already owned by another thread, DosSemRequest optionally can block the requesting thread until the semaphore becomes available. The unblocking of a thread blocked by a DosSemRequest is level-triggered. That is, DosSemRequest does not return until the semaphore remains clear long enough for the affected thread to be redispatched and successfully claim the semaphore. Thus, if a number of threads are blocked indefinitely on DosSemRequest calls for the semaphore, only the thread that sets the semaphore is actually unblocked. If a milliseconds value is specified for the Timeout parameter, this places an upper limit on the amount of time the requesting thread remains blocked, waiting for the semaphore to become available.

When a thread no longer requires the protected resource, it issues DosSemClear to clear the semaphore, so another thread may claim it with a successful DosSemRequest. If the semaphore is an exclusive system semaphore, it has a use count associated with it, which is incremented by a DosSemRequest and decremented by a DosSemClear. The semaphore is not actually cleared and made available to the next thread that wants to access the resource until the semaphore has been cleared the same number of times it has been requested. This means that exclusive system semaphores can be used in recursive routines. When the use count is 0, the semaphore is available to be claimed by the next user of the protected resource.

If a process terminates while owning a nonexclusive system semaphore, ERROR_SEM_OWNER_DIED is returned to the thread that next gets the semaphore through DosSemRequest. That thread takes steps to ensure the integrity of the resource. The thread can release the resource by issuing a DosSemClear, or it can reset the ERROR_SEM_OWNER_DIED return code condition flagged in the semaphore data structure.

Note

To request a Fast-Safe RAM semaphore, a thread calls DosFSRamSemRequest.

Bindings

C

#define INCL_DOSSEMAPHORES

USHORT  rc = DosSemRequest(SemHandle, Timeout);

HSEM    SemHandle;     /* Semaphore handle */
LONG    Timeout;       /* Timeout (in milliseconds) */
USHORT  rc;            /* return code */

MASM

EXTRN  DosSemRequest:FAR
INCL_DOSSEMAPHORES  EQU 1

PUSH   DWORD   SemHandle     ;Semaphore handle
PUSH   DWORD   Timeout       ;Timeout (in milliseconds)
CALL   DosSemRequest

Returns WORD

Example

The following example illustrates the serialization of access to a shared resource between threads of the same process. The program creates a nonexclusive system semaphore named resource.sem, requests access to the semaphore, clears it, and finally closes the semaphore. For an illustration of notification of events, see the example given in DosOpenSem, DosSemSet, or DosSemWait.

#define INCL_DOSSEMAPHORES

#include <os2.h>

#define SEM_NAME "\\SEM\\resource.sem"  /* Semaphore name */
#define TIMEOUT 1500L                   /* Timeout (in milliseconds) */

main()
{
  HSEM SemHandle;
  USHORT rc;

  /* Note: the semaphore could have been created by another    */
  /*       thread.                                             */

  DosCreateSem(CSEM_PUBLIC,         /* Ownership - nonexclusive */
               &SemHandle,          /* Semaphore handle (returned) */
               SEM_NAME);           /* Semaphore name */
  if(!(rc = DosSemRequest(SemHandle,       /* Semaphore Handle */
                         TIMEOUT)))        /* Timeout Period   */
  {

    /* Semaphore obtained; resource may now be used. */
    /* Clear the semaphore after using resource.     */

    if(DosSemClear(SemHandle))
    {
      /* Semaphore exclusively owned by another process --  */
      /* cannot clear now.                                  */
    }
  }
  else
  {
    /* Semaphore not obtained: error processing (i.e. switch on rc) */
  }
  /* Semaphore no longer needed; close it */
  if(DosCloseSem(SemHandle))
  {
    /* Semaphore is still set -- cannot close now */
  }
}