interface/wx/recguard.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        recguard.h
   3 // Purpose:     interface of wxRecursionGuardFlag
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     @class wxRecursionGuardFlag
  10
  11     This is a completely opaque class which exists only to be used with
  12     wxRecursionGuard, please see the example in that class' documentation.
  13
  14     @remarks
  15
  16     wxRecursionGuardFlag object must be declared @c static or the recursion
  17     would never be detected.
  18
  19     @library{wxbase}
  20     @category{misc}
  21 */
  22 class wxRecursionGuardFlag
  23 {
  24 public:
  25
  26 };
  27
  28
  29
  30 /**
  31     @class wxRecursionGuard
  32
  33     wxRecursionGuard is a very simple class which can be used to prevent reentrancy
  34     problems in a function. It is not thread-safe and so should be used only in
  35     single-threaded programs or in combination with some thread synchronization
  36     mechanisms.
  37
  38     wxRecursionGuard is always used together with the
  39     wxRecursionGuardFlag like in this example:
  40
  41     @code
  42     void Foo()
  43     {
  44         static wxRecursionGuardFlag s_flag;
  45         wxRecursionGuard guard(s_flag);
  46         if ( guard.IsInside() )
  47         {
  48             // don't allow reentrancy
  49             return;
  50         }
  51
  52         ...
  53     }
  54     @endcode
  55
  56     As you can see, wxRecursionGuard simply tests the flag value and sets it to
  57     @true if it hadn't been already set.
  58     IsInside() allows testing the old flag
  59     value. The advantage of using this class compared to directly manipulating the
  60     flag is that the flag is always reset in the wxRecursionGuard destructor and so
  61     you don't risk to forget to do it even if the function returns in an unexpected
  62     way (for example because an exception has been thrown).
  63
  64     @library{wxbase}
  65     @category{misc}
  66 */
  67 class wxRecursionGuard
  68 {
  69 public:
  70     /**
  71         A wxRecursionGuard object must always be initialized with a @c static
  72         wxRecursionGuardFlag. The constructor saves the
  73         value of the flag to be able to return the correct value from
  74         IsInside().
  75     */
  76     wxRecursionGuard(wxRecursionGuardFlag& flag);
  77
  78     /**
  79         The destructor resets the flag value so that the function can be entered again
  80         the next time.
  81
  82         @note This is not virtual, so this class is not meant to be derived
  83               from (besides, there is absolutely no reason to do it anyhow).
  84     */
  85     ~wxRecursionGuard();
  86
  87     /**
  88         Returns @true if we're already inside the code block "protected" by this
  89         wxRecursionGuard (i.e. between this line and the end of current scope).
  90         Usually the function using wxRecursionGuard takes some specific actions
  91         in such case (may be simply returning) to prevent reentrant calls to itself.
  92
  93         If this method returns @false, it is safe to continue.
  94     */
  95     bool IsInside() const;
  96 };
  97