docs/html/thread.html

<HTML
><HEAD
><TITLE
>Multi-threaded Programming</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.64
"><LINK
REL="HOME"
TITLE="SDL Library Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="SDL Reference"
HREF="reference.html"><LINK
REL="PREVIOUS"
TITLE="SDL_CDtrack"
HREF="sdlcdtrack.html"><LINK
REL="NEXT"
TITLE="SDL_CreateThread"
HREF="sdlcreatethread.html"><META
NAME="KEYWORD"
CONTENT="threads"><META
NAME="KEYWORD"
CONTENT="function"></HEAD
><BODY
CLASS="CHAPTER"
BGCOLOR="#FFF8DC"
TEXT="#000000"
LINK="#0000ee"
VLINK="#551a8b"
ALINK="#ff0000"
><DIV
CLASS="NAVHEADER"
><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>SDL Library Documentation</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="sdlcdtrack.html"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="sdlcreatethread.html"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="CHAPTER"
><H1
><A
NAME="THREAD"
>Chapter 12. Multi-threaded Programming</A
></H1
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
><A
HREF="sdlcreatethread.html"
>SDL_CreateThread</A
> &#8212; Creates a new thread of execution that shares its parent's properties.</DT
><DT
><A
HREF="sdlthreadid.html"
>SDL_ThreadID</A
> &#8212; Get the 32-bit thread identifier for the current thread.</DT
><DT
><A
HREF="sdlgetthreadid.html"
>SDL_GetThreadID</A
> &#8212; Get the SDL thread ID of a SDL_Thread</DT
><DT
><A
HREF="sdlwaitthread.html"
>SDL_WaitThread</A
> &#8212; Wait for a thread to finish.</DT
><DT
><A
HREF="sdlkillthread.html"
>SDL_KillThread</A
> &#8212; Gracelessly terminates the thread.</DT
><DT
><A
HREF="sdlcreatemutex.html"
>SDL_CreateMutex</A
> &#8212; Create a mutex</DT
><DT
><A
HREF="sdldestroymutex.html"
>SDL_DestroyMutex</A
> &#8212; Destroy a mutex</DT
><DT
><A
HREF="sdlmutexp.html"
>SDL_mutexP</A
> &#8212; Lock a mutex</DT
><DT
><A
HREF="sdlmutexv.html"
>SDL_mutexV</A
> &#8212; Unlock a mutex</DT
><DT
><A
HREF="sdlcreatesemaphore.html"
>SDL_CreateSemaphore</A
> &#8212; Creates a new semaphore and assigns an initial value to it.</DT
><DT
><A
HREF="sdldestroysemaphore.html"
>SDL_DestroySemaphore</A
> &#8212; Destroys a semaphore that was created by <A
HREF="sdlcreatesemaphore.html"
>SDL_CreateSemaphore</A
>.</DT
><DT
><A
HREF="sdlsemwait.html"
>SDL_SemWait</A
> &#8212; Lock a semaphore and suspend the thread if the semaphore value is zero.</DT
><DT
><A
HREF="sdlsemtrywait.html"
>SDL_SemTryWait</A
> &#8212; Attempt to lock a semaphore but don't suspend the thread.</DT
><DT
><A
HREF="sdlsemwaittimeout.html"
>SDL_SemWaitTimeout</A
> &#8212; Lock a semaphore, but only wait up to a specified maximum time.</DT
><DT
><A
HREF="sdlsempost.html"
>SDL_SemPost</A
> &#8212; Unlock a semaphore.</DT
><DT
><A
HREF="sdlsemvalue.html"
>SDL_SemValue</A
> &#8212; Return the current value of a semaphore.</DT
><DT
><A
HREF="sdlcreatecond.html"
>SDL_CreateCond</A
> &#8212; Create a condition variable</DT
><DT
><A
HREF="sdldestroycond.html"
>SDL_DestroyCond</A
> &#8212; Destroy a condition variable</DT
><DT
><A
HREF="sdlcondsignal.html"
>SDL_CondSignal</A
> &#8212; Restart a thread wait on a condition variable</DT
><DT
><A
HREF="sdlcondbroadcast.html"
>SDL_CondBroadcast</A
> &#8212; Restart all threads waiting on a condition variable</DT
><DT
><A
HREF="sdlcondwait.html"
>SDL_CondWait</A
> &#8212; Wait on a condition variable</DT
><DT
><A
HREF="sdlcondwaittimeout.html"
>SDL_CondWaitTimeout</A
> &#8212; Wait on a condition variable, with timeout</DT
></DL
></DIV
><P
>SDL provides functions for creating threads, mutexes, semphores and condition variables.</P
><P
>In general, you must be very aware of concurrency and data integrity issues
when writing multi-threaded programs.  Some good guidelines include:
<P
></P
><UL
><LI
><P
>Don't call SDL video/event functions from separate threads</P
></LI
><LI
><P
>Don't use any library functions in separate threads</P
></LI
><LI
><P
>Don't perform any memory management in separate threads</P
></LI
><LI
><P
>Lock global variables which may be accessed by multiple threads</P
></LI
><LI
><P
>Never terminate threads, always set a flag and wait for them to quit</P
></LI
><LI
><P
>Think very carefully about all possible ways your code may interact</P
></LI
></UL
></P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>SDL's threading is not implemented on MacOS, due to that lack of preemptive thread support (eck!)</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="sdlcdtrack.html"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="sdlcreatethread.html"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>SDL_CDtrack</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="reference.html"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>SDL_CreateThread</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>