]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/semaphor.tex
Typo correction
[wxWidgets.git] / 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 \latexignore{\rtfignore{\wxheading{Members}}}
40
41 \membersection{wxSemaphore::wxSemaphore}\label{wxsemaphorewxsemaphore}
42
43 \func{}{wxSemaphore}{\param{int }{initialcount = 0}, \param{int }{maxcount = 0}}
44
45 Specifying a {\it maxcount} of $0$ actually makes wxSemaphore behave as if
46 there is no upper limit. If maxcount is $1$, the semaphore behaves exactly as a
47 mutex.
48
49 {\it initialcount} is the initial value of the semaphore which must be between
50 $0$ and {\it maxcount} (if it is not set to $0$).
51
52 \membersection{wxSemaphore::\destruct{wxSemaphore}}\label{wxsemaphoredtor}
53
54 \func{}{\destruct{wxSemaphore}}{\void}
55
56 Destructor is not virtual, don't use this class polymorphically.
57
58 \membersection{wxSemaphore::Post}\label{wxsemaphorepost}
59
60 \func{wxSemaError }{Post}{\void}
61
62 Increments the semaphore count and signals one of the waiting
63 threads in an atomic way. Returns wxSEMA\_OVERFLOW if the count
64 would increase the counter past the maximum.
65
66 \wxheading{Return value}
67
68 One of:
69
70 \twocolwidtha{7cm}
71 \begin{twocollist}\itemsep=0pt
72 \twocolitem{{\bf wxSEMA\_NO\_ERROR}}{There was no error.}
73 \twocolitem{{\bf wxSEMA\_INVALID}}{Semaphore hasn't been initialized successfully.}
74 \twocolitem{{\bf wxSEMA\_OVERFLOW}}{Post() would increase counter past the max.}
75 \twocolitem{{\bf wxSEMA\_MISC\_ERROR}}{Miscellaneous error.}
76 \end{twocollist}
77
78
79 \membersection{wxSemaphore::TryWait}\label{wxsemaphoretrywait}
80
81 \func{wxSemaError }{TryWait}{\void}
82
83 Same as \helpref{Wait()}{wxsemaphorewait}, but returns immediately.
84
85 \wxheading{Return value}
86
87 One of:
88
89 \twocolwidtha{7cm}
90 \begin{twocollist}\itemsep=0pt
91 \twocolitem{{\bf wxSEMA\_NO\_ERROR}}{There was no error.}
92 \twocolitem{{\bf wxSEMA\_INVALID}}{Semaphore hasn't been initialized successfully.}
93 \twocolitem{{\bf wxSEMA\_BUSY}}{Returned by TryWait() if Wait() would block, i.e. the count is zero.}
94 \twocolitem{{\bf wxSEMA\_MISC\_ERROR}}{Miscellaneous error.}
95 \end{twocollist}
96
97
98 \membersection{wxSemaphore::Wait}\label{wxsemaphorewait}
99
100 \func{wxSemaError }{Wait}{\void}
101
102 Wait indefinitely until the semaphore count becomes strictly positive
103 and then decrement it and return.
104
105 \wxheading{Return value}
106
107 One of:
108
109 \twocolwidtha{7cm}
110 \begin{twocollist}\itemsep=0pt
111 \twocolitem{{\bf wxSEMA\_NO\_ERROR}}{There was no error.}
112 \twocolitem{{\bf wxSEMA\_INVALID}}{Semaphore hasn't been initialized successfully.}
113 \twocolitem{{\bf wxSEMA\_MISC\_ERROR}}{Miscellaneous error.}
114 \end{twocollist}
115
116 \membersection{wxSemaphore::WaitTimeout}\label{wxsemaphorewaittimeout}
117
118 \func{wxSemaError }{WaitTimeout}{\param{unsigned
119 long}{timeout\_millis}}
120
121 Same as \helpref{Wait()}{wxsemaphorewait}, but with a timeout
122 limit.
123
124 \wxheading{Return value}
125
126 One of:
127
128 \twocolwidtha{7cm}
129 \begin{twocollist}\itemsep=0pt
130 \twocolitem{{\bf wxSEMA\_NO\_ERROR}}{There was no error.}
131 \twocolitem{{\bf wxSEMA\_INVALID}}{Semaphore hasn't been initialized successfully.}
132 \twocolitem{{\bf wxSEMA\_TIMEOUT}}{Timeout occurred without receiving semaphore.}
133 \twocolitem{{\bf wxSEMA\_MISC\_ERROR}}{Miscellaneous error.}
134 \end{twocollist}