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