libcxx/include/__utility/exception_guard.h

   1 //===----------------------------------------------------------------------===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8
   9 #ifndef _LIBCPP___UTILITY_TRANSACTION_H
  10 #define _LIBCPP___UTILITY_TRANSACTION_H
  11
  12 #include <__assert>
  13 #include <__config>
  14 #include <__type_traits/is_nothrow_move_constructible.h>
  15 #include <__utility/exchange.h>
  16 #include <__utility/move.h>
  17
  18 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
  19 #  pragma GCC system_header
  20 #endif
  21
  22 _LIBCPP_PUSH_MACROS
  23 #include <__undef_macros>
  24
  25 _LIBCPP_BEGIN_NAMESPACE_STD
  26
  27 // __exception_guard is a helper class for writing code with the strong exception guarantee.
  28 //
  29 // When writing code that can throw an exception, one can store rollback instructions in an
  30 // exception guard so that if an exception is thrown at any point during the lifetime of the
  31 // exception guard, it will be rolled back automatically. When the exception guard is done, one
  32 // must mark it as being complete so it isn't rolled back when the exception guard is destroyed.
  33 //
  34 // Exception guards are not default constructible, they can't be copied or assigned to, but
  35 // they can be moved around for convenience.
  36 //
  37 // __exception_guard is a no-op in -fno-exceptions mode to produce better code-gen. This means
  38 // that we don't provide the strong exception guarantees. However, Clang doesn't generate cleanup
  39 // code with exceptions disabled, so even if we wanted to provide the strong exception guarantees
  40 // we couldn't. This is also only relevant for constructs with a stack of
  41 // -fexceptions > -fno-exceptions > -fexceptions code, since the exception can't be caught where
  42 // exceptions are disabled. While -fexceptions > -fno-exceptions is quite common
  43 // (e.g. libc++.dylib > -fno-exceptions), having another layer with exceptions enabled seems a lot
  44 // less common, especially one that tries to catch an exception through -fno-exceptions code.
  45 //
  46 // __exception_guard can help greatly simplify code that would normally be cluttered by
  47 // `#if _LIBCPP_HAS_NO_EXCEPTIONS`. For example:
  48 //
  49 //    template <class Iterator, class Size, class OutputIterator>
  50 //    Iterator uninitialized_copy_n(Iterator iter, Size n, OutputIterator out) {
  51 //        typedef typename iterator_traits<Iterator>::value_type value_type;
  52 //        __exception_guard guard([start=out, &out] {
  53 //            std::destroy(start, out);
  54 //        });
  55 //
  56 //        for (; n > 0; ++iter, ++out, --n) {
  57 //            ::new ((void*)std::addressof(*out)) value_type(*iter);
  58 //        }
  59 //        guard.__complete();
  60 //        return out;
  61 //    }
  62 //
  63
  64 template <class _Rollback>
  65 struct __exception_guard_exceptions {
  66   __exception_guard_exceptions() = delete;
  67
  68   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX20 explicit __exception_guard_exceptions(_Rollback __rollback)
  69       : __rollback_(std::move(__rollback)), __completed_(false) {}
  70
  71   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX20
  72   __exception_guard_exceptions(__exception_guard_exceptions&& __other)
  73       _NOEXCEPT_(is_nothrow_move_constructible<_Rollback>::value)
  74       : __rollback_(std::move(__other.__rollback_)), __completed_(__other.__completed_) {
  75     __other.__completed_ = true;
  76   }
  77
  78   __exception_guard_exceptions(__exception_guard_exceptions const&)            = delete;
  79   __exception_guard_exceptions& operator=(__exception_guard_exceptions const&) = delete;
  80   __exception_guard_exceptions& operator=(__exception_guard_exceptions&&)      = delete;
  81
  82   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX20 void __complete() _NOEXCEPT { __completed_ = true; }
  83
  84   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX20 ~__exception_guard_exceptions() {
  85     if (!__completed_)
  86       __rollback_();
  87   }
  88
  89 private:
  90   _Rollback __rollback_;
  91   bool __completed_;
  92 };
  93
  94 _LIBCPP_CTAD_SUPPORTED_FOR_TYPE(__exception_guard_exceptions);
  95
  96 template <class _Rollback>
  97 struct __exception_guard_noexceptions {
  98   __exception_guard_noexceptions() = delete;
  99   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX20
 100       _LIBCPP_NODEBUG explicit __exception_guard_noexceptions(_Rollback) {}
 101
 102   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX20 _LIBCPP_NODEBUG
 103   __exception_guard_noexceptions(__exception_guard_noexceptions&& __other)
 104       _NOEXCEPT_(is_nothrow_move_constructible<_Rollback>::value)
 105       : __completed_(__other.__completed_) {
 106     __other.__completed_ = true;
 107   }
 108
 109   __exception_guard_noexceptions(__exception_guard_noexceptions const&)            = delete;
 110   __exception_guard_noexceptions& operator=(__exception_guard_noexceptions const&) = delete;
 111   __exception_guard_noexceptions& operator=(__exception_guard_noexceptions&&)      = delete;
 112
 113   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX20 _LIBCPP_NODEBUG void __complete() _NOEXCEPT {
 114     __completed_ = true;
 115   }
 116
 117   _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX20 _LIBCPP_NODEBUG ~__exception_guard_noexceptions() {
 118     _LIBCPP_ASSERT_UNCATEGORIZED(__completed_, "__exception_guard not completed with exceptions disabled");
 119   }
 120
 121 private:
 122   bool __completed_ = false;
 123 };
 124
 125 _LIBCPP_CTAD_SUPPORTED_FOR_TYPE(__exception_guard_noexceptions);
 126
 127 #ifdef _LIBCPP_HAS_NO_EXCEPTIONS
 128 template <class _Rollback>
 129 using __exception_guard = __exception_guard_noexceptions<_Rollback>;
 130 #else
 131 template <class _Rollback>
 132 using __exception_guard = __exception_guard_exceptions<_Rollback>;
 133 #endif
 134
 135 template <class _Rollback>
 136 _LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR __exception_guard<_Rollback> __make_exception_guard(_Rollback __rollback) {
 137   return __exception_guard<_Rollback>(std::move(__rollback));
 138 }
 139
 140 _LIBCPP_END_NAMESPACE_STD
 141
 142 _LIBCPP_POP_MACROS
 143
 144 #endif // _LIBCPP___UTILITY_TRANSACTION_H