|
Size: 1027
Comment: add RF
|
Size: 2022
Comment: update content (old wiki)
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 6: | Line 6: |
| Use this function to suspend the calling thread until the semaphore pointed to by '''sem''' has a positive count, then atomically (?? automatically ??) decrease the semaphore count. | 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*. |
| Line 16: | Line 16: |
| ||'''sem'''||^a pointer to the SDL_sem structure to be monitored^|| | ||'''sem'''||^a pointer to the SDL_sem structure / semaphore to be monitored^|| |
| Line 19: | Line 19: |
| Returns ^the count less the portion allocated when the resource becomes available and re-allocated^ ,,on success,,, ^0 on busy/unavailable^, or a negative error code on failure; call [[SDL_GetError]]() for more information. ??? | 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. ??? |
| Line 22: | Line 24: |
| * | |
| Line 23: | Line 26: |
| You can add your code example here | if (SDL_SemWait(my_sem) == -1) { return WAIT_FAILED; } ... SDL_SemPost(my_sem); |
| Line 25: | Line 34: |
| * | |
| Line 27: | Line 37: |
| ''You can add useful comments here'' | *<<BR>>[[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]](). <<BR>>* <<Color2(green,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?)>> |
| Line 30: | Line 44: |
| .[[SDL_SemTryWait]] ??? .[[SDL_SemWaitTimeout]] ??? |
.[[SDL_SemPost]] * .[[SDL_SemTryWait]] * .[[SDL_SemValue]] * .[[SDL_SemWaitTimeout]] * |
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*.
Contents
Syntax
int SDL_SemWait(SDL_sem* sem)
Function Parameters
sem |
a pointer to the SDL_sem structure / semaphore to be monitored |
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().
*
green
