WinWaitEventSem: Difference between revisions
| (4 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
WinWaitEventSem 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. | |||
=== Syntax === | === Syntax === | ||
WinWaitEventSem( ''hevSemaphore'', ''ulTimeOut'' ) | |||
=== Parameters === | === Parameters === | ||
;HEV ''hevSemaphore'' (input):The handle of the semaphore to be released. | |||
;ULONG ''ulTimeout'' (input):The number of milliseconds the function will wait before returning. | |||
The handle of the semaphore to be released. | :* 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. | |||
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 === | === Returns === | ||
APIRET rc | |||
The following values can be returned | The following values can be returned: | ||
{|class="wikitable" | |||
{| | |||
|0 | |0 | ||
|NO_ERROR | |NO_ERROR | ||
|Successfully | |Successfully obtained semaphore ownership | ||
obtained semaphore ownership | |||
|- | |- | ||
|6 | |6 | ||
|ERROR_INVALID_HANDLE | |ERROR_INVALID_HANDLE | ||
|Error, The value in ''phevSemaphore'' does not point to a valid | |Error, The value in ''phevSemaphore'' does not point to a valid semaphore, The calling process must first have access to the semaphore in question | ||
semaphore, The calling process must first have access to the semaphore in | |||
question | |||
|- | |- | ||
|8 | |8 | ||
| Line 42: | Line 28: | ||
|95 | |95 | ||
|ERROR_INTERRUPT | |ERROR_INTERRUPT | ||
|Error, | |Error, The thread has become unblocked by an external event such as an exception, ownership | ||
The thread has become unblocked by an external event such as an exception, ownership | |||
has not been obtained | has not been obtained | ||
|- | |- | ||
|640 | |640 | ||
|ERROR_TIMEOUT | |ERROR_TIMEOUT | ||
|Error, | |Error, The caller was blocked for ''ulTimeout'' milliseconds but ownership of the semaphore could not be obtained within this time limit, Time has expired. | ||
The caller was blocked for ''ulTimeout'' milliseconds but ownership of the | |} | ||
semaphore could not be obtained within this time limit, Time has expired | |||
|} | |||
=== Gotchas === | === Gotchas === | ||
The process calling WinWaitEventSem must first obtain access to the semaphore in question or ERROR_INVALID_HANDLE will be returned. | The process calling WinWaitEventSem 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 not a PM thread, [[ | If the thread to be blocked, waiting on an event semaphore, is not a PM thread, [[DosWaitEventSem]] should be used instead of WinWaitEventSem. | ||
=== Sample Code === | === Sample Code === | ||
<pre> | <pre> | ||
#define INCL_WINMESSAGEMGR | #define INCL_WINMESSAGEMGR | ||
#include | #include <os2.h> | ||
HEV hevMySemaphore; /* MySemaphore handle */ | HEV hevMySemaphore; /* MySemaphore handle */ | ||
| Line 95: | Line 62: | ||
/* We got an error to take care of. */ | /* We got an error to take care of. */ | ||
} | } | ||
</pre> | </pre> | ||
=== See Also === | === See Also === | ||
[[ | * [[DosCloseEventSem]] | ||
[[ | * [[DosCreateEventSem]] | ||
[[ | * [[DosOpenEventSem]] | ||
[[ | * [[DosPostEventSem]] | ||
[[ | * [[DosQueryEventSem]] | ||
[[ | * [[DosResetEventSem]] | ||
[[ | * [[DosWaitEventSem]] | ||
[[Category: | [[Category:Win]] | ||
Latest revision as of 19:21, 14 May 2025
WinWaitEventSem 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.
Syntax
WinWaitEventSem( hevSemaphore, ulTimeOut )
Parameters
- HEV hevSemaphore (input)
- The handle of the semaphore to be released.
- 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 obtained semaphore ownership |
| 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 ownership of the semaphore could not be obtained within this time limit, Time has expired. |
Gotchas
The process calling WinWaitEventSem 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 not a PM thread, DosWaitEventSem should be used instead of WinWaitEventSem.
Sample Code
#define INCL_WINMESSAGEMGR
#include <os2.h>
HEV hevMySemaphore; /* MySemaphore handle */
ULONG TimeOut= -1; /* the number of milliseconds the */
/* the caller will block for the sem */
/* this example will block forever */
APIRET rc; /* return code */
/* access is gained to the semaphore in question */
/* either by DosCreateEventSem ... */
/* ... or by DosOpenEventSem */
/* its handle is placed in hevMySemaphore */
rc = WinWaitEventSem(hevMySemaphore, TimeOut);
if (rc != 0)
{
/* We got an error to take care of. */
}