include/SDL_thread.h
changeset 3407 d3baf5ac4e37
parent 3269 a67a961e2171
child 3578 0d1b16ee0bca
     1.1 --- a/include/SDL_thread.h	Sun Oct 18 23:21:15 2009 +0000
     1.2 +++ b/include/SDL_thread.h	Mon Oct 19 13:31:58 2009 +0000
     1.3 @@ -24,9 +24,9 @@
     1.4  #define _SDL_thread_h
     1.5  
     1.6  /**
     1.7 - * \file SDL_thread.h
     1.8 - *
     1.9 - * Header for the SDL thread management routines 
    1.10 + *  \file SDL_thread.h
    1.11 + *  
    1.12 + *  Header for the SDL thread management routines.
    1.13   */
    1.14  
    1.15  #include "SDL_stdinc.h"
    1.16 @@ -47,21 +47,27 @@
    1.17  struct SDL_Thread;
    1.18  typedef struct SDL_Thread SDL_Thread;
    1.19  
    1.20 -/* Create a thread */
    1.21  #if defined(__WIN32__) && !defined(HAVE_LIBC)
    1.22 -/*
    1.23 -   We compile SDL into a DLL. This means, that it's the DLL which
    1.24 -   creates a new thread for the calling process with the SDL_CreateThread()
    1.25 -   API. There is a problem with this, that only the RTL of the SDL.DLL will
    1.26 -   be initialized for those threads, and not the RTL of the calling application!
    1.27 -   To solve this, we make a little hack here.
    1.28 -   We'll always use the caller's _beginthread() and _endthread() APIs to
    1.29 -   start a new thread. This way, if it's the SDL.DLL which uses this API,
    1.30 -   then the RTL of SDL.DLL will be used to create the new thread, and if it's
    1.31 -   the application, then the RTL of the application will be used.
    1.32 -   So, in short:
    1.33 -   Always use the _beginthread() and _endthread() of the calling runtime library!
    1.34 -*/
    1.35 +/**
    1.36 + *  \file SDL_thread.h
    1.37 + *  
    1.38 + *  We compile SDL into a DLL. This means, that it's the DLL which
    1.39 + *  creates a new thread for the calling process with the SDL_CreateThread()
    1.40 + *  API. There is a problem with this, that only the RTL of the SDL.DLL will
    1.41 + *  be initialized for those threads, and not the RTL of the calling 
    1.42 + *  application!
    1.43 + *  
    1.44 + *  To solve this, we make a little hack here.
    1.45 + *  
    1.46 + *  We'll always use the caller's _beginthread() and _endthread() APIs to
    1.47 + *  start a new thread. This way, if it's the SDL.DLL which uses this API,
    1.48 + *  then the RTL of SDL.DLL will be used to create the new thread, and if it's
    1.49 + *  the application, then the RTL of the application will be used.
    1.50 + *  
    1.51 + *  So, in short:
    1.52 + *  Always use the _beginthread() and _endthread() of the calling runtime 
    1.53 + *  library!
    1.54 + */
    1.55  #define SDL_PASSED_BEGINTHREAD_ENDTHREAD
    1.56  #ifndef _WIN32_WCE
    1.57  #include <process.h>            /* This has _beginthread() and _endthread() defined! */
    1.58 @@ -87,40 +93,66 @@
    1.59  typedef void (__cdecl * pfnSDL_CurrentEndThread) (unsigned code);
    1.60  #endif
    1.61  
    1.62 +/**
    1.63 + *  Create a thread.
    1.64 + */
    1.65  extern DECLSPEC SDL_Thread *SDLCALL
    1.66  SDL_CreateThread(int (SDLCALL * f) (void *), void *data,
    1.67                   pfnSDL_CurrentBeginThread pfnBeginThread,
    1.68                   pfnSDL_CurrentEndThread pfnEndThread);
    1.69  
    1.70  #if defined(_WIN32_WCE)
    1.71 +
    1.72 +/**
    1.73 + *  Create a thread.
    1.74 + */
    1.75  #define SDL_CreateThread(fn, data) SDL_CreateThread(fn, data, NULL, NULL)
    1.76 +
    1.77  #else
    1.78 +
    1.79 +/**
    1.80 + *  Create a thread.
    1.81 + */
    1.82  #define SDL_CreateThread(fn, data) SDL_CreateThread(fn, data, _beginthreadex, _endthreadex)
    1.83 +
    1.84  #endif
    1.85  #else
    1.86 +
    1.87 +/**
    1.88 + *  Create a thread.
    1.89 + */
    1.90  extern DECLSPEC SDL_Thread *SDLCALL
    1.91  SDL_CreateThread(int (SDLCALL * fn) (void *), void *data);
    1.92 +
    1.93  #endif
    1.94  
    1.95 -/* Get the 32-bit thread identifier for the current thread */
    1.96 +/**
    1.97 + *  Get the 32-bit thread identifier for the current thread.
    1.98 + */
    1.99  extern DECLSPEC Uint32 SDLCALL SDL_ThreadID(void);
   1.100  
   1.101 -/* Get the 32-bit thread identifier for the specified thread,
   1.102 -   equivalent to SDL_ThreadID() if the specified thread is NULL.
   1.103 +/**
   1.104 + *  Get the 32-bit thread identifier for the specified thread.
   1.105 + *  
   1.106 + *  Equivalent to SDL_ThreadID() if the specified thread is NULL.
   1.107   */
   1.108  extern DECLSPEC Uint32 SDLCALL SDL_GetThreadID(SDL_Thread * thread);
   1.109  
   1.110 -/* Wait for a thread to finish.
   1.111 -   The return code for the thread function is placed in the area
   1.112 -   pointed to by 'status', if 'status' is not NULL.
   1.113 +/**
   1.114 + *  Wait for a thread to finish.
   1.115 + *  
   1.116 + *  The return code for the thread function is placed in the area
   1.117 + *  pointed to by \c status, if \c status is not NULL.
   1.118   */
   1.119  extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread * thread, int *status);
   1.120  
   1.121 -/* This function is here for binary compatibility with legacy apps, but
   1.122 -   in SDL 1.3 and later, it's a no-op. You cannot forcibly kill a thread
   1.123 -   in a safe manner on many platforms. You should instead find a way to
   1.124 -   alert your thread that it is time to terminate, and then have it gracefully
   1.125 -   exit on its own. Do not ever call this function!
   1.126 +/**
   1.127 + *  \deprecated This function is here for binary compatibility with legacy apps,
   1.128 + *              but in SDL 1.3 and later, it's a no-op.
   1.129 + *  
   1.130 + *  You cannot forcibly kill a thread in a safe manner on many platforms. You 
   1.131 + *  should instead find a way to alert your thread that it is time to terminate,
   1.132 + *  and then have it gracefully exit on its own. Do not ever call this function!
   1.133   */
   1.134  extern DECLSPEC void SDLCALL SDL_KillThread(SDL_Thread * thread);
   1.135