projects / wxWidgets.git / blame
| Commit | Line | Data |
|---|---|---|
| be809868 VZ |
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, the semaphores are useful to restict access to a shared resource | |
| 24 | which can only be accessed by some fixed number of clients at once. 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{void}{Post}{\void} | |
| 61 | ||
| 62 | Increments the semaphore count and signals one of the waiting threads in an | |
| 63 | atomic way. | |
| 64 | ||
| 65 | \membersection{wxSemaphore::TryWait}\label{wxsemaphoretrywait} | |
| 66 | ||
| 67 | \func{bool}{TryWait}{\void} | |
| 68 | ||
| 69 | Same as \helpref{Wait()}{wxsemaphorewait}, but does not block, returns | |
| 70 | {\tt TRUE} if the semaphore was successfully acquired and {\tt FALSE} if the | |
| 71 | count is zero and it couldn't be done. | |
| 72 | ||
| 73 | \membersection{wxSemaphore::Wait}\label{wxsemaphorewait} | |
| 74 | ||
| 75 | \func{void}{Wait}{\void} | |
| 76 | ||
| 77 | Wait indefinitely until the semaphore count becomes strictly positive | |
| 78 | and then decrement it and return. | |
| 79 | ||
| 80 | \func{bool}{Wait}{\param{unsigned long }{timeout\_millis}} | |
| 81 | ||
| 54946cc9 | 82 | Same as the version above, but with a timeout limit: returns {\tt TRUE} if the |
| be809868 VZ |
83 | semaphore was acquired and {\tt FALSE} if the timeout has ellapsed |
| 84 |