DosRequestMutexSem: Difference between revisions
mNo edit summary |
|||
| Line 1: | Line 1: | ||
=== Syntax === | === Syntax === | ||
rc = DosRequestMutexSem( ''hmtxSemaphore'', | rc = DosRequestMutexSem( ''hmtxSemaphore'', | ||
''ulTimeOut'' ); | ''ulTimeOut'' ); | ||
=== Parameters === | === Parameters === | ||
HMTX ''hmtxSemaphore'' (input) | ;HMTX ''hmtxSemaphore'' (input):The handle of the semaphore to be released. | ||
;ULONG ''ulTimeout'' (input):The number of milliseconds the function will wait before | |||
The handle of the semaphore to be released. | |||
ULONG ''ulTimeout'' (input) | |||
The number of milliseconds the function will wait before | |||
returning. | returning. | ||
* Set to '''SEM_IMMEDIATE_RETURN''' (0), the function will return immediately regardless of whether or not the semaphore is free. | * Set to '''SEM_IMMEDIATE_RETURN''' (0), the function will return immediately regardless of whether or not the semaphore is free. | ||
* Set to '''SEM_INDEFINITE_WAIT''' (-1), the function will block indefinitely (forever) until the semaphore becomes free and ownership is obtained. | * Set to '''SEM_INDEFINITE_WAIT''' (-1), the function will block indefinitely (forever) until the semaphore becomes free and ownership is obtained. | ||
=== Returns === | === Returns === | ||
APIRET rc | APIRET rc | ||
The following values can be returned | The following values can be returned | ||
{|class="wikitable" | |||
{| | |||
|0 | |0 | ||
|NO_ERROR | |NO_ERROR | ||
| Line 48: | Line 37: | ||
|ERROR_TIMEOUT | |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 | |Error, The caller was blocked for ''ulTimeout'' milliseconds but ownership of the semaphore could not be obtained within this time limit, Time has expired | ||
|} | |} | ||
=== Include Info === | === Include Info === | ||
#define INCL_DOSSEMAPHORES | #define INCL_DOSSEMAPHORES | ||
#include | #include <os2.h> | ||
=== Usage Explanation === | === Usage Explanation === | ||
DosRequestMutexSem blocks until ownership of a mutex semaphore may be obtained. | |||
DosRequestMutexSem blocks until ownership of a mutex semaphore may | Ownership of a semaphore with multiple threads requesting it is granted to the thread with the highest priority. Among threads with the same priority, ownership is granted in a First-In-First-Out (FIFO) manner. | ||
be obtained. | |||
Ownership of a semaphore with multiple threads requesting it is | |||
granted to the thread with the highest priority. Among threads | |||
with the same priority, ownership is granted in a First-In-First-Out | |||
(FIFO) manner. | |||
=== Gotchas === | === Gotchas === | ||
The process calling DosRequestMutexSem must first obtain access to the semaphore in question or ERROR_INVALID_HANDLE will be returned. | |||
The process calling DosRequestMutexSem must first obtain access to | |||
the semaphore in question or ERROR_INVALID_HANDLE will be returned. | |||
=== Sample Code === | === Sample Code === | ||
| Line 94: | Line 71: | ||
/* We got an error to take care of. */ | /* We got an error to take care of. */ | ||
} | } | ||
</pre> | </pre> | ||
=== See Also === | === See Also === | ||
[[ | *[[DosCloseMutexSem]] | ||
[[ | *[[DosCreateMutexSem]] | ||
[[ | *[[DosOpenMutexSem]] | ||
[[ | *[[DosQueryMutexSem]] | ||
[[ | *[[DosReleaseMutexSem]] | ||
[[Category: | [[Category:Dos]] | ||
Revision as of 15:39, 5 December 2016
Syntax
rc = DosRequestMutexSem( hmtxSemaphore,
ulTimeOut );
Parameters
- HMTX hmtxSemaphore (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 free.
- Set to SEM_INDEFINITE_WAIT (-1), the function will block indefinitely (forever) until the semaphore becomes free and ownership is obtained.
Returns
APIRET rc
The following values can be returned
| 0 | NO_ERROR | Successfully obtained semaphore ownership |
| 6 | ERROR_INVALID_HANDLE | Error, The value in phmtxSemaphore does not point to a valid semaphore, The calling process must first have access to the semaphore in question |
| 95 | ERROR_INTERRUPT | Error, The thread has become unblocked by an external event such as an exception, ownership has not been obtained |
| 103 | ERROR_TOO_MANY_SEM_REQUESTS | Error, The semaphore usage count system limit, of 65535, has been exceeded |
| 105 | ERROR_SEM_OWNER_DIED | Error, The semaphore owner has died without releasing the semaphore |
| 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 |
Include Info
#define INCL_DOSSEMAPHORES #include <os2.h>
Usage Explanation
DosRequestMutexSem blocks until ownership of a mutex semaphore may be obtained. Ownership of a semaphore with multiple threads requesting it is granted to the thread with the highest priority. Among threads with the same priority, ownership is granted in a First-In-First-Out (FIFO) manner.
Gotchas
The process calling DosRequestMutexSem must first obtain access to the semaphore in question or ERROR_INVALID_HANDLE will be returned.
Sample Code
#define INCL_DOSSEMAPHORES
#include
HMTX hmtxMySemaphore; /* 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 DosCreateMutexSem ... */
/* ... or by DosOpenMutexSem */
/* its handle is placed in hmtxMySemaphore */
rc = DosRequestMutexSem(hmtxMySemaphore, TimeOut);
if (rc != 0)
{
/* We got an error to take care of. */
}