1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 %% Purpose: wxSemaphore documentation
4 %% Author: Vadim Zeitlin
8 %% Copyright: (c) 2002 Vadim Zeitlin
9 %% License: wxWindows license
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
12 \section{\class{wxSemaphore
}}\label{wxsemaphore
}
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.
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
}.
31 \wxheading{Derived from
}
35 \wxheading{Include files
}
41 \helpref{wxBase
}{librarieslist
}
43 \latexignore{\rtfignore{\wxheading{Members
}}}
45 \membersection{wxSemaphore::wxSemaphore
}\label{wxsemaphorewxsemaphore
}
47 \func{}{wxSemaphore
}{\param{int
}{initialcount =
0},
\param{int
}{maxcount =
0}}
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 exactly as a
53 {\it initialcount
} is the initial value of the semaphore which must be between
54 $
0$ and
{\it maxcount
} (if it is not set to $
0$).
56 \membersection{wxSemaphore::
\destruct{wxSemaphore
}}\label{wxsemaphoredtor
}
58 \func{}{\destruct{wxSemaphore
}}{\void}
60 Destructor is not virtual, don't use this class polymorphically.
62 \membersection{wxSemaphore::Post
}\label{wxsemaphorepost
}
64 \func{wxSemaError
}{Post
}{\void}
66 Increments the semaphore count and signals one of the waiting
67 threads in an atomic way. Returns wxSEMA
\_OVERFLOW if the count
68 would increase the counter past the maximum.
70 \wxheading{Return value
}
75 \begin{twocollist
}\itemsep=
0pt
76 \twocolitem{{\bf wxSEMA
\_NO\_ERROR}}{There was no error.
}
77 \twocolitem{{\bf wxSEMA
\_INVALID}}{Semaphore hasn't been initialized successfully.
}
78 \twocolitem{{\bf wxSEMA
\_OVERFLOW}}{Post() would increase counter past the max.
}
79 \twocolitem{{\bf wxSEMA
\_MISC\_ERROR}}{Miscellaneous error.
}
83 \membersection{wxSemaphore::TryWait
}\label{wxsemaphoretrywait
}
85 \func{wxSemaError
}{TryWait
}{\void}
87 Same as
\helpref{Wait()
}{wxsemaphorewait
}, but returns immediately.
89 \wxheading{Return value
}
94 \begin{twocollist
}\itemsep=
0pt
95 \twocolitem{{\bf wxSEMA
\_NO\_ERROR}}{There was no error.
}
96 \twocolitem{{\bf wxSEMA
\_INVALID}}{Semaphore hasn't been initialized successfully.
}
97 \twocolitem{{\bf wxSEMA
\_BUSY}}{Returned by TryWait() if Wait() would block, i.e. the count is zero.
}
98 \twocolitem{{\bf wxSEMA
\_MISC\_ERROR}}{Miscellaneous error.
}
102 \membersection{wxSemaphore::Wait
}\label{wxsemaphorewait
}
104 \func{wxSemaError
}{Wait
}{\void}
106 Wait indefinitely until the semaphore count becomes strictly positive
107 and then decrement it and return.
109 \wxheading{Return value
}
114 \begin{twocollist
}\itemsep=
0pt
115 \twocolitem{{\bf wxSEMA
\_NO\_ERROR}}{There was no error.
}
116 \twocolitem{{\bf wxSEMA
\_INVALID}}{Semaphore hasn't been initialized successfully.
}
117 \twocolitem{{\bf wxSEMA
\_MISC\_ERROR}}{Miscellaneous error.
}
120 \membersection{wxSemaphore::WaitTimeout
}\label{wxsemaphorewaittimeout
}
122 \func{wxSemaError
}{WaitTimeout
}{\param{unsigned
123 long
}{timeout
\_millis}}
125 Same as
\helpref{Wait()
}{wxsemaphorewait
}, but with a timeout
128 \wxheading{Return value
}
133 \begin{twocollist
}\itemsep=
0pt
134 \twocolitem{{\bf wxSEMA
\_NO\_ERROR}}{There was no error.
}
135 \twocolitem{{\bf wxSEMA
\_INVALID}}{Semaphore hasn't been initialized successfully.
}
136 \twocolitem{{\bf wxSEMA
\_TIMEOUT}}{Timeout occurred without receiving semaphore.
}
137 \twocolitem{{\bf wxSEMA
\_MISC\_ERROR}}{Miscellaneous error.
}