[sdl_omap.git] / docs / html / thread.html

<HTML
><HEAD
><TITLE
>Multi-threaded Programming</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><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
SUMMARY="Header navigation 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"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="sdlcreatethread.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="CHAPTER"
><H1
><A
NAME="THREAD"
></A
>Chapter 12. Multi-threaded Programming</H1
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
><A
HREF="sdlcreatethread.html"
>SDL_CreateThread</A
>&nbsp;--&nbsp;Creates a new thread of execution that shares its parent's properties.</DT
><DT
><A
HREF="sdlthreadid.html"
>SDL_ThreadID</A
>&nbsp;--&nbsp;Get the 32-bit thread identifier for the current thread.</DT
><DT
><A
HREF="sdlgetthreadid.html"
>SDL_GetThreadID</A
>&nbsp;--&nbsp;Get the SDL thread ID of a SDL_Thread</DT
><DT
><A
HREF="sdlwaitthread.html"
>SDL_WaitThread</A
>&nbsp;--&nbsp;Wait for a thread to finish.</DT
><DT
><A
HREF="sdlkillthread.html"
>SDL_KillThread</A
>&nbsp;--&nbsp;Gracelessly terminates the thread.</DT
><DT
><A
HREF="sdlcreatemutex.html"
>SDL_CreateMutex</A
>&nbsp;--&nbsp;Create a mutex</DT
><DT
><A
HREF="sdldestroymutex.html"
>SDL_DestroyMutex</A
>&nbsp;--&nbsp;Destroy a mutex</DT
><DT
><A
HREF="sdlmutexp.html"
>SDL_mutexP</A
>&nbsp;--&nbsp;Lock a mutex</DT
><DT
><A
HREF="sdlmutexv.html"
>SDL_mutexV</A
>&nbsp;--&nbsp;Unlock a mutex</DT
><DT
><A
HREF="sdlcreatesemaphore.html"
>SDL_CreateSemaphore</A
>&nbsp;--&nbsp;Creates a new semaphore and assigns an initial value to it.</DT
><DT
><A
HREF="sdldestroysemaphore.html"
>SDL_DestroySemaphore</A
>&nbsp;--&nbsp;Destroys a semaphore that was created by <A
HREF="sdlcreatesemaphore.html"
>SDL_CreateSemaphore</A
>.</DT
><DT
><A
HREF="sdlsemwait.html"
>SDL_SemWait</A
>&nbsp;--&nbsp;Lock a semaphore and suspend the thread if the semaphore value is zero.</DT
><DT
><A
HREF="sdlsemtrywait.html"
>SDL_SemTryWait</A
>&nbsp;--&nbsp;Attempt to lock a semaphore but don't suspend the thread.</DT
><DT
><A
HREF="sdlsemwaittimeout.html"
>SDL_SemWaitTimeout</A
>&nbsp;--&nbsp;Lock a semaphore, but only wait up to a specified maximum time.</DT
><DT
><A
HREF="sdlsempost.html"
>SDL_SemPost</A
>&nbsp;--&nbsp;Unlock a semaphore.</DT
><DT
><A
HREF="sdlsemvalue.html"
>SDL_SemValue</A
>&nbsp;--&nbsp;Return the current value of a semaphore.</DT
><DT
><A
HREF="sdlcreatecond.html"
>SDL_CreateCond</A
>&nbsp;--&nbsp;Create a condition variable</DT
><DT
><A
HREF="sdldestroycond.html"
>SDL_DestroyCond</A
>&nbsp;--&nbsp;Destroy a condition variable</DT
><DT
><A
HREF="sdlcondsignal.html"
>SDL_CondSignal</A
>&nbsp;--&nbsp;Restart a thread wait on a condition variable</DT
><DT
><A
HREF="sdlcondbroadcast.html"
>SDL_CondBroadcast</A
>&nbsp;--&nbsp;Restart all threads waiting on a condition variable</DT
><DT
><A
HREF="sdlcondwait.html"
>SDL_CondWait</A
>&nbsp;--&nbsp;Wait on a condition variable</DT
><DT
><A
HREF="sdlcondwaittimeout.html"
>SDL_CondWaitTimeout</A
>&nbsp;--&nbsp;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 (Mac OS X dos nt suffer from this problem)</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="sdlcdtrack.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="sdlcreatethread.html"
ACCESSKEY="N"
>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"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>SDL_CreateThread</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
Commit	Line	Data
e14743d1	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	>