|
Size: 2168
Comment: update contents - pointers, structs
|
Size: 1264
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 2: | Line 2: |
| #pragma disable-camelcase ||<tablewidth="100%" style="color: #FF0000;" :> DRAFT|| |
#pragma camelcase off |
| Line 6: | Line 5: |
| Use this function to *lock a semaphore* ^with a timeout^ ''-or-'' ^as a^ variant of [[SDL_SemWait]]() with a timeout in milliseconds. | Use this function wait until a semaphore has a positive value and then decrements it. |
| Line 17: | Line 16: |
| ||'''sem'''||^the semaphore to monitor^|| | ||'''sem'''||the semaphore to wait on|| |
| Line 23: | Line 22: |
| *<<BR>>If the semaphore was not successfully locked, the semaphore will be unchanged.<<BR>>* |
|
| Line 26: | Line 23: |
| * {{{#!highlight cpp 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); }}} *<<BR>><<Color2(green,Note that the 1.2 ver used a different param so this example should be checked for compliance with the current syntax.)>> |
<<Include(SDL_CreateSemaphore, , , from="## Begin Semaphore Example", to="## End Semaphore Example")>> |
| Line 44: | Line 26: |
| On some platforms this function is implemented by looping with a delay of 1 ms, and so should be avoided if possible. *<<BR>>[[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]]().<<BR>>* |
This function suspends the calling thread until either the semaphore pointed to by '''sem''' has a positive value, the call is interrupted by a signal or error, or the specified time has elapsed. If the call is successful it will atomically decrement the semaphore value. |
| Line 51: | Line 29: |
| .[[SDL_SemPost]] * .[[SDL_SemTryWait]] * .[[SDL_SemValue]] * .[[SDL_SemWait]] * |
.[[SDL_CreateSemaphore]] .[[SDL_DestroySemaphore]] .[[SDL_SemPost]] .[[SDL_SemTryWait]] .[[SDL_SemValue]] .[[SDL_SemWait]] |
SDL_SemWaitTimeout
Use this function wait until a semaphore has a positive value and then decrements it.
Contents
Syntax
int SDL_SemWaitTimeout(SDL_sem* sem,
Uint32 ms)
Function Parameters
sem |
the semaphore to wait on |
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.
Code Examples
Typical use of semaphores:
SDL_atomic_t done;
SDL_sem *sem;
SDL_AtomicSet(&done, 0);
sem = SDL_CreateSemaphore(0);
.
.
Thread A:
while (!SDL_AtomicGet(&done)) {
add_data_to_queue();
SDL_SemPost(sem);
}
Thread B:
while (!SDL_AtomicGet(&done)) {
SDL_SemWait(sem);
if (data_available()) {
get_data_from_queue();
}
}
.
.
SDL_AtomicSet(&done, 1);
SDL_SemPost(sem);
wait_for_threads();
SDL_DestroySemaphore(sem);
Remarks
This function suspends the calling thread until either the semaphore pointed to by sem has a positive value, the call is interrupted by a signal or error, or the specified time has elapsed. If the call is successful it will atomically decrement the semaphore value.
