docs/html/thread.html

   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 >&nbsp;--&nbsp;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 >&nbsp;--&nbsp;Get the 32-bit thread identifier for the current thread.</DT
  99 ><DT
 100 ><A
 101 HREF="sdlgetthreadid.html"
 102 >SDL_GetThreadID</A
 103 >&nbsp;--&nbsp;Get the SDL thread ID of a SDL_Thread</DT
 104 ><DT
 105 ><A
 106 HREF="sdlwaitthread.html"
 107 >SDL_WaitThread</A
 108 >&nbsp;--&nbsp;Wait for a thread to finish.</DT
 109 ><DT
 110 ><A
 111 HREF="sdlkillthread.html"
 112 >SDL_KillThread</A
 113 >&nbsp;--&nbsp;Gracelessly terminates the thread.</DT
 114 ><DT
 115 ><A
 116 HREF="sdlcreatemutex.html"
 117 >SDL_CreateMutex</A
 118 >&nbsp;--&nbsp;Create a mutex</DT
 119 ><DT
 120 ><A
 121 HREF="sdldestroymutex.html"
 122 >SDL_DestroyMutex</A
 123 >&nbsp;--&nbsp;Destroy a mutex</DT
 124 ><DT
 125 ><A
 126 HREF="sdlmutexp.html"
 127 >SDL_mutexP</A
 128 >&nbsp;--&nbsp;Lock a mutex</DT
 129 ><DT
 130 ><A
 131 HREF="sdlmutexv.html"
 132 >SDL_mutexV</A
 133 >&nbsp;--&nbsp;Unlock a mutex</DT
 134 ><DT
 135 ><A
 136 HREF="sdlcreatesemaphore.html"
 137 >SDL_CreateSemaphore</A
 138 >&nbsp;--&nbsp;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 >&nbsp;--&nbsp;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 >&nbsp;--&nbsp;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 >&nbsp;--&nbsp;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 >&nbsp;--&nbsp;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 >&nbsp;--&nbsp;Unlock a semaphore.</DT
 167 ><DT
 168 ><A
 169 HREF="sdlsemvalue.html"
 170 >SDL_SemValue</A
 171 >&nbsp;--&nbsp;Return the current value of a semaphore.</DT
 172 ><DT
 173 ><A
 174 HREF="sdlcreatecond.html"
 175 >SDL_CreateCond</A
 176 >&nbsp;--&nbsp;Create a condition variable</DT
 177 ><DT
 178 ><A
 179 HREF="sdldestroycond.html"
 180 >SDL_DestroyCond</A
 181 >&nbsp;--&nbsp;Destroy a condition variable</DT
 182 ><DT
 183 ><A
 184 HREF="sdlcondsignal.html"
 185 >SDL_CondSignal</A
 186 >&nbsp;--&nbsp;Restart a thread wait on a condition variable</DT
 187 ><DT
 188 ><A
 189 HREF="sdlcondbroadcast.html"
 190 >SDL_CondBroadcast</A
 191 >&nbsp;--&nbsp;Restart all threads waiting on a condition variable</DT
 192 ><DT
 193 ><A
 194 HREF="sdlcondwait.html"
 195 >SDL_CondWait</A
 196 >&nbsp;--&nbsp;Wait on a condition variable</DT
 197 ><DT
 198 ><A
 199 HREF="sdlcondwaittimeout.html"
 200 >SDL_CondWaitTimeout</A
 201 >&nbsp;--&nbsp;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 >