DosWaitEventSem: Difference between revisions

Revision as of 16:55, 17 May 2016

Syntax

rc = DosWaitEventSem( hevSemaphore, 
                      ulTimeOut );

Parameters

HEV hevSemaphore (input)

The handle of the semaphore wait on.

ULONG ulTimeout (input)

The number of milliseconds the function will wait before returning.

Set to SEM_IMMEDIATE_RETURN (0), the function will return immediately regardless of whether or not the semaphore is posted.
Set to SEM_INDEFINITE_WAIT (-1), the function will block indefinitely (forever) until the semaphore is posted.

Returns

 APIRET rc

The following values can be returned

0	NO_ERROR	Successfully waited for the event semaphore to be posted to
6	ERROR_INVALID_HANDLE	Error, The value in phevSemaphore does not point to a valid semaphore, The calling process must first have access to the semaphore in question
8	ERROR_NOT_ENOUGH_MEMORY	Error, The system memory limit has been exhausted
95	ERROR_INTERRUPT	Error, The thread has become unblocked by an external event such as an exception, ownership has not been obtained
640	ERROR_TIMEOUT	Error, The caller was blocked for ulTimeout milliseconds but no post was issued within this time limit, Time has expired

Include Info

#define INCL_DOSSEMAPHORES
#include <os2.h>

Usage Explanation

DosWaitEventSem blocks until the specified event semaphore is posted. Event semaphores are edge-triggered. This means that if the semaphore is posted and reset before a waiting thread has a chance to run, the waiting thread will still act as though the semaphore is posted.

Relevant Structures

Gotchas

The process calling DosWaitEventSem must first obtain access to the semaphore in question or ERROR_INVALID_HANDLE will be returned. If the thread to be blocked, waiting on an event semaphore, is a PM thread, WinWaitEventSem should be used instead of DosWaitEventSem. This will allow the message queue thread to continue processing.

Sample Code

 
#define INCL_DOSSEMAPHORES
#include 

HEV  hevMySemaphore;     /* MySemaphore handle */
ULONG TimeOut= -1;         /* the number of milliseconds the */
                           /* the caller will block for the sem */
                           /* this example will block forever */

	/* access is gained to the semaphore in question */
	/* either by DosCreateEventSem ... */
	/* ... or by DosOpenEventSem */
	/* its handle is placed in hevMySemaphore */

	rc = DosWaitEventSem(hevMySemaphore, TimeOut);

	if (rc != 0)
	{
	  /* We got an error to take care of. */
	}