interface/recguard.h

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