DRAFT

SDL_SemWait

Use this function to suspend the calling thread until the semaphore pointed to by sem has a positive count, then atomically decrease the semaphore count -or- ...suspend the calling thread until the semaphore can be atomically decremented -or- *lock a semaphore and suspend the thread if the semaphore value is zero*.

Syntax

int SDL_SemWait(SDL_sem* sem)

Function Parameters

sem

the semaphore to monitor

Return Value

Returns 0 on success 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

*

if (SDL_SemWait(my_sem) == -1) {
        return WAIT_FAILED;
}

...

SDL_SemPost(my_sem);

*

Remarks

*
SDL_SemWait() suspends the calling thread until either the semaphore pointed to by sem has a positive value or the call is interrupted by a signal or error. If the call is successful it will atomically decrement the semaphore value.

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

Should the Remarks include any discussion of locking and unlocking for clarity? For example is the lock/unlock pair a built-in feature of this function or does the programmer have to 'manually' lock then unlock the semaphore or thread when using this function? Would it be beneficial to a user to have some discussion of that here or is it just understood/given?


CategoryAPI, CategoryMutex

SDL_SemWait (last edited 2010-10-18 02:17:46 by SheenaSmith)

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