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

<HTML
><HEAD
><TITLE
>SDL_SemWaitTimeout</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="Multi-threaded Programming"
HREF="thread.html"><LINK
REL="PREVIOUS"
TITLE="SDL_SemTryWait"
HREF="sdlsemtrywait.html"><LINK
REL="NEXT"
TITLE="SDL_SemPost"
HREF="sdlsempost.html"></HEAD
><BODY
CLASS="REFENTRY"
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="sdlsemtrywait.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="sdlsempost.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="SDLSEMWAITTIMEOUT"
></A
>SDL_SemWaitTimeout</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN8120"
></A
><H2
>Name</H2
>SDL_SemWaitTimeout&nbsp;--&nbsp;Lock a semaphore, but only wait up to a specified maximum time.</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN8123"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN8124"
></A
><P
></P
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include "SDL.h"
#include "SDL_thread.h"</PRE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int <B
CLASS="FSFUNC"
>SDL_SemWaitTimeout</B
></CODE
>(SDL_sem *sem, Uint32 timeout);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8130"
></A
><H2
>Description</H2
><P
><TT
CLASS="FUNCTION"
>SDL_SemWaitTimeout()</TT
> is a varient of
<A
HREF="sdlsemwait.html"
>SDL_SemWait</A
>
with a maximum timeout value.
If the value of the semaphore pointed to by <TT
CLASS="PARAMETER"
><I
>sem</I
></TT
> is
positive (greater than zero) it will atomically decrement the semaphore value
and return 0, otherwise it will wait up to <TT
CLASS="PARAMETER"
><I
>timeout</I
></TT
>
milliseconds trying to lock the semaphore. This function is to be avoided if
possible since on some platforms it is implemented by polling the semaphore
every millisecond in a busy loop.</P
><P
>After <TT
CLASS="FUNCTION"
>SDL_SemWaitTimeout()</TT
> is successful, the semaphore
can be released and its count atomically incremented by a successful call to
<A
HREF="sdlsempost.html"
>SDL_SemPost</A
>.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8140"
></A
><H2
>Return Value</H2
><P
>Returns <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> if the semaphore was successfully locked or
either <SPAN
CLASS="RETURNVALUE"
>SDL_MUTEX_TIMEDOUT</SPAN
> or <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
>
if the timeout period was exceeded or there was an error, respectivly.</P
><P
>If the semaphore was not successfully locked, the semaphore will be unchanged.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8147"
></A
><H2
>Examples</H2
><P
><PRE
CLASS="PROGRAMLISTING"
>res = SDL_SemWaitTimeout(my_sem, WAIT_TIMEOUT_MILLISEC);

if (res == SDL_MUTEX_TIMEDOUT) {
        return TRY_AGAIN;
}
if (res == -1) {
        return WAIT_ERROR;
}

...

SDL_SemPost(my_sem);</PRE
></P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN8151"
></A
><H2
>See Also</H2
><P
><A
HREF="sdlcreatesemaphore.html"
><TT
CLASS="FUNCTION"
>SDL_CreateSemaphore</TT
></A
>,
<A
HREF="sdldestroysemaphore.html"
><TT
CLASS="FUNCTION"
>SDL_DestroySemaphore</TT
></A
>,
<A
HREF="sdlsemwait.html"
><TT
CLASS="FUNCTION"
>SDL_SemWait</TT
></A
>,
<A
HREF="sdlsemtrywait.html"
><TT
CLASS="FUNCTION"
>SDL_SemTryWait</TT
></A
>,
<A
HREF="sdlsempost.html"
><TT
CLASS="FUNCTION"
>SDL_SemPost</TT
></A
>,
<A
HREF="sdlsemvalue.html"
><TT
CLASS="FUNCTION"
>SDL_SemValue</TT
></A
></P
></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="sdlsemtrywait.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="sdlsempost.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>SDL_SemTryWait</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="thread.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>SDL_SemPost</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
Commit	Line	Data
e14743d1	1	<HTML
	2	><HEAD
	3	><TITLE
	4	>SDL_SemWaitTimeout</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="Multi-threaded Programming"
	14	HREF="thread.html"><LINK
	15	REL="PREVIOUS"
	16	TITLE="SDL_SemTryWait"
	17	HREF="sdlsemtrywait.html"><LINK
	18	REL="NEXT"
	19	TITLE="SDL_SemPost"
	20	HREF="sdlsempost.html"></HEAD
	21	><BODY
	22	CLASS="REFENTRY"
	23	BGCOLOR="#FFF8DC"
	24	TEXT="#000000"
	25	LINK="#0000ee"
	26	VLINK="#551a8b"
	27	ALINK="#ff0000"
	28	><DIV
	29	CLASS="NAVHEADER"
	30	><TABLE
	31	SUMMARY="Header navigation table"
	32	WIDTH="100%"
	33	BORDER="0"
	34	CELLPADDING="0"
	35	CELLSPACING="0"
	36	><TR
	37	><TH
	38	COLSPAN="3"
	39	ALIGN="center"
	40	>SDL Library Documentation</TH
	41	></TR
	42	><TR
	43	><TD
	44	WIDTH="10%"
	45	ALIGN="left"
	46	VALIGN="bottom"
	47	><A
	48	HREF="sdlsemtrywait.html"
	49	ACCESSKEY="P"
	50	>Prev</A
	51	></TD
	52	><TD
	53	WIDTH="80%"
	54	ALIGN="center"
	55	VALIGN="bottom"
	56	></TD
	57	><TD
	58	WIDTH="10%"
	59	ALIGN="right"
	60	VALIGN="bottom"
	61	><A
	62	HREF="sdlsempost.html"
	63	ACCESSKEY="N"
	64	>Next</A
65	></TD
66	></TR
67	></TABLE
68	><HR
69	ALIGN="LEFT"
70	WIDTH="100%"></DIV
71	><H1
72	><A
73	NAME="SDLSEMWAITTIMEOUT"
74	></A
75	>SDL_SemWaitTimeout</H1
76	><DIV
77	CLASS="REFNAMEDIV"
78	><A
79	NAME="AEN8120"
80	></A
81	><H2
82	>Name</H2
83	>SDL_SemWaitTimeout -- Lock a semaphore, but only wait up to a specified maximum time.</DIV
84	><DIV
85	CLASS="REFSYNOPSISDIV"
86	><A
87	NAME="AEN8123"
88	></A
89	><H2
90	>Synopsis</H2
91	><DIV
92	CLASS="FUNCSYNOPSIS"
93	><A
94	NAME="AEN8124"
95	></A
96	><P
97	></P
98	><PRE
99	CLASS="FUNCSYNOPSISINFO"
100	>#include "SDL.h"
101	#include "SDL_thread.h"</PRE
102	><P
103	><CODE
104	><CODE
105	CLASS="FUNCDEF"
106	>int <B
107	CLASS="FSFUNC"
108	>SDL_SemWaitTimeout</B
109	></CODE
110	>(SDL_sem *sem, Uint32 timeout);</CODE
111	></P
112	><P
113	></P
114	></DIV
115	></DIV
116	><DIV
117	CLASS="REFSECT1"
118	><A
119	NAME="AEN8130"
120	></A
121	><H2
122	>Description</H2
123	><P
124	><TT
125	CLASS="FUNCTION"
126	>SDL_SemWaitTimeout()</TT
127	> is a varient of
128	<A
129	HREF="sdlsemwait.html"
130	>SDL_SemWait</A
131	>
132	with a maximum timeout value.
133	If the value of the semaphore pointed to by <TT
134	CLASS="PARAMETER"
135	><I
136	>sem</I
137	></TT
138	> is
139	positive (greater than zero) it will atomically decrement the semaphore value
140	and return 0, otherwise it will wait up to <TT
141	CLASS="PARAMETER"
142	><I
143	>timeout</I
144	></TT
145	>
146	milliseconds trying to lock the semaphore. This function is to be avoided if
147	possible since on some platforms it is implemented by polling the semaphore
148	every millisecond in a busy loop.</P
149	><P
150	>After <TT
151	CLASS="FUNCTION"
152	>SDL_SemWaitTimeout()</TT
153	> is successful, the semaphore
154	can be released and its count atomically incremented by a successful call to
155	<A
156	HREF="sdlsempost.html"
157	>SDL_SemPost</A
158	>.</P
159	></DIV
160	><DIV
161	CLASS="REFSECT1"
162	><A
163	NAME="AEN8140"
164	></A
165	><H2
166	>Return Value</H2
167	><P
168	>Returns <SPAN
169	CLASS="RETURNVALUE"
170	>0</SPAN
171	> if the semaphore was successfully locked or
172	either <SPAN
173	CLASS="RETURNVALUE"
174	>SDL_MUTEX_TIMEDOUT</SPAN
175	> or <SPAN
176	CLASS="RETURNVALUE"
177	>-1</SPAN
178	>
179	if the timeout period was exceeded or there was an error, respectivly.</P
180	><P
181	>If the semaphore was not successfully locked, the semaphore will be unchanged.</P
182	></DIV
183	><DIV
184	CLASS="REFSECT1"
185	><A
186	NAME="AEN8147"
187	></A
188	><H2
189	>Examples</H2
190	><P
191	><PRE
192	CLASS="PROGRAMLISTING"
193	>res = SDL_SemWaitTimeout(my_sem, WAIT_TIMEOUT_MILLISEC);
194
195	if (res == SDL_MUTEX_TIMEDOUT) {
196	return TRY_AGAIN;
197	}
198	if (res == -1) {
199	return WAIT_ERROR;
200	}
201
202	...
203
204	SDL_SemPost(my_sem);</PRE
205	></P
206	></DIV
207	><DIV
208	CLASS="REFSECT1"
209	><A
210	NAME="AEN8151"
211	></A
212	><H2
213	>See Also</H2
214	><P
215	><A
216	HREF="sdlcreatesemaphore.html"
217	><TT
218	CLASS="FUNCTION"
219	>SDL_CreateSemaphore</TT
220	></A
221	>,
222	<A
223	HREF="sdldestroysemaphore.html"
224	><TT
225	CLASS="FUNCTION"
226	>SDL_DestroySemaphore</TT
227	></A
228	>,
229	<A
230	HREF="sdlsemwait.html"
231	><TT
232	CLASS="FUNCTION"
233	>SDL_SemWait</TT
234	></A
235	>,
236	<A
237	HREF="sdlsemtrywait.html"
238	><TT
239	CLASS="FUNCTION"
240	>SDL_SemTryWait</TT
241	></A
242	>,
243	<A
244	HREF="sdlsempost.html"
245	><TT
246	CLASS="FUNCTION"
247	>SDL_SemPost</TT
248	></A
249	>,
250	<A
251	HREF="sdlsemvalue.html"
252	><TT
253	CLASS="FUNCTION"
254	>SDL_SemValue</TT
255	></A
256	></P
257	></DIV
258	><DIV
259	CLASS="NAVFOOTER"
260	><HR
261	ALIGN="LEFT"
262	WIDTH="100%"><TABLE
263	SUMMARY="Footer navigation table"
264	WIDTH="100%"
265	BORDER="0"
266	CELLPADDING="0"
267	CELLSPACING="0"
268	><TR
269	><TD
270	WIDTH="33%"
271	ALIGN="left"
272	VALIGN="top"
273	><A
274	HREF="sdlsemtrywait.html"
275	ACCESSKEY="P"
276	>Prev</A
277	></TD
278	><TD
279	WIDTH="34%"
280	ALIGN="center"
281	VALIGN="top"
282	><A
283	HREF="index.html"
284	ACCESSKEY="H"
285	>Home</A
286	></TD
287	><TD
288	WIDTH="33%"
289	ALIGN="right"
290	VALIGN="top"
291	><A
292	HREF="sdlsempost.html"
293	ACCESSKEY="N"
294	>Next</A
295	></TD
296	></TR
297	><TR
298	><TD
299	WIDTH="33%"
300	ALIGN="left"
301	VALIGN="top"
302	>SDL_SemTryWait</TD
303	><TD
304	WIDTH="34%"
305	ALIGN="center"
306	VALIGN="top"
307	><A
308	HREF="thread.html"
309	ACCESSKEY="U"
310	>Up</A
311	></TD
312	><TD
313	WIDTH="33%"
314	ALIGN="right"
315	VALIGN="top"
316	>SDL_SemPost</TD
317	></TR
318	></TABLE
319	></DIV
320	></BODY
321	></HTML
322	>