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