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