// Name: scopeguard.h
// Purpose: interface of global functions
// Author: wxWidgets team
-// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
-/** @ingroup group_funcmacro_misc */
+/**
+ @class wxScopeGuard
+
+ Scope guard is an object which allows executing an action on scope exit.
+
+ The objects of this class must be constructed using wxMakeGuard() function.
+
+ @nolibrary
+ @category{misc}
+ */
+class wxScopeGuard
+{
+public:
+ /**
+ Call this method to dismiss the execution of the action on scope exit.
+
+ A typical example:
+ @code
+ Update1();
+
+ // ensure that changes done so far are rolled back if the next
+ // operation throws
+ wxScopeGuard guard = wxMakeGuard(RollBack);
+ Update2();
+
+ // it didn't throw so commit the changes, i.e. avoid rolling back
+ guard.Dismiss();
+ @endcode
+ */
+ void Dismiss();
+};
+
+/** @addtogroup group_funcmacro_misc */
//@{
/**
- This macro ensures that the global @a function with 0, 1, 2 or more
- parameters (up to some implementation-defined limit) is executed on scope
- exit, whether due to a normal function return or because an exception has
- been thrown. A typical example of its usage:
+ Returns a scope guard object which will call the specified function with
+ the given parameters on scope exit.
+
+ This function is overloaded to take several parameters up to some
+ implementation-defined (but relatively low) limit.
+
+ The @a func should be a functor taking parameters of the types P1, ..., PN,
+ i.e. the expression @c func(p1, ..., pN) should be valid.
+ */
+template <typename F, typename P1, ..., typename PN>
+wxScopeGuard wxMakeGuard(F func, P1 p1, ..., PN pN);
+
+//@}
+
+/** @addtogroup group_funcmacro_misc */
+//@{
+/**
+ Ensure that the global @a function with a few (up to some
+ implementation-defined limit) is executed on scope exit, whether due to a
+ normal function return or because an exception has been thrown.
+
+ A typical example of its usage:
@code
void *buf = malloc(size);
@header{wx/scopeguard.h}
*/
+#define wxON_BLOCK_EXIT(function, ...)
#define wxON_BLOCK_EXIT0(function)
#define wxON_BLOCK_EXIT1(function, p1)
#define wxON_BLOCK_EXIT2(function, p1, p2)
+#define wxON_BLOCK_EXIT3(function, p1, p2, p3)
//@}
-/** @ingroup group_funcmacro_misc */
+/** @addtogroup group_funcmacro_misc */
//@{
/**
- This family of macros is similar to wxON_BLOCK_EXIT0(), but calls a method
+ This family of macros is similar to wxON_BLOCK_EXIT(), but calls a method
of the given object instead of a free function.
@header{wx/scopeguard.h}
*/
+#define wxON_BLOCK_EXIT_OBJ(object, method, ...)
#define wxON_BLOCK_EXIT_OBJ0(object, method)
#define wxON_BLOCK_EXIT_OBJ1(object, method, p1)
#define wxON_BLOCK_EXIT_OBJ2(object, method, p1, p2)
+#define wxON_BLOCK_EXIT_OBJ3(object, method, p1, p2, p3)
//@}
-/** @ingroup group_funcmacro_misc */
+/** @addtogroup group_funcmacro_misc */
//@{
/**
- This family of macros is similar to wxON_BLOCK_OBJ0(), but calls a method
+ This family of macros is similar to wxON_BLOCK_OBJ(), but calls a method
of @c this object instead of a method of the specified object.
@header{wx/scopeguard.h}
*/
+#define wxON_BLOCK_EXIT_THIS(method, ...)
#define wxON_BLOCK_EXIT_THIS0(method)
#define wxON_BLOCK_EXIT_THIS1(method, p1)
#define wxON_BLOCK_EXIT_THIS2(method, p1, p2)
+#define wxON_BLOCK_EXIT_THIS3(method, p1, p2, p3)
//@}
-/** @ingroup group_funcmacro_misc */
+/** @addtogroup group_funcmacro_misc */
//@{
/**
This macro sets a variable to the specified value on scope exit.
}
@endcode
+ Notice that @a value is copied, i.e. stored by value, so it can be a
+ temporary object returned by a function call, for example.
+
@see wxON_BLOCK_EXIT_OBJ0(), wxON_BLOCK_EXIT_NULL()
@header{wx/scopeguard.h}