docs/latex/wx/recguard.tex

   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
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxRecursionGuard}}\label{wxrecursionguard}
  13
  14 wxRecursionGuard is a very simple class which can be used to prevent reentrancy
  15 problems in a function. It is not thread-safe and so should be used only in
  16 single-threaded programs or in combination with some thread synchronization
  17 mechanisms.
  18
  19 wxRecursionGuard 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
  36 As you can see, wxRecursionGuard simply tests the flag value and sets it to
  37 true if it hadn't been already set.
  38 \helpref{IsInside()}{wxrecursionguardisinside} allows testing the old flag
  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
  52 \wxheading{Library}
  53
  54 \helpref{wxBase}{librarieslist}
  55
  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