docs/latex/wx/semaphor.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        semaphore.tex
   3 %% Purpose:     wxSemaphore documentation
   4 %% Author:      Vadim Zeitlin
   5 %% Modified by:
   6 %% Created:     02.04.02
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) 2002 Vadim Zeitlin
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxSemaphore}}\label{wxsemaphore}
  13
  14 wxSemaphore is a counter limiting the number of threads concurrently accessing
  15 a shared resource. This counter is always between $0$ and the maximum value
  16 specified during the semaphore creation. When the counter is strictly greater
  17 than $0$, a call to \helpref{Wait}{wxsemaphorewait} returns immediately and
  18 decrements the counter. As soon as it reaches $0$, any subsequent calls to
  19 \helpref{Wait}{wxsemaphorewait} block and only return when the semaphore
  20 counter becomes strictly positive again as the result of calling
  21 \helpref{Post}{wxsemaphorepost} which increments the counter.
  22
  23 In general, semaphores are useful to restrict access to a shared resource
  24 which can only be accessed by some fixed number of clients at the same time. For
  25 example, when modeling a hotel reservation system a semaphore with the counter
  26 equal to the total number of available rooms could be created. Each time a room
  27 is reserved, the semaphore should be acquired by calling
  28 \helpref{Wait}{wxsemaphorewait} and each time a room is freed it should be
  29 released by calling \helpref{Post}{wxsemaphorepost}.
  30
  31 \wxheading{Derived from}
  32
  33 No base class
  34
  35 \wxheading{Include files}
  36
  37 <wx/thread.h>
  38
  39 \wxheading{Library}
  40
  41 \helpref{wxBase}{librarieslist}
  42
  43 \latexignore{\rtfignore{\wxheading{Members}}}
  44
  45 \membersection{wxSemaphore::wxSemaphore}\label{wxsemaphorewxsemaphore}
  46
  47 \func{}{wxSemaphore}{\param{int }{initialcount = 0}, \param{int }{maxcount = 0}}
  48
  49 Specifying a {\it maxcount} of $0$ actually makes wxSemaphore behave as if
  50 there is no upper limit. If maxcount is $1$, the semaphore behaves almost as a
  51 mutex (but unlike a mutex it can be released by a thread different from the one
  52 which acquired it).
  53
  54 {\it initialcount} is the initial value of the semaphore which must be between
  55 $0$ and {\it maxcount} (if it is not set to $0$).
  56
  57 \membersection{wxSemaphore::\destruct{wxSemaphore}}\label{wxsemaphoredtor}
  58
  59 \func{}{\destruct{wxSemaphore}}{\void}
  60
  61 Destructor is not virtual, don't use this class polymorphically.
  62
  63 \membersection{wxSemaphore::Post}\label{wxsemaphorepost}
  64
  65 \func{wxSemaError }{Post}{\void}
  66
  67 Increments the semaphore count and signals one of the waiting
  68 threads in an atomic way. Returns wxSEMA\_OVERFLOW if the count
  69 would increase the counter past the maximum.
  70
  71 \wxheading{Return value}
  72
  73 One of:
  74
  75 \twocolwidtha{7cm}
  76 \begin{twocollist}\itemsep=0pt
  77 \twocolitem{{\bf wxSEMA\_NO\_ERROR}}{There was no error.}
  78 \twocolitem{{\bf wxSEMA\_INVALID}}{Semaphore hasn't been initialized successfully.}
  79 \twocolitem{{\bf wxSEMA\_OVERFLOW}}{Post() would increase counter past the max.}
  80 \twocolitem{{\bf wxSEMA\_MISC\_ERROR}}{Miscellaneous error.}
  81 \end{twocollist}
  82
  83
  84 \membersection{wxSemaphore::TryWait}\label{wxsemaphoretrywait}
  85
  86 \func{wxSemaError }{TryWait}{\void}
  87
  88 Same as \helpref{Wait()}{wxsemaphorewait}, but returns immediately.
  89
  90 \wxheading{Return value}
  91
  92 One of:
  93
  94 \twocolwidtha{7cm}
  95 \begin{twocollist}\itemsep=0pt
  96 \twocolitem{{\bf wxSEMA\_NO\_ERROR}}{There was no error.}
  97 \twocolitem{{\bf wxSEMA\_INVALID}}{Semaphore hasn't been initialized successfully.}
  98 \twocolitem{{\bf wxSEMA\_BUSY}}{Returned by TryWait() if Wait() would block, i.e. the count is zero.}
  99 \twocolitem{{\bf wxSEMA\_MISC\_ERROR}}{Miscellaneous error.}
 100 \end{twocollist}
 101
 102
 103 \membersection{wxSemaphore::Wait}\label{wxsemaphorewait}
 104
 105 \func{wxSemaError }{Wait}{\void}
 106
 107 Wait indefinitely until the semaphore count becomes strictly positive
 108 and then decrement it and return.
 109
 110 \wxheading{Return value}
 111
 112 One of:
 113
 114 \twocolwidtha{7cm}
 115 \begin{twocollist}\itemsep=0pt
 116 \twocolitem{{\bf wxSEMA\_NO\_ERROR}}{There was no error.}
 117 \twocolitem{{\bf wxSEMA\_INVALID}}{Semaphore hasn't been initialized successfully.}
 118 \twocolitem{{\bf wxSEMA\_MISC\_ERROR}}{Miscellaneous error.}
 119 \end{twocollist}
 120
 121 \membersection{wxSemaphore::WaitTimeout}\label{wxsemaphorewaittimeout}
 122
 123 \func{wxSemaError }{WaitTimeout}{\param{unsigned
 124 long}{timeout\_millis}}
 125
 126 Same as \helpref{Wait()}{wxsemaphorewait}, but with a timeout
 127 limit.
 128
 129 \wxheading{Return value}
 130
 131 One of:
 132
 133 \twocolwidtha{7cm}
 134 \begin{twocollist}\itemsep=0pt
 135 \twocolitem{{\bf wxSEMA\_NO\_ERROR}}{There was no error.}
 136 \twocolitem{{\bf wxSEMA\_INVALID}}{Semaphore hasn't been initialized successfully.}
 137 \twocolitem{{\bf wxSEMA\_TIMEOUT}}{Timeout occurred without receiving semaphore.}
 138 \twocolitem{{\bf wxSEMA\_MISC\_ERROR}}{Miscellaneous error.}
 139 \end{twocollist}