mfbt/Scoped.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 /* DEPRECATED: Use UniquePtr.h instead. */
   8
   9 #ifndef mozilla_Scoped_h
  10 #define mozilla_Scoped_h
  11
  12 /*
  13  * DEPRECATED: Use UniquePtr.h instead.
  14  *
  15  * Resource Acquisition Is Initialization is a programming idiom used
  16  * to write robust code that is able to deallocate resources properly,
  17  * even in presence of execution errors or exceptions that need to be
  18  * propagated.  The Scoped* classes defined via the |SCOPED_TEMPLATE|
  19  * and |MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLTE| macros perform the
  20  * deallocation of the resource they hold once program execution
  21  * reaches the end of the scope for which they have been defined.
  22  * These macros have been used to automatically close file
  23  * descriptors/file handles when reaching the end of the scope,
  24  * graphics contexts, etc.
  25  *
  26  * The general scenario for RAII classes created by the above macros
  27  * is the following:
  28  *
  29  * ScopedClass foo(create_value());
  30  * // ... In this scope, |foo| is defined. Use |foo.get()| or |foo.rwget()|
  31  *        to access the value.
  32  * // ... In case of |return| or |throw|, |foo| is deallocated automatically.
  33  * // ... If |foo| needs to be returned or stored, use |foo.forget()|
  34  *
  35  * Note that the RAII classes defined in this header do _not_ perform any form
  36  * of reference-counting or garbage-collection. These classes have exactly two
  37  * behaviors:
  38  *
  39  * - if |forget()| has not been called, the resource is always deallocated at
  40  *   the end of the scope;
  41  * - if |forget()| has been called, any control on the resource is unbound
  42  *   and the resource is not deallocated by the class.
  43  */
  44
  45 #include <utility>
  46
  47 #include "mozilla/Assertions.h"
  48 #include "mozilla/Attributes.h"
  49 #include "mozilla/GuardObjects.h"
  50
  51 namespace mozilla {
  52
  53 /*
  54  * Scoped is a helper to create RAII wrappers
  55  * Type argument |Traits| is expected to have the following structure:
  56  *
  57  *   struct Traits
  58  *   {
  59  *     // Define the type of the value stored in the wrapper
  60  *     typedef value_type type;
  61  *     // Returns the value corresponding to the uninitialized or freed state
  62  *     const static type empty();
  63  *     // Release resources corresponding to the wrapped value
  64  *     // This function is responsible for not releasing an |empty| value
  65  *     const static void release(type);
  66  *   }
  67  */
  68 template <typename Traits>
  69 class MOZ_NON_TEMPORARY_CLASS Scoped {
  70  public:
  71   typedef typename Traits::type Resource;
  72
  73   explicit Scoped(MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM)
  74       : mValue(Traits::empty()) {
  75     MOZ_GUARD_OBJECT_NOTIFIER_INIT;
  76   }
  77
  78   explicit Scoped(const Resource& aValue MOZ_GUARD_OBJECT_NOTIFIER_PARAM)
  79       : mValue(aValue) {
  80     MOZ_GUARD_OBJECT_NOTIFIER_INIT;
  81   }
  82
  83   /* Move constructor. */
  84   Scoped(Scoped&& aOther MOZ_GUARD_OBJECT_NOTIFIER_PARAM)
  85       : mValue(std::move(aOther.mValue)) {
  86     MOZ_GUARD_OBJECT_NOTIFIER_INIT;
  87     aOther.mValue = Traits::empty();
  88   }
  89
  90   ~Scoped() { Traits::release(mValue); }
  91
  92   // Constant getter
  93   operator const Resource&() const { return mValue; }
  94   const Resource& operator->() const { return mValue; }
  95   const Resource& get() const { return mValue; }
  96   // Non-constant getter.
  97   Resource& rwget() { return mValue; }
  98
  99   /*
 100    * Forget the resource.
 101    *
 102    * Once |forget| has been called, the |Scoped| is neutralized, i.e. it will
 103    * have no effect at destruction (unless it is reset to another resource by
 104    * |operator=|).
 105    *
 106    * @return The original resource.
 107    */
 108   Resource forget() {
 109     Resource tmp = mValue;
 110     mValue = Traits::empty();
 111     return tmp;
 112   }
 113
 114   /*
 115    * Perform immediate clean-up of this |Scoped|.
 116    *
 117    * If this |Scoped| is currently empty, this method has no effect.
 118    */
 119   void dispose() {
 120     Traits::release(mValue);
 121     mValue = Traits::empty();
 122   }
 123
 124   bool operator==(const Resource& aOther) const { return mValue == aOther; }
 125
 126   /*
 127    * Replace the resource with another resource.
 128    *
 129    * Calling |operator=| has the side-effect of triggering clean-up. If you do
 130    * not want to trigger clean-up, you should first invoke |forget|.
 131    *
 132    * @return this
 133    */
 134   Scoped& operator=(const Resource& aOther) { return reset(aOther); }
 135
 136   Scoped& reset(const Resource& aOther) {
 137     Traits::release(mValue);
 138     mValue = aOther;
 139     return *this;
 140   }
 141
 142   /* Move assignment operator. */
 143   Scoped& operator=(Scoped&& aRhs) {
 144     MOZ_ASSERT(&aRhs != this, "self-move-assignment not allowed");
 145     this->~Scoped();
 146     new (this) Scoped(std::move(aRhs));
 147     return *this;
 148   }
 149
 150  private:
 151   explicit Scoped(const Scoped& aValue) = delete;
 152   Scoped& operator=(const Scoped& aValue) = delete;
 153
 154  private:
 155   Resource mValue;
 156   MOZ_DECL_USE_GUARD_OBJECT_NOTIFIER
 157 };
 158
 159 /*
 160  * SCOPED_TEMPLATE defines a templated class derived from Scoped
 161  * This allows to implement templates such as ScopedFreePtr.
 162  *
 163  * @param name The name of the class to define.
 164  * @param Traits A struct implementing clean-up. See the implementations
 165  * for more details.
 166  */
 167 #define SCOPED_TEMPLATE(name, Traits)                                         \
 168   template <typename Type>                                                    \
 169   struct MOZ_NON_TEMPORARY_CLASS name                                         \
 170       : public mozilla::Scoped<Traits<Type> > {                               \
 171     typedef mozilla::Scoped<Traits<Type> > Super;                             \
 172     typedef typename Super::Resource Resource;                                \
 173     name& operator=(Resource aRhs) {                                          \
 174       Super::operator=(aRhs);                                                 \
 175       return *this;                                                           \
 176     }                                                                         \
 177     name& operator=(name&& aRhs) = default;                                   \
 178                                                                               \
 179     explicit name(MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM)                       \
 180         : Super(MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM_TO_PARENT) {}            \
 181     explicit name(Resource aRhs MOZ_GUARD_OBJECT_NOTIFIER_PARAM)              \
 182         : Super(aRhs MOZ_GUARD_OBJECT_NOTIFIER_PARAM_TO_PARENT) {}            \
 183     name(name&& aRhs MOZ_GUARD_OBJECT_NOTIFIER_PARAM)                         \
 184         : Super(std::move(aRhs) MOZ_GUARD_OBJECT_NOTIFIER_PARAM_TO_PARENT) {} \
 185                                                                               \
 186    private:                                                                   \
 187     explicit name(const name&) = delete;                                      \
 188     name& operator=(const name&) = delete;                                    \
 189   };
 190
 191 /*
 192  * MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE makes it easy to create scoped
 193  * pointers for types with custom deleters; just overload
 194  * TypeSpecificDelete(T*) in the same namespace as T to call the deleter for
 195  * type T.
 196  *
 197  * @param name The name of the class to define.
 198  * @param Type A struct implementing clean-up. See the implementations
 199  * for more details.
 200  * *param Deleter The function that is used to delete/destroy/free a
 201  *        non-null value of Type*.
 202  *
 203  * Example:
 204  *
 205  *   MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE(ScopedPRFileDesc, PRFileDesc, \
 206  *                                             PR_Close)
 207  *   ...
 208  *   {
 209  *       ScopedPRFileDesc file(PR_OpenFile(...));
 210  *       ...
 211  *   } // file is closed with PR_Close here
 212  */
 213 #define MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE(name, Type, Deleter) \
 214   template <>                                                          \
 215   inline void TypeSpecificDelete(Type* aValue) {                       \
 216     Deleter(aValue);                                                   \
 217   }                                                                    \
 218   typedef ::mozilla::TypeSpecificScopedPointer<Type> name;
 219
 220 template <typename T>
 221 void TypeSpecificDelete(T* aValue);
 222
 223 template <typename T>
 224 struct TypeSpecificScopedPointerTraits {
 225   typedef T* type;
 226   static type empty() { return nullptr; }
 227   static void release(type aValue) {
 228     if (aValue) {
 229       TypeSpecificDelete(aValue);
 230     }
 231   }
 232 };
 233
 234 SCOPED_TEMPLATE(TypeSpecificScopedPointer, TypeSpecificScopedPointerTraits)
 235
 236 } /* namespace mozilla */
 237
 238 #endif /* mozilla_Scoped_h */