[wxWidgets.git] / docs / latex / wx / recguard.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name:        recguard.tex
%% Purpose:     wxRecursionGuard documentation
%% Author:      Vadim Zeitlin
%% Modified by:
%% Created:     14.08.03
%% RCS-ID:      $Id$
%% Copyright:   (c) Vadim Zeitlin
%% License:     wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{\class{wxRecursionGuard}}\label{wxrecursionguard}

wxRecursionGuard is a very simple class which can be used to prevent reentrancy
problems in a function. It is not thread-safe and so should be used only in
single-threaded programs or in combination with some thread synchronization
mechanisms.

wxRecursionGuard is always used together with the 
\helpref{wxRecursionGuardFlag}{wxrecursionguardflag} like in this example:
\begin{verbatim}
    void Foo()
    {
        static wxRecursionGuardFlag s_flag;
        wxRecursionGuard guard(s_flag);
        if ( guard.IsInside() )
        {
            // don't allow reentrancy
            return;
        }

        ...
    }
\end{verbatim}

As you can see, wxRecursionGuard simply tests the flag value and sets it to
true if it hadn't been already set. 
\helpref{IsInside()}{wxrecursionguardisinside} allows testing the old flag
value. The advantage of using this class compared to directly manipulating the
flag is that the flag is always reset in the wxRecursionGuard destructor and so
you don't risk to forget to do it even if the function returns in an unexpected
way (for example because an exception has been thrown).

\wxheading{Derived from}

No base class

\wxheading{Include files}

<wx/recguard.h>

\wxheading{Library}

\helpref{wxBase}{librarieslist}


\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxRecursionGuard::wxRecursionGuard}\label{wxrecursionguardctor}

\func{}{wxRecursionGuard}{\param{wxRecursionGuardFlag\& }{flag}}

A wxRecursionGuard object must always be initialized with a (static) 
\helpref{wxRecursionGuardFlag}{wxrecursionguardflag}. The constructor saves the
value of the flag to be able to return the correct value from 
\helpref{IsInside}{wxrecursionguardisinside}.


\membersection{wxRecursionGuard::\destruct{wxRecursionGuard}}\label{wxrecursionguarddtor}

\func{}{\destruct{wxRecursionGuard}}{\void}

The destructor resets the flag value so that the function can be entered again
the next time.

Note that it is not virtual and so this class is not meant to be derived from
(besides, there is absolutely no reason to do it anyhow).


\membersection{wxRecursionGuard::IsInside}\label{wxrecursionguardisinside}

\constfunc{bool}{IsInside}{\void}

Returns \true if we're already inside the code block ``protected'' by this
wxRecursionGuard (i.e. between this line and the end of current scope). Usually
the function using wxRecursionGuard takes some specific actions in such case
(may be simply returning) to prevent reentrant calls to itself.

If this method returns \false, it is safe to continue.


\section{\class{wxRecursionGuardFlag}}\label{wxrecursionguardflag}

This is a completely opaque class which exists only to be used with 
\helpref{wxRecursionGuard}{wxrecursionguard}, please see the example in that
class documentation.

Please notice that wxRecursionGuardFlag object \emph{must} be declared 
\texttt{static} or the recursion would never be detected.

\wxheading{Derived from}

No base class

\wxheading{Include files}

<wx/recguard.h>
Commit	Line	Data
7b4d7f99 VZ	1	%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	2	%% Name: recguard.tex
	3	%% Purpose: wxRecursionGuard documentation
	4	%% Author: Vadim Zeitlin
	5	%% Modified by:
	6	%% Created: 14.08.03
	7	%% RCS-ID: $Id$
	8	%% Copyright: (c) Vadim Zeitlin
8795498c	9	%% License: wxWindows license
7b4d7f99 VZ	10	%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	11
	12	\section{\class{wxRecursionGuard}}\label{wxrecursionguard}
	13
	14	wxRecursionGuard is a very simple class which can be used to prevent reentrancy
154b6b0f	15	problems in a function. It is not thread-safe and so should be used only in
7b4d7f99 VZ	16	single-threaded programs or in combination with some thread synchronization
	17	mechanisms.
	18
684761db	19	wxRecursionGuard is always used together with the
7b4d7f99 VZ	20	\helpref{wxRecursionGuardFlag}{wxrecursionguardflag} like in this example:
	21	\begin{verbatim}
	22	void Foo()
	23	{
	24	static wxRecursionGuardFlag s_flag;
	25	wxRecursionGuard guard(s_flag);
	26	if ( guard.IsInside() )
	27	{
	28	// don't allow reentrancy
	29	return;
	30	}
	31
	32	...
	33	}
	34	\end{verbatim}
	35
	36	As you can see, wxRecursionGuard simply tests the flag value and sets it to
	37	true if it hadn't been already set.
684761db	38	\helpref{IsInside()}{wxrecursionguardisinside} allows testing the old flag
7b4d7f99 VZ	39	value. The advantage of using this class compared to directly manipulating the
	40	flag is that the flag is always reset in the wxRecursionGuard destructor and so
	41	you don't risk to forget to do it even if the function returns in an unexpected
	42	way (for example because an exception has been thrown).
	43
	44	\wxheading{Derived from}
	45
	46	No base class
	47
	48	\wxheading{Include files}
	49
	50	<wx/recguard.h>
	51
a7af285d VZ	52	\wxheading{Library}
	53
	54	\helpref{wxBase}{librarieslist}
	55
7b4d7f99 VZ	56
	57	\latexignore{\rtfignore{\wxheading{Members}}}
	58
	59	\membersection{wxRecursionGuard::wxRecursionGuard}\label{wxrecursionguardctor}
	60
	61	\func{}{wxRecursionGuard}{\param{wxRecursionGuardFlag\& }{flag}}
	62
	63	A wxRecursionGuard object must always be initialized with a (static)
	64	\helpref{wxRecursionGuardFlag}{wxrecursionguardflag}. The constructor saves the
	65	value of the flag to be able to return the correct value from
	66	\helpref{IsInside}{wxrecursionguardisinside}.
	67
	68
	69	\membersection{wxRecursionGuard::\destruct{wxRecursionGuard}}\label{wxrecursionguarddtor}
	70
	71	\func{}{\destruct{wxRecursionGuard}}{\void}
	72
	73	The destructor resets the flag value so that the function can be entered again
	74	the next time.
	75
	76	Note that it is not virtual and so this class is not meant to be derived from
	77	(besides, there is absolutely no reason to do it anyhow).
	78
	79
	80	\membersection{wxRecursionGuard::IsInside}\label{wxrecursionguardisinside}
	81
	82	\constfunc{bool}{IsInside}{\void}
	83
	84	Returns \true if we're already inside the code block ``protected'' by this
	85	wxRecursionGuard (i.e. between this line and the end of current scope). Usually
	86	the function using wxRecursionGuard takes some specific actions in such case
	87	(may be simply returning) to prevent reentrant calls to itself.
	88
	89	If this method returns \false, it is safe to continue.
	90
	91
	92
	93	\section{\class{wxRecursionGuardFlag}}\label{wxrecursionguardflag}
	94
	95	This is a completely opaque class which exists only to be used with
	96	\helpref{wxRecursionGuard}{wxrecursionguard}, please see the example in that
	97	class documentation.
	98
	99	Please notice that wxRecursionGuardFlag object \emph{must} be declared
	100	\texttt{static} or the recursion would never be detected.
	101
	102	\wxheading{Derived from}
	103
	104	No base class
	105
	106	\wxheading{Include files}
	107
	108	<wx/recguard.h>
	109