libraries/source/spidermonkey/include-win32-release/mozilla/GuardObjects.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 /* Implementation of macros to ensure correct use of RAII Auto* objects. */
   8
   9 #ifndef mozilla_GuardObjects_h
  10 #define mozilla_GuardObjects_h
  11
  12 #include "mozilla/Assertions.h"
  13 #include "mozilla/Types.h"
  14
  15 #include <utility>
  16
  17 #ifdef __cplusplus
  18
  19 #  ifdef DEBUG
  20
  21 /**
  22  * A custom define is used rather than |mozPoisonValue()| due to cascading
  23  * build failures relating to how mfbt is linked on different operating
  24  * systems. See bug 1160253.
  25  */
  26 #    define MOZ_POISON uintptr_t(-1)
  27
  28 namespace mozilla {
  29 namespace detail {
  30
  31 /*
  32  * The following classes are designed to cause assertions to detect
  33  * inadvertent use of guard objects as temporaries. In other words,
  34  * when we have a guard object whose only purpose is its constructor and
  35  * destructor (and is never otherwise referenced), the intended use
  36  * might be:
  37  *
  38  *   AutoRestore savePainting(mIsPainting);
  39  *
  40  * but is is easy to accidentally write:
  41  *
  42  *   AutoRestore(mIsPainting);
  43  *
  44  * which compiles just fine, but runs the destructor well before the
  45  * intended time.
  46  *
  47  * They work by adding (#ifdef DEBUG) an additional parameter to the
  48  * guard object's constructor, with a default value, so that users of
  49  * the guard object's API do not need to do anything. The default value
  50  * of this parameter is a temporary object. C++ (ISO/IEC 14882:1998),
  51  * section 12.2 [class.temporary], clauses 4 and 5 seem to assume a
  52  * guarantee that temporaries are destroyed in the reverse of their
  53  * construction order, but I actually can't find a statement that that
  54  * is true in the general case (beyond the two specific cases mentioned
  55  * there). However, it seems to be true.
  56  *
  57  * These classes are intended to be used only via the macros immediately
  58  * below them:
  59  *
  60  *   MOZ_DECL_USE_GUARD_OBJECT_NOTIFIER declares (ifdef DEBUG) a member
  61  *     variable, and should be put where a declaration of a private
  62  *     member variable would be placed.
  63  *   MOZ_GUARD_OBJECT_NOTIFIER_PARAM should be placed at the end of the
  64  *     parameters to each constructor of the guard object; it declares
  65  *     (ifdef DEBUG) an additional parameter. (But use the *_ONLY_PARAM
  66  *     variant for constructors that take no other parameters.)
  67  *   MOZ_GUARD_OBJECT_NOTIFIER_PARAM_IN_IMPL should likewise be used in
  68  *     the implementation of such constructors when they are not inline.
  69  *   MOZ_GUARD_OBJECT_NOTIFIER_PARAM_TO_PARENT should be used in
  70  *     the implementation of such constructors to pass the parameter to
  71  *     a base class that also uses these macros
  72  *   MOZ_GUARD_OBJECT_NOTIFIER_INIT is a statement that belongs in each
  73  *     constructor. It uses the parameter declared by
  74  *     MOZ_GUARD_OBJECT_NOTIFIER_PARAM.
  75  *
  76  * For more details, and examples of using these macros, see
  77  * https://developer.mozilla.org/en/Using_RAII_classes_in_Mozilla
  78  */
  79 class GuardObjectNotifier {
  80  private:
  81   bool* mStatementDone;
  82
  83  public:
  84   GuardObjectNotifier() : mStatementDone(reinterpret_cast<bool*>(MOZ_POISON)) {}
  85
  86   ~GuardObjectNotifier() {
  87     // Assert that the GuardObjectNotifier has been properly initialized by
  88     // using the |MOZ_GUARD_OBJECT_NOTIFIER_INIT| macro. A poison value is
  89     // used rather than a null check to appease static analyzers that were
  90     // (incorrectly) detecting null pointer dereferences.
  91     MOZ_ASSERT(mStatementDone != reinterpret_cast<bool*>(MOZ_POISON));
  92     *mStatementDone = true;
  93   }
  94
  95   void setStatementDone(bool* aStatementIsDone) {
  96     mStatementDone = aStatementIsDone;
  97   }
  98 };
  99
 100 class GuardObjectNotificationReceiver {
 101  private:
 102   bool mStatementDone;
 103
 104  public:
 105   GuardObjectNotificationReceiver() : mStatementDone(false) {}
 106
 107   ~GuardObjectNotificationReceiver() {
 108     /*
 109      * Assert that the guard object was not used as a temporary.  (Note that
 110      * this assert might also fire if init is not called because the guard
 111      * object's implementation is not using the above macros correctly.)
 112      */
 113     MOZ_ASSERT(mStatementDone,
 114                "Guard object should not be used as a temporary.");
 115   }
 116
 117   void init(GuardObjectNotifier& aNotifier) {
 118     aNotifier.setStatementDone(&mStatementDone);
 119   }
 120 };
 121
 122 } /* namespace detail */
 123 } /* namespace mozilla */
 124
 125 #    undef MOZ_POISON
 126
 127 #  endif /* DEBUG */
 128
 129 #  ifdef DEBUG
 130 #    define MOZ_DECL_USE_GUARD_OBJECT_NOTIFIER           \
 131       ::mozilla::detail::GuardObjectNotificationReceiver \
 132           _mCheckNotUsedAsTemporary;
 133 #    define MOZ_GUARD_OBJECT_NOTIFIER_PARAM                  \
 134       , ::mozilla::detail::GuardObjectNotifier&& _notifier = \
 135             ::mozilla::detail::GuardObjectNotifier()
 136 #    define MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM           \
 137       ::mozilla::detail::GuardObjectNotifier&& _notifier = \
 138           ::mozilla::detail::GuardObjectNotifier()
 139 #    define MOZ_GUARD_OBJECT_NOTIFIER_PARAM_IN_IMPL \
 140       , ::mozilla::detail::GuardObjectNotifier&& _notifier
 141 #    define MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM_IN_IMPL \
 142       ::mozilla::detail::GuardObjectNotifier&& _notifier
 143 #    define MOZ_GUARD_OBJECT_NOTIFIER_PARAM_TO_PARENT , ::std::move(_notifier)
 144 #    define MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM_TO_PARENT \
 145       ::std::move(_notifier)
 146 #    define MOZ_GUARD_OBJECT_NOTIFIER_INIT         \
 147       do {                                         \
 148         _mCheckNotUsedAsTemporary.init(_notifier); \
 149       } while (0)
 150 #  else
 151 #    define MOZ_DECL_USE_GUARD_OBJECT_NOTIFIER
 152 #    define MOZ_GUARD_OBJECT_NOTIFIER_PARAM
 153 #    define MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM
 154 #    define MOZ_GUARD_OBJECT_NOTIFIER_PARAM_IN_IMPL
 155 #    define MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM_IN_IMPL
 156 #    define MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM_TO_PARENT
 157 #    define MOZ_GUARD_OBJECT_NOTIFIER_PARAM_TO_PARENT
 158 #    define MOZ_GUARD_OBJECT_NOTIFIER_INIT \
 159       do {                                 \
 160       } while (0)
 161 #  endif
 162
 163 #endif /* __cplusplus */
 164
 165 #endif /* mozilla_GuardObjects_h */