include/SDL_thread.h
changeset 7978 70ac84e49797
parent 7653 9a0e274b8aa7
child 7981 6d538bc1b395
     1.1 --- a/include/SDL_thread.h	Wed Nov 13 22:35:26 2013 -0500
     1.2 +++ b/include/SDL_thread.h	Thu Nov 14 00:52:39 2013 -0500
     1.3 @@ -165,14 +165,54 @@
     1.4  extern DECLSPEC int SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority);
     1.5  
     1.6  /**
     1.7 - *  Wait for a thread to finish.
     1.8 + *  Wait for a thread to finish. Threads that haven't been detached will
     1.9 + *  remain (as a "zombie") until this function cleans them up. Not doing so
    1.10 + *  is a resource leak.
    1.11 + *
    1.12 + *  Once a thread has been cleaned up through this function, the SDL_Thread
    1.13 + *  that references it becomes invalid and should not be referenced again.
    1.14 + *  As such, only one thread may call SDL_WaitThread() on another.
    1.15   *
    1.16   *  The return code for the thread function is placed in the area
    1.17   *  pointed to by \c status, if \c status is not NULL.
    1.18 + *
    1.19 + *  You may not wait on a thread that has been used in a call to
    1.20 + *  SDL_DetachThread(). Use either that function or this one, but not
    1.21 + *  both, or behavior is undefined.
    1.22 + *
    1.23 + *  It is safe to pass NULL to this function; it is a no-op.
    1.24   */
    1.25  extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread * thread, int *status);
    1.26  
    1.27  /**
    1.28 + *  A thread may be "detached" to signify that it should not remain until
    1.29 + *  another thread has called SDL_WaitThread() on it. Detaching a thread
    1.30 + *  is useful for long-running threads that nothing needs to synchronize
    1.31 + *  with or further manage. When a detached thread is done, it simply
    1.32 + *  goes away.
    1.33 + *
    1.34 + *  There is no way to recover the return code of a detached thread. If you
    1.35 + *  need this, don't detach the thread and instead use SDL_WaitThread().
    1.36 + *
    1.37 + *  Once a thread is detached, you should usually assume the SDL_Thread isn't
    1.38 + *  safe to reference again, as it will become invalid immediately upon
    1.39 + *  the detached thread's exit, instead of remaining until someone has called
    1.40 + *  SDL_WaitThread() to finally clean it up. As such, don't detach the same
    1.41 + *  thread more than once.
    1.42 + *
    1.43 + *  If a thread has already exited when passed to SDL_DetachThread(), it will
    1.44 + *  stop waiting for a call to SDL_WaitThread() and clean up immediately.
    1.45 + *  It is not safe to detach a thread that might be used with SDL_WaitThread().
    1.46 + *
    1.47 + *  You may not call SDL_WaitThread() on a thread that has been detached.
    1.48 + *  Use either that function or this one, but not both, or behavior is
    1.49 + *  undefined.
    1.50 + *
    1.51 + *  It is safe to pass NULL to this function; it is a no-op.
    1.52 + */
    1.53 +extern DECLSPEC void SDLCALL SDL_DetachThread(SDL_Thread * thread);
    1.54 +
    1.55 +/**
    1.56   *  \brief Create an identifier that is globally visible to all threads but refers to data that is thread-specific.
    1.57   *
    1.58   *  \return The newly created thread local storage identifier, or 0 on error