DRAFT

SDL_SemWaitTimeout

Use this function to *lock a semaphore* with a timeout -or- as a variant of SDL_SemWait() with a timeout in milliseconds.

Syntax

int SDL_SemWaitTimeout(SDL_sem* sem,
                       Uint32   ms)

Function Parameters

sem

the semaphore to monitor

ms

the length of the timeout in milliseconds

Return Value

Returns 0 if the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not succeed in the allotted time, or a negative error code on failure; call SDL_GetError() for more information.

*
If the semaphore was not successfully locked, the semaphore will be unchanged.
*

Code Examples

*

res = SDL_SemWaitTimeout(my_sem, WAIT_TIMEOUT_MILLISEC);

if (res == SDL_MUTEX_TIMEDOUT) {
        return TRY_AGAIN;
}
if (res == -1) {
        return WAIT_ERROR;
}

...

SDL_SemPost(my_sem);

*
Note that the 1.2 ver used a different param so this example should be checked for compliance with the current syntax.

Remarks

On some platforms this function is implemented by looping with a delay of 1 ms, and so should be avoided if possible.

*
SDL_SemWaitTimeout() is a variant of SDL_SemWait() with a maximum timeout value. If the value of the semaphore pointed to by sem is positive, it will atomically decrement the semaphore value and return 0, otherwise it will wait up to ms milliseconds trying to lock the semaphore. This function is to be avoided if possible since on some platforms it is implemented by polling the semaphore every millisecond in a busy loop.

After SDL_SemWaitTimeout() is successful, the semaphore can be released and its count atomically incremented by a successful call to SDL_SemPost().
*


CategoryAPI, CategoryMutex

SDL_SemWaitTimeout (last edited 2010-10-18 02:14:40 by SheenaSmith)

Feedback
Please include your contact information if you'd like to receive a reply.
Submit