include/SDL_mutex.h
changeset 5110 0846f18eb625
parent 4469 f67139f6d87f
child 5262 b530ef003506
     1.1 --- a/include/SDL_mutex.h	Thu Jan 27 10:07:14 2011 -0800
     1.2 +++ b/include/SDL_mutex.h	Thu Jan 27 10:40:17 2011 -0800
     1.3 @@ -164,6 +164,31 @@
     1.4  
     1.5  /**
     1.6   *  Create a condition variable.
     1.7 + *
     1.8 + *  Typical use of condition variables:
     1.9 + *
    1.10 + *  Thread A:
    1.11 + *    SDL_LockMutex(lock);
    1.12 + *    while ( ! condition ) {
    1.13 + *        SDL_CondWait(cond, lock);
    1.14 + *    }
    1.15 + *    SDL_UnlockMutex(lock);
    1.16 + *
    1.17 + *  Thread B:
    1.18 + *    SDL_LockMutex(lock);
    1.19 + *    ...
    1.20 + *    condition = true;
    1.21 + *    ...
    1.22 + *    SDL_CondSignal(cond);
    1.23 + *    SDL_UnlockMutex(lock);
    1.24 + *
    1.25 + *  There is some discussion whether to signal the condition variable
    1.26 + *  with the mutex locked or not.  There is some potential performance
    1.27 + *  benefit to unlocking first on some platforms, but there are some
    1.28 + *  potential race conditions depending on how your code is structured.
    1.29 + *
    1.30 + *  In general it's safer to signal the condition variable while the
    1.31 + *  mutex is locked.
    1.32   */
    1.33  extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
    1.34  
    1.35 @@ -181,6 +206,7 @@
    1.36  
    1.37  /**
    1.38   *  Restart all threads that are waiting on the condition variable.
    1.39 + *
    1.40   *  \return 0 or -1 on error.
    1.41   */
    1.42  extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond);