docs/html/sdlsemtrywait.html

   1 <HTML
   2 ><HEAD
   3 ><TITLE
   4 >SDL_SemTryWait</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_SemWait"
  17 HREF="sdlsemwait.html"><LINK
  18 REL="NEXT"
  19 TITLE="SDL_SemWaitTimeout"
  20 HREF="sdlsemwaittimeout.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="sdlsemwait.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="sdlsemwaittimeout.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="SDLSEMTRYWAIT"
  74 ></A
  75 >SDL_SemTryWait</H1
  76 ><DIV
  77 CLASS="REFNAMEDIV"
  78 ><A
  79 NAME="AEN8069"
  80 ></A
  81 ><H2
  82 >Name</H2
  83 >SDL_SemTryWait&nbsp;--&nbsp;Attempt to lock a semaphore but don't suspend the thread.</DIV
  84 ><DIV
  85 CLASS="REFSYNOPSISDIV"
  86 ><A
  87 NAME="AEN8072"
  88 ></A
  89 ><H2
  90 >Synopsis</H2
  91 ><DIV
  92 CLASS="FUNCSYNOPSIS"
  93 ><A
  94 NAME="AEN8073"
  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_SemTryWait</B
 109 ></CODE
 110 >(SDL_sem *sem);</CODE
 111 ></P
 112 ><P
 113 ></P
 114 ></DIV
 115 ></DIV
 116 ><DIV
 117 CLASS="REFSECT1"
 118 ><A
 119 NAME="AEN8079"
 120 ></A
 121 ><H2
 122 >Description</H2
 123 ><P
 124 ><TT
 125 CLASS="FUNCTION"
 126 >SDL_SemTryWait</TT
 127 > is a non-blocking varient of
 128 <A
 129 HREF="sdlsemwait.html"
 130 ><TT
 131 CLASS="FUNCTION"
 132 >SDL_SemWait</TT
 133 ></A
 134 >. If the value of the semaphore
 135 pointed to by <TT
 136 CLASS="PARAMETER"
 137 ><I
 138 >sem</I
 139 ></TT
 140 > is positive it will atomically
 141 decrement the semaphore value and return 0, otherwise it will return
 142 <SPAN
 143 CLASS="RETURNVALUE"
 144 >SDL_MUTEX_TIMEDOUT</SPAN
 145 > instead of suspending the thread.</P
 146 ><P
 147 >After <TT
 148 CLASS="FUNCTION"
 149 >SDL_SemTryWait</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="AEN8090"
 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_TIMEDOUT</SPAN
 172 > or <SPAN
 173 CLASS="RETURNVALUE"
 174 >-1</SPAN
 175 >
 176 if the thread would have suspended 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="AEN8097"
 184 ></A
 185 ><H2
 186 >Examples</H2
 187 ><P
 188 ><PRE
 189 CLASS="PROGRAMLISTING"
 190 >res = SDL_SemTryWait(my_sem);
 191
 192 if (res == SDL_MUTEX_TIMEDOUT) {
 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="AEN8101"
 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="sdlsemwaittimeout.html"
 235 ><TT
 236 CLASS="FUNCTION"
 237 >SDL_SemWaitTimeout</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 SUMMARY="Footer navigation table"
 261 WIDTH="100%"
 262 BORDER="0"
 263 CELLPADDING="0"
 264 CELLSPACING="0"
 265 ><TR
 266 ><TD
 267 WIDTH="33%"
 268 ALIGN="left"
 269 VALIGN="top"
 270 ><A
 271 HREF="sdlsemwait.html"
 272 ACCESSKEY="P"
 273 >Prev</A
 274 ></TD
 275 ><TD
 276 WIDTH="34%"
 277 ALIGN="center"
 278 VALIGN="top"
 279 ><A
 280 HREF="index.html"
 281 ACCESSKEY="H"
 282 >Home</A
 283 ></TD
 284 ><TD
 285 WIDTH="33%"
 286 ALIGN="right"
 287 VALIGN="top"
 288 ><A
 289 HREF="sdlsemwaittimeout.html"
 290 ACCESSKEY="N"
 291 >Next</A
 292 ></TD
 293 ></TR
 294 ><TR
 295 ><TD
 296 WIDTH="33%"
 297 ALIGN="left"
 298 VALIGN="top"
 299 >SDL_SemWait</TD
 300 ><TD
 301 WIDTH="34%"
 302 ALIGN="center"
 303 VALIGN="top"
 304 ><A
 305 HREF="thread.html"
 306 ACCESSKEY="U"
 307 >Up</A
 308 ></TD
 309 ><TD
 310 WIDTH="33%"
 311 ALIGN="right"
 312 VALIGN="top"
 313 >SDL_SemWaitTimeout</TD
 314 ></TR
 315 ></TABLE
 316 ></DIV
 317 ></BODY
 318 ></HTML
 319 >