interface/wx/scopeguard.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        scopeguard.h
   3 // Purpose:     interface of global functions
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxScopeGuard
  11
  12     Scope guard is an object which allows executing an action on scope exit.
  13
  14     The objects of this class must be constructed using wxMakeGuard() function.
  15
  16     @nolibrary
  17     @category{misc}
  18  */
  19 class wxScopeGuard
  20 {
  21 public:
  22     /**
  23         Call this method to dismiss the execution of the action on scope exit.
  24
  25         A typical example:
  26         @code
  27             Update1();
  28
  29             // ensure that changes done so far are rolled back if the next
  30             // operation throws
  31             wxScopeGuard guard = wxMakeGuard(RollBack);
  32             Update2();
  33
  34             // it didn't throw so commit the changes, i.e. avoid rolling back
  35             guard.Dismiss();
  36         @endcode
  37      */
  38     void Dismiss();
  39 };
  40
  41 /** @addtogroup group_funcmacro_misc */
  42 //@{
  43 /**
  44     Returns a scope guard object which will call the specified function with
  45     the given parameters on scope exit.
  46
  47     This function is overloaded to take several parameters up to some
  48     implementation-defined (but relatively low) limit.
  49
  50     The @a func should be a functor taking parameters of the types P1, ..., PN,
  51     i.e. the expression @c func(p1, ..., pN) should be valid.
  52  */
  53 template <typename F, typename P1, ..., typename PN>
  54 wxScopeGuard wxMakeGuard(F func, P1 p1, ..., PN pN);
  55
  56 //@}
  57
  58 /** @addtogroup group_funcmacro_misc */
  59 //@{
  60 /**
  61     Ensure that the global @a function with a few (up to some
  62     implementation-defined limit) is executed on scope exit, whether due to a
  63     normal function return or because an exception has been thrown.
  64
  65     A typical example of its usage:
  66
  67     @code
  68     void *buf = malloc(size);
  69     wxON_BLOCK_EXIT1(free, buf);
  70     @endcode
  71
  72     Please see the original article by Andrei Alexandrescu and Petru Marginean
  73     published in December 2000 issue of C/C++ Users Journal for more details.
  74
  75     @see wxON_BLOCK_EXIT_OBJ0()
  76
  77     @header{wx/scopeguard.h}
  78 */
  79 #define wxON_BLOCK_EXIT(function, ...)
  80 #define wxON_BLOCK_EXIT0(function)
  81 #define wxON_BLOCK_EXIT1(function, p1)
  82 #define wxON_BLOCK_EXIT2(function, p1, p2)
  83 #define wxON_BLOCK_EXIT3(function, p1, p2, p3)
  84 //@}
  85
  86 /** @addtogroup group_funcmacro_misc */
  87 //@{
  88 /**
  89     This family of macros is similar to wxON_BLOCK_EXIT(), but calls a method
  90     of the given object instead of a free function.
  91
  92     @header{wx/scopeguard.h}
  93 */
  94 #define wxON_BLOCK_EXIT_OBJ(object, method, ...)
  95 #define wxON_BLOCK_EXIT_OBJ0(object, method)
  96 #define wxON_BLOCK_EXIT_OBJ1(object, method, p1)
  97 #define wxON_BLOCK_EXIT_OBJ2(object, method, p1, p2)
  98 #define wxON_BLOCK_EXIT_OBJ3(object, method, p1, p2, p3)
  99 //@}
 100
 101 /** @addtogroup group_funcmacro_misc */
 102 //@{
 103 /**
 104     This family of macros is similar to wxON_BLOCK_OBJ(), but calls a method
 105     of @c this object instead of a method of the specified object.
 106
 107     @header{wx/scopeguard.h}
 108 */
 109 #define wxON_BLOCK_EXIT_THIS(method, ...)
 110 #define wxON_BLOCK_EXIT_THIS0(method)
 111 #define wxON_BLOCK_EXIT_THIS1(method, p1)
 112 #define wxON_BLOCK_EXIT_THIS2(method, p1, p2)
 113 #define wxON_BLOCK_EXIT_THIS3(method, p1, p2, p3)
 114 //@}
 115
 116 /** @addtogroup group_funcmacro_misc */
 117 //@{
 118 /**
 119     This macro sets a variable to the specified value on scope exit.
 120
 121     Example of usage:
 122     @code
 123     void foo()
 124     {
 125         bool isDoingSomething = true;
 126         {
 127             wxON_BLOCK_EXIT_SET(isDoingSomething, false);
 128             ... do something ...
 129         }
 130         ... isDoingSomething is false now ...
 131     }
 132     @endcode
 133
 134     Notice that @a value is copied, i.e. stored by value, so it can be a
 135     temporary object returned by a function call, for example.
 136
 137     @see wxON_BLOCK_EXIT_OBJ0(), wxON_BLOCK_EXIT_NULL()
 138
 139     @header{wx/scopeguard.h}
 140 */
 141 #define wxON_BLOCK_EXIT_SET(var, value)
 142
 143 /**
 144     This macro sets the pointer passed to it as argument to NULL on scope exit.
 145
 146     It must be used instead of wxON_BLOCK_EXIT_SET() when the value being set
 147     is @c NULL.
 148
 149     @header{wx/scopeguard.h}
 150  */
 151 #define wxON_BLOCK_EXIT_NULL(ptr)
 152
 153 //@}
 154