| 1 | <HTML |
| 2 | ><HEAD |
| 3 | ><TITLE |
| 4 | >Multi-threaded Programming</TITLE |
| 5 | ><META |
| 6 | NAME="GENERATOR" |
| 7 | CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+ |
| 8 | "><LINK |
| 9 | REL="HOME" |
| 10 | TITLE="SDL Library Documentation" |
| 11 | HREF="index.html"><LINK |
| 12 | REL="UP" |
| 13 | TITLE="SDL Reference" |
| 14 | HREF="reference.html"><LINK |
| 15 | REL="PREVIOUS" |
| 16 | TITLE="SDL_CDtrack" |
| 17 | HREF="sdlcdtrack.html"><LINK |
| 18 | REL="NEXT" |
| 19 | TITLE="SDL_CreateThread" |
| 20 | HREF="sdlcreatethread.html"><META |
| 21 | NAME="KEYWORD" |
| 22 | CONTENT="threads"><META |
| 23 | NAME="KEYWORD" |
| 24 | CONTENT="function"></HEAD |
| 25 | ><BODY |
| 26 | CLASS="CHAPTER" |
| 27 | BGCOLOR="#FFF8DC" |
| 28 | TEXT="#000000" |
| 29 | LINK="#0000ee" |
| 30 | VLINK="#551a8b" |
| 31 | ALINK="#ff0000" |
| 32 | ><DIV |
| 33 | CLASS="NAVHEADER" |
| 34 | ><TABLE |
| 35 | SUMMARY="Header navigation table" |
| 36 | WIDTH="100%" |
| 37 | BORDER="0" |
| 38 | CELLPADDING="0" |
| 39 | CELLSPACING="0" |
| 40 | ><TR |
| 41 | ><TH |
| 42 | COLSPAN="3" |
| 43 | ALIGN="center" |
| 44 | >SDL Library Documentation</TH |
| 45 | ></TR |
| 46 | ><TR |
| 47 | ><TD |
| 48 | WIDTH="10%" |
| 49 | ALIGN="left" |
| 50 | VALIGN="bottom" |
| 51 | ><A |
| 52 | HREF="sdlcdtrack.html" |
| 53 | ACCESSKEY="P" |
| 54 | >Prev</A |
| 55 | ></TD |
| 56 | ><TD |
| 57 | WIDTH="80%" |
| 58 | ALIGN="center" |
| 59 | VALIGN="bottom" |
| 60 | ></TD |
| 61 | ><TD |
| 62 | WIDTH="10%" |
| 63 | ALIGN="right" |
| 64 | VALIGN="bottom" |
| 65 | ><A |
| 66 | HREF="sdlcreatethread.html" |
| 67 | ACCESSKEY="N" |
| 68 | >Next</A |
| 69 | ></TD |
| 70 | ></TR |
| 71 | ></TABLE |
| 72 | ><HR |
| 73 | ALIGN="LEFT" |
| 74 | WIDTH="100%"></DIV |
| 75 | ><DIV |
| 76 | CLASS="CHAPTER" |
| 77 | ><H1 |
| 78 | ><A |
| 79 | NAME="THREAD" |
| 80 | ></A |
| 81 | >Chapter 12. Multi-threaded Programming</H1 |
| 82 | ><DIV |
| 83 | CLASS="TOC" |
| 84 | ><DL |
| 85 | ><DT |
| 86 | ><B |
| 87 | >Table of Contents</B |
| 88 | ></DT |
| 89 | ><DT |
| 90 | ><A |
| 91 | HREF="sdlcreatethread.html" |
| 92 | >SDL_CreateThread</A |
| 93 | > -- Creates a new thread of execution that shares its parent's properties.</DT |
| 94 | ><DT |
| 95 | ><A |
| 96 | HREF="sdlthreadid.html" |
| 97 | >SDL_ThreadID</A |
| 98 | > -- Get the 32-bit thread identifier for the current thread.</DT |
| 99 | ><DT |
| 100 | ><A |
| 101 | HREF="sdlgetthreadid.html" |
| 102 | >SDL_GetThreadID</A |
| 103 | > -- Get the SDL thread ID of a SDL_Thread</DT |
| 104 | ><DT |
| 105 | ><A |
| 106 | HREF="sdlwaitthread.html" |
| 107 | >SDL_WaitThread</A |
| 108 | > -- Wait for a thread to finish.</DT |
| 109 | ><DT |
| 110 | ><A |
| 111 | HREF="sdlkillthread.html" |
| 112 | >SDL_KillThread</A |
| 113 | > -- Gracelessly terminates the thread.</DT |
| 114 | ><DT |
| 115 | ><A |
| 116 | HREF="sdlcreatemutex.html" |
| 117 | >SDL_CreateMutex</A |
| 118 | > -- Create a mutex</DT |
| 119 | ><DT |
| 120 | ><A |
| 121 | HREF="sdldestroymutex.html" |
| 122 | >SDL_DestroyMutex</A |
| 123 | > -- Destroy a mutex</DT |
| 124 | ><DT |
| 125 | ><A |
| 126 | HREF="sdlmutexp.html" |
| 127 | >SDL_mutexP</A |
| 128 | > -- Lock a mutex</DT |
| 129 | ><DT |
| 130 | ><A |
| 131 | HREF="sdlmutexv.html" |
| 132 | >SDL_mutexV</A |
| 133 | > -- Unlock a mutex</DT |
| 134 | ><DT |
| 135 | ><A |
| 136 | HREF="sdlcreatesemaphore.html" |
| 137 | >SDL_CreateSemaphore</A |
| 138 | > -- Creates a new semaphore and assigns an initial value to it.</DT |
| 139 | ><DT |
| 140 | ><A |
| 141 | HREF="sdldestroysemaphore.html" |
| 142 | >SDL_DestroySemaphore</A |
| 143 | > -- Destroys a semaphore that was created by <A |
| 144 | HREF="sdlcreatesemaphore.html" |
| 145 | >SDL_CreateSemaphore</A |
| 146 | >.</DT |
| 147 | ><DT |
| 148 | ><A |
| 149 | HREF="sdlsemwait.html" |
| 150 | >SDL_SemWait</A |
| 151 | > -- Lock a semaphore and suspend the thread if the semaphore value is zero.</DT |
| 152 | ><DT |
| 153 | ><A |
| 154 | HREF="sdlsemtrywait.html" |
| 155 | >SDL_SemTryWait</A |
| 156 | > -- Attempt to lock a semaphore but don't suspend the thread.</DT |
| 157 | ><DT |
| 158 | ><A |
| 159 | HREF="sdlsemwaittimeout.html" |
| 160 | >SDL_SemWaitTimeout</A |
| 161 | > -- Lock a semaphore, but only wait up to a specified maximum time.</DT |
| 162 | ><DT |
| 163 | ><A |
| 164 | HREF="sdlsempost.html" |
| 165 | >SDL_SemPost</A |
| 166 | > -- Unlock a semaphore.</DT |
| 167 | ><DT |
| 168 | ><A |
| 169 | HREF="sdlsemvalue.html" |
| 170 | >SDL_SemValue</A |
| 171 | > -- Return the current value of a semaphore.</DT |
| 172 | ><DT |
| 173 | ><A |
| 174 | HREF="sdlcreatecond.html" |
| 175 | >SDL_CreateCond</A |
| 176 | > -- Create a condition variable</DT |
| 177 | ><DT |
| 178 | ><A |
| 179 | HREF="sdldestroycond.html" |
| 180 | >SDL_DestroyCond</A |
| 181 | > -- Destroy a condition variable</DT |
| 182 | ><DT |
| 183 | ><A |
| 184 | HREF="sdlcondsignal.html" |
| 185 | >SDL_CondSignal</A |
| 186 | > -- Restart a thread wait on a condition variable</DT |
| 187 | ><DT |
| 188 | ><A |
| 189 | HREF="sdlcondbroadcast.html" |
| 190 | >SDL_CondBroadcast</A |
| 191 | > -- Restart all threads waiting on a condition variable</DT |
| 192 | ><DT |
| 193 | ><A |
| 194 | HREF="sdlcondwait.html" |
| 195 | >SDL_CondWait</A |
| 196 | > -- Wait on a condition variable</DT |
| 197 | ><DT |
| 198 | ><A |
| 199 | HREF="sdlcondwaittimeout.html" |
| 200 | >SDL_CondWaitTimeout</A |
| 201 | > -- Wait on a condition variable, with timeout</DT |
| 202 | ></DL |
| 203 | ></DIV |
| 204 | ><P |
| 205 | >SDL provides functions for creating threads, mutexes, semphores and condition variables.</P |
| 206 | ><P |
| 207 | >In general, you must be very aware of concurrency and data integrity issues |
| 208 | when writing multi-threaded programs. Some good guidelines include: |
| 209 | <P |
| 210 | ></P |
| 211 | ><UL |
| 212 | ><LI |
| 213 | ><P |
| 214 | >Don't call SDL video/event functions from separate threads</P |
| 215 | ></LI |
| 216 | ><LI |
| 217 | ><P |
| 218 | >Don't use any library functions in separate threads</P |
| 219 | ></LI |
| 220 | ><LI |
| 221 | ><P |
| 222 | >Don't perform any memory management in separate threads</P |
| 223 | ></LI |
| 224 | ><LI |
| 225 | ><P |
| 226 | >Lock global variables which may be accessed by multiple threads</P |
| 227 | ></LI |
| 228 | ><LI |
| 229 | ><P |
| 230 | >Never terminate threads, always set a flag and wait for them to quit</P |
| 231 | ></LI |
| 232 | ><LI |
| 233 | ><P |
| 234 | >Think very carefully about all possible ways your code may interact</P |
| 235 | ></LI |
| 236 | ></UL |
| 237 | ></P |
| 238 | ><DIV |
| 239 | CLASS="NOTE" |
| 240 | ><BLOCKQUOTE |
| 241 | CLASS="NOTE" |
| 242 | ><P |
| 243 | ><B |
| 244 | >Note: </B |
| 245 | >SDL's threading is not implemented on MacOS, due to that lack of preemptive thread support (Mac OS X dos nt suffer from this problem)</P |
| 246 | ></BLOCKQUOTE |
| 247 | ></DIV |
| 248 | ></DIV |
| 249 | ><DIV |
| 250 | CLASS="NAVFOOTER" |
| 251 | ><HR |
| 252 | ALIGN="LEFT" |
| 253 | WIDTH="100%"><TABLE |
| 254 | SUMMARY="Footer navigation table" |
| 255 | WIDTH="100%" |
| 256 | BORDER="0" |
| 257 | CELLPADDING="0" |
| 258 | CELLSPACING="0" |
| 259 | ><TR |
| 260 | ><TD |
| 261 | WIDTH="33%" |
| 262 | ALIGN="left" |
| 263 | VALIGN="top" |
| 264 | ><A |
| 265 | HREF="sdlcdtrack.html" |
| 266 | ACCESSKEY="P" |
| 267 | >Prev</A |
| 268 | ></TD |
| 269 | ><TD |
| 270 | WIDTH="34%" |
| 271 | ALIGN="center" |
| 272 | VALIGN="top" |
| 273 | ><A |
| 274 | HREF="index.html" |
| 275 | ACCESSKEY="H" |
| 276 | >Home</A |
| 277 | ></TD |
| 278 | ><TD |
| 279 | WIDTH="33%" |
| 280 | ALIGN="right" |
| 281 | VALIGN="top" |
| 282 | ><A |
| 283 | HREF="sdlcreatethread.html" |
| 284 | ACCESSKEY="N" |
| 285 | >Next</A |
| 286 | ></TD |
| 287 | ></TR |
| 288 | ><TR |
| 289 | ><TD |
| 290 | WIDTH="33%" |
| 291 | ALIGN="left" |
| 292 | VALIGN="top" |
| 293 | >SDL_CDtrack</TD |
| 294 | ><TD |
| 295 | WIDTH="34%" |
| 296 | ALIGN="center" |
| 297 | VALIGN="top" |
| 298 | ><A |
| 299 | HREF="reference.html" |
| 300 | ACCESSKEY="U" |
| 301 | >Up</A |
| 302 | ></TD |
| 303 | ><TD |
| 304 | WIDTH="33%" |
| 305 | ALIGN="right" |
| 306 | VALIGN="top" |
| 307 | >SDL_CreateThread</TD |
| 308 | ></TR |
| 309 | ></TABLE |
| 310 | ></DIV |
| 311 | ></BODY |
| 312 | ></HTML |
| 313 | > |