Mercurial > sdl-ios-xcode

comparison include/SDL_thread.h @ 3407:d3baf5ac4e37

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Partial fix for bug #859 Header file update from Ken for improved doxygen output
author Sam Lantinga <slouken@libsdl.org>
date Mon, 19 Oct 2009 13:31:58 +0000
parents a67a961e2171
children 0d1b16ee0bca
comparison
equal deleted inserted replaced
3406:8ae607392409 3407:d3baf5ac4e37
22 22
23 #ifndef _SDL_thread_h 23 #ifndef _SDL_thread_h
24 #define _SDL_thread_h 24 #define _SDL_thread_h
25 25
26 /** 26 /**
27 * \file SDL_thread.h 27 * \file SDL_thread.h
28 * 28 *
29 * Header for the SDL thread management routines 29 * Header for the SDL thread management routines.
30 */ 30 */
31 31
32 #include "SDL_stdinc.h" 32 #include "SDL_stdinc.h"
33 #include "SDL_error.h" 33 #include "SDL_error.h"
34 34
45 45
46 /* The SDL thread structure, defined in SDL_thread.c */ 46 /* The SDL thread structure, defined in SDL_thread.c */
47 struct SDL_Thread; 47 struct SDL_Thread;
48 typedef struct SDL_Thread SDL_Thread; 48 typedef struct SDL_Thread SDL_Thread;
49 49
50 /* Create a thread */
51 #if defined(__WIN32__) && !defined(HAVE_LIBC) 50 #if defined(__WIN32__) && !defined(HAVE_LIBC)
52 /* 51 /**
53 We compile SDL into a DLL. This means, that it's the DLL which 52 * \file SDL_thread.h
54 creates a new thread for the calling process with the SDL_CreateThread() 53 *
55 API. There is a problem with this, that only the RTL of the SDL.DLL will 54 * We compile SDL into a DLL. This means, that it's the DLL which
56 be initialized for those threads, and not the RTL of the calling application! 55 * creates a new thread for the calling process with the SDL_CreateThread()
57 To solve this, we make a little hack here. 56 * API. There is a problem with this, that only the RTL of the SDL.DLL will
58 We'll always use the caller's _beginthread() and _endthread() APIs to 57 * be initialized for those threads, and not the RTL of the calling
59 start a new thread. This way, if it's the SDL.DLL which uses this API, 58 * application!
60 then the RTL of SDL.DLL will be used to create the new thread, and if it's 59 *
61 the application, then the RTL of the application will be used. 60 * To solve this, we make a little hack here.
62 So, in short: 61 *
63 Always use the _beginthread() and _endthread() of the calling runtime library! 62 * We'll always use the caller's _beginthread() and _endthread() APIs to
64 */ 63 * start a new thread. This way, if it's the SDL.DLL which uses this API,
64 * then the RTL of SDL.DLL will be used to create the new thread, and if it's
65 * the application, then the RTL of the application will be used.
66 *
67 * So, in short:
68 * Always use the _beginthread() and _endthread() of the calling runtime
69 * library!
70 */
65 #define SDL_PASSED_BEGINTHREAD_ENDTHREAD 71 #define SDL_PASSED_BEGINTHREAD_ENDTHREAD
66 #ifndef _WIN32_WCE 72 #ifndef _WIN32_WCE
67 #include <process.h> /* This has _beginthread() and _endthread() defined! */ 73 #include <process.h> /* This has _beginthread() and _endthread() defined! */
68 #endif 74 #endif
69 75
85 void *arg, unsigned, 91 void *arg, unsigned,
86 unsigned *threadID); 92 unsigned *threadID);
87 typedef void (__cdecl * pfnSDL_CurrentEndThread) (unsigned code); 93 typedef void (__cdecl * pfnSDL_CurrentEndThread) (unsigned code);
88 #endif 94 #endif
89 95
96 /**
97 * Create a thread.
98 */
90 extern DECLSPEC SDL_Thread *SDLCALL 99 extern DECLSPEC SDL_Thread *SDLCALL
91 SDL_CreateThread(int (SDLCALL * f) (void *), void *data, 100 SDL_CreateThread(int (SDLCALL * f) (void *), void *data,
92 pfnSDL_CurrentBeginThread pfnBeginThread, 101 pfnSDL_CurrentBeginThread pfnBeginThread,
93 pfnSDL_CurrentEndThread pfnEndThread); 102 pfnSDL_CurrentEndThread pfnEndThread);
94 103
95 #if defined(_WIN32_WCE) 104 #if defined(_WIN32_WCE)
105
106 /**
107 * Create a thread.
108 */
96 #define SDL_CreateThread(fn, data) SDL_CreateThread(fn, data, NULL, NULL) 109 #define SDL_CreateThread(fn, data) SDL_CreateThread(fn, data, NULL, NULL)
110
97 #else 111 #else
112
113 /**
114 * Create a thread.
115 */
98 #define SDL_CreateThread(fn, data) SDL_CreateThread(fn, data, _beginthreadex, _endthreadex) 116 #define SDL_CreateThread(fn, data) SDL_CreateThread(fn, data, _beginthreadex, _endthreadex)
117
99 #endif 118 #endif
100 #else 119 #else
120
121 /**
122 * Create a thread.
123 */
101 extern DECLSPEC SDL_Thread *SDLCALL 124 extern DECLSPEC SDL_Thread *SDLCALL
102 SDL_CreateThread(int (SDLCALL * fn) (void *), void *data); 125 SDL_CreateThread(int (SDLCALL * fn) (void *), void *data);
126
103 #endif 127 #endif
104 128
105 /* Get the 32-bit thread identifier for the current thread */ 129 /**
130 * Get the 32-bit thread identifier for the current thread.
131 */
106 extern DECLSPEC Uint32 SDLCALL SDL_ThreadID(void); 132 extern DECLSPEC Uint32 SDLCALL SDL_ThreadID(void);
107 133
108 /* Get the 32-bit thread identifier for the specified thread, 134 /**
109 equivalent to SDL_ThreadID() if the specified thread is NULL. 135 * Get the 32-bit thread identifier for the specified thread.
136 *
137 * Equivalent to SDL_ThreadID() if the specified thread is NULL.
110 */ 138 */
111 extern DECLSPEC Uint32 SDLCALL SDL_GetThreadID(SDL_Thread * thread); 139 extern DECLSPEC Uint32 SDLCALL SDL_GetThreadID(SDL_Thread * thread);
112 140
113 /* Wait for a thread to finish. 141 /**
114 The return code for the thread function is placed in the area 142 * Wait for a thread to finish.
115 pointed to by 'status', if 'status' is not NULL. 143 *
144 * The return code for the thread function is placed in the area
145 * pointed to by \c status, if \c status is not NULL.
116 */ 146 */
117 extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread * thread, int *status); 147 extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread * thread, int *status);
118 148
119 /* This function is here for binary compatibility with legacy apps, but 149 /**
120 in SDL 1.3 and later, it's a no-op. You cannot forcibly kill a thread 150 * \deprecated This function is here for binary compatibility with legacy apps,
121 in a safe manner on many platforms. You should instead find a way to 151 * but in SDL 1.3 and later, it's a no-op.
122 alert your thread that it is time to terminate, and then have it gracefully 152 *
123 exit on its own. Do not ever call this function! 153 * You cannot forcibly kill a thread in a safe manner on many platforms. You
154 * should instead find a way to alert your thread that it is time to terminate,
155 * and then have it gracefully exit on its own. Do not ever call this function!
124 */ 156 */
125 extern DECLSPEC void SDLCALL SDL_KillThread(SDL_Thread * thread); 157 extern DECLSPEC void SDLCALL SDL_KillThread(SDL_Thread * thread);
126 158
127 159
128 /* Ends C function definitions when using C++ */ 160 /* Ends C function definitions when using C++ */