DRAFT

SDL_SemTryWait

Use this function to as a non-blocking variant of alternative to SDL_SemWait() -or- ...*to attempt to lock a semaphore but don't not suspend the thread*.

Syntax

int SDL_SemTryWait(SDL_sem* sem)

Function Parameters

sem

the semaphore to decrement

Return Value

Returns 0 if the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait would block, or a negative error code on failure; call SDL_GetError() for more information.

-or-

*
Modified slightly from the old wiki: Returns 0 if the semaphore was successfully locked (and decremented), SDL_MUTEX_TIMEDOUT if the thread would have suspended, or a negative error code on failure.

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

Code Examples

*

res = SDL_SemTryWait(my_sem);

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

...

SDL_SemPost(my_sem);

*

Remarks

You can add useful comments here

*
SDL_SemTryWait() is a non-blocking variant of SDL_SemWait(). 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 return SDL_MUTEX_TIMEDOUT instead of suspending the thread.

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

Seems like this should have some explanation that you would choose this function if you have a thread that will be ruined if it is blocked but it would be better if it could be stalled a bit if necessary and possible. As compared to SDL_SemWait which will block the thread regardless of the result to the thread. Is that right?


CategoryAPI, CategoryMutex

SDL_SemTryWait (last edited 2010-10-18 02:15:54 by SheenaSmith)

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