X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2edb0bdef6238c8c246b6978bc14828b7033d931..c266eff98c5e44012647f54f38a1e29ecabd8759:/docs/latex/wx/semaphor.tex?ds=sidebyside diff --git a/docs/latex/wx/semaphor.tex b/docs/latex/wx/semaphor.tex index 335a399597..9d9271f944 100644 --- a/docs/latex/wx/semaphor.tex +++ b/docs/latex/wx/semaphor.tex @@ -20,8 +20,8 @@ decrements the counter. As soon as it reaches $0$, any subsequent calls to counter becomes strictly positive again as the result of calling \helpref{Post}{wxsemaphorepost} which increments the counter. -In general, the semaphores are useful to restrict access to a shared resource -which can only be accessed by some fixed number of clients at once. For +In general, semaphores are useful to restrict access to a shared resource +which can only be accessed by some fixed number of clients at the same time. For example, when modeling a hotel reservation system a semaphore with the counter equal to the total number of available rooms could be created. Each time a room is reserved, the semaphore should be acquired by calling @@ -36,6 +36,10 @@ No base class +\wxheading{Library} + +\helpref{wxBase}{librarieslist} + \latexignore{\rtfignore{\wxheading{Members}}} \membersection{wxSemaphore::wxSemaphore}\label{wxsemaphorewxsemaphore} @@ -43,8 +47,9 @@ No base class \func{}{wxSemaphore}{\param{int }{initialcount = 0}, \param{int }{maxcount = 0}} Specifying a {\it maxcount} of $0$ actually makes wxSemaphore behave as if -there is no upper limit. If maxcount is $1$ the semaphore behaves exactly as a -mutex. +there is no upper limit. If maxcount is $1$, the semaphore behaves almost as a +mutex (but unlike a mutex it can be released by a thread different from the one +which acquired it). {\it initialcount} is the initial value of the semaphore which must be between $0$ and {\it maxcount} (if it is not set to $0$). @@ -57,28 +62,78 @@ Destructor is not virtual, don't use this class polymorphically. \membersection{wxSemaphore::Post}\label{wxsemaphorepost} -\func{void}{Post}{\void} +\func{wxSemaError }{Post}{\void} + +Increments the semaphore count and signals one of the waiting +threads in an atomic way. Returns wxSEMA\_OVERFLOW if the count +would increase the counter past the maximum. + +\wxheading{Return value} + +One of: + +\twocolwidtha{7cm} +\begin{twocollist}\itemsep=0pt +\twocolitem{{\bf wxSEMA\_NO\_ERROR}}{There was no error.} +\twocolitem{{\bf wxSEMA\_INVALID}}{Semaphore hasn't been initialized successfully.} +\twocolitem{{\bf wxSEMA\_OVERFLOW}}{Post() would increase counter past the max.} +\twocolitem{{\bf wxSEMA\_MISC\_ERROR}}{Miscellaneous error.} +\end{twocollist} -Increments the semaphore count and signals one of the waiting threads in an -atomic way. \membersection{wxSemaphore::TryWait}\label{wxsemaphoretrywait} -\func{bool}{TryWait}{\void} +\func{wxSemaError }{TryWait}{\void} + +Same as \helpref{Wait()}{wxsemaphorewait}, but returns immediately. + +\wxheading{Return value} + +One of: + +\twocolwidtha{7cm} +\begin{twocollist}\itemsep=0pt +\twocolitem{{\bf wxSEMA\_NO\_ERROR}}{There was no error.} +\twocolitem{{\bf wxSEMA\_INVALID}}{Semaphore hasn't been initialized successfully.} +\twocolitem{{\bf wxSEMA\_BUSY}}{Returned by TryWait() if Wait() would block, i.e. the count is zero.} +\twocolitem{{\bf wxSEMA\_MISC\_ERROR}}{Miscellaneous error.} +\end{twocollist} -Same as \helpref{Wait()}{wxsemaphorewait}, but does not block, returns -{\tt TRUE} if the semaphore was successfully acquired and {\tt FALSE} if the -count is zero and it couldn't be done. \membersection{wxSemaphore::Wait}\label{wxsemaphorewait} -\func{void}{Wait}{\void} +\func{wxSemaError }{Wait}{\void} Wait indefinitely until the semaphore count becomes strictly positive and then decrement it and return. -\func{bool}{Wait}{\param{unsigned long }{timeout\_millis}} +\wxheading{Return value} + +One of: + +\twocolwidtha{7cm} +\begin{twocollist}\itemsep=0pt +\twocolitem{{\bf wxSEMA\_NO\_ERROR}}{There was no error.} +\twocolitem{{\bf wxSEMA\_INVALID}}{Semaphore hasn't been initialized successfully.} +\twocolitem{{\bf wxSEMA\_MISC\_ERROR}}{Miscellaneous error.} +\end{twocollist} + +\membersection{wxSemaphore::WaitTimeout}\label{wxsemaphorewaittimeout} + +\func{wxSemaError }{WaitTimeout}{\param{unsigned +long}{timeout\_millis}} + +Same as \helpref{Wait()}{wxsemaphorewait}, but with a timeout +limit. + +\wxheading{Return value} -Same as the version above, but with a timeout limit: returns {\tt TRUE} if the -semaphore was acquired and {\tt FALSE} if the timeout has elapsed +One of: +\twocolwidtha{7cm} +\begin{twocollist}\itemsep=0pt +\twocolitem{{\bf wxSEMA\_NO\_ERROR}}{There was no error.} +\twocolitem{{\bf wxSEMA\_INVALID}}{Semaphore hasn't been initialized successfully.} +\twocolitem{{\bf wxSEMA\_TIMEOUT}}{Timeout occurred without receiving semaphore.} +\twocolitem{{\bf wxSEMA\_MISC\_ERROR}}{Miscellaneous error.} +\end{twocollist}