git.saurik.com Git - wxWidgets.git/blame_incremental

... / ...

Commit	Line	Data
	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}