|
Size: 1877
Comment: update content - pointers, structs
|
Size: 2183
Comment: Added explanatory content
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 3: | Line 3: |
| ||<tablewidth="100%" style="color: #FF0000;" :> DRAFT|| | ||<tablewidth="100%"style="color: rgb(255, 0, 0); text-align: center;">DRAFT || |
| Line 6: | Line 7: |
| Use this function to ^wait on a condition variable for a fixed delay^ ''-or-'' *with timeout*. <<Color2(green,The description in the header is too long and too detailed. Tried to write a simple summary. Should it be the longer description here instead?<<BR>>Waits for at most '''ms''' milliseconds and returns 0 if the condition variable is signaled SDL_MUTEX_TIMEDOUT if the condition is not signaled in the allotted time and -1 on error. (with appropriate commas that don't work in green))>> |
Use this function to coordinate threads in a multi-threaded environment. This function will wait for the condition variable to be signaled for the number of milliseconds passed in. If the time length requested elapses prior to the condition being signaled, this function returns with a SDL_MUTEX_TIMEDOUT value, otherwise it returns '0' meaning that the condition has been signaled. Thus function also unlocks the passed in mutex prior to waiting on the condition signal, and locks the mutex upon the condition being signaled, or the timeout. |
| Line 18: | Line 17: |
| == Function Parameters == ||'''cond''' ||^The condition pointer whose signal will be waited on. ^ || ||'''mutex''' ||^Mutex pointer used by user code to gate thread access. ^ || ||'''ms''' ||^The maximum time to wait in milliseconds. Set to SDL_MUTEX_MAXWAIT for infinite wait. ^ || |
|
| Line 19: | Line 22: |
| == Function Parameters == ||'''cond'''||^the applicable condition variable^ ???|| ||'''mutex'''||^a pointer to the mutex to be timed out^ ???|| ||'''ms'''||^the maximum number of milliseconds to wait^|| |
|
| Line 31: | Line 30: |
| == Remarks == '''mutex''' must be locked prior to calling this function. This function unlocks '''mutex''', and it remains unlocked while this function waits for the condition signal, or the timeout to occur. In this way other threads within your program are free to make use of the shared resources while this function is in the waiting state. |
|
| Line 32: | Line 33: |
| == Remarks == *<<BR>>'''mutex''' is unlocked so it must be locked when the function is called and it will ,,re-,, ^un^lock afterward. |
When either the condition is signaled, or the timeout occurs, this function will lock '''mutex, '''prior to returning. |
| Line 35: | Line 35: |
| <<Color2(green,Is this a typo in the old wiki - ''re'' vs ''un''lock? Does the function handle the locking/unlocking or does the programmer need to do that?)>><<BR>>* On some platforms this function is implemented by looping with a delay of 1 ms, and so should be avoided if possible. |
On some platforms this function is implemented by looping with a delay of 1 ms, and so should be avoided if possible. |
| Line 40: | Line 38: |
| .[[SDL_CondWait]] * | . [[SDL_CondWait]] * |
| Line 43: | Line 41: |
| [[CategoryAPI]], [[CategoryMutex]] | [[CategoryAPI]], CategoryMutex |
DRAFT |
SDL_CondWaitTimeout
Use this function to coordinate threads in a multi-threaded environment. This function will wait for the condition variable to be signaled for the number of milliseconds passed in. If the time length requested elapses prior to the condition being signaled, this function returns with a SDL_MUTEX_TIMEDOUT value, otherwise it returns '0' meaning that the condition has been signaled. Thus function also unlocks the passed in mutex prior to waiting on the condition signal, and locks the mutex upon the condition being signaled, or the timeout.
Contents
Syntax
int SDL_CondWaitTimeout(SDL_cond* cond,
SDL_mutex* mutex,
Uint32 ms)
Function Parameters
cond |
The condition pointer whose signal will be waited on. |
mutex |
Mutex pointer used by user code to gate thread access. |
ms |
The maximum time to wait in milliseconds. Set to SDL_MUTEX_MAXWAIT for infinite wait. |
Return Value
Returns 0 if the condition variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not signaled in the allotted time, or a negative error code on failure; call SDL_GetError() for more information.
Code Examples
You can add your code example here
Remarks
mutex must be locked prior to calling this function. This function unlocks mutex, and it remains unlocked while this function waits for the condition signal, or the timeout to occur. In this way other threads within your program are free to make use of the shared resources while this function is in the waiting state.
When either the condition is signaled, or the timeout occurs, this function will lock mutex, prior to returning.
On some platforms this function is implemented by looping with a delay of 1 ms, and so should be avoided if possible.
