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 "mozilla/Assertions.h"
  46 #include "mozilla/Attributes.h"
  47 #include "mozilla/GuardObjects.h"
  48 #include "mozilla/Move.h"
  49
  50 namespace mozilla {
  51
  52 /*
  53  * Scoped is a helper to create RAII wrappers
  54  * Type argument |Traits| is expected to have the following structure:
  55  *
  56  *   struct Traits
  57  *   {
  58  *     // Define the type of the value stored in the wrapper
  59  *     typedef value_type type;
  60  *     // Returns the value corresponding to the uninitialized or freed state
  61  *     const static type empty();
  62  *     // Release resources corresponding to the wrapped value
  63  *     // This function is responsible for not releasing an |empty| value
  64  *     const static void release(type);
  65  *   }
  66  */
  67 template <typename Traits>
  68 class MOZ_NON_TEMPORARY_CLASS Scoped {
  69  public:
  70   typedef typename Traits::type Resource;
  71
  72   explicit Scoped(MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM)
  73       : mValue(Traits::empty()) {
  74     MOZ_GUARD_OBJECT_NOTIFIER_INIT;
  75   }
  76
  77   explicit Scoped(const Resource& aValue MOZ_GUARD_OBJECT_NOTIFIER_PARAM)
  78       : mValue(aValue) {
  79     MOZ_GUARD_OBJECT_NOTIFIER_INIT;
  80   }
  81
  82   /* Move constructor. */
  83   Scoped(Scoped&& aOther MOZ_GUARD_OBJECT_NOTIFIER_PARAM)
  84       : mValue(std::move(aOther.mValue)) {
  85     MOZ_GUARD_OBJECT_NOTIFIER_INIT;
  86     aOther.mValue = Traits::empty();
  87   }
  88
  89   ~Scoped() { Traits::release(mValue); }
  90
  91   // Constant getter
  92   operator const Resource&() const { return mValue; }
  93   const Resource& operator->() const { return mValue; }
  94   const Resource& get() const { return mValue; }
  95   // Non-constant getter.
  96   Resource& rwget() { return mValue; }
  97
  98   /*
  99    * Forget the resource.
 100    *
 101    * Once |forget| has been called, the |Scoped| is neutralized, i.e. it will
 102    * have no effect at destruction (unless it is reset to another resource by
 103    * |operator=|).
 104    *
 105    * @return The original resource.
 106    */
 107   Resource forget() {
 108     Resource tmp = mValue;
 109     mValue = Traits::empty();
 110     return tmp;
 111   }
 112
 113   /*
 114    * Perform immediate clean-up of this |Scoped|.
 115    *
 116    * If this |Scoped| is currently empty, this method has no effect.
 117    */
 118   void dispose() {
 119     Traits::release(mValue);
 120     mValue = Traits::empty();
 121   }
 122
 123   bool operator==(const Resource& aOther) const { return mValue == aOther; }
 124
 125   /*
 126    * Replace the resource with another resource.
 127    *
 128    * Calling |operator=| has the side-effect of triggering clean-up. If you do
 129    * not want to trigger clean-up, you should first invoke |forget|.
 130    *
 131    * @return this
 132    */
 133   Scoped& operator=(const Resource& aOther) { return reset(aOther); }
 134
 135   Scoped& reset(const Resource& aOther) {
 136     Traits::release(mValue);
 137     mValue = aOther;
 138     return *this;
 139   }
 140
 141   /* Move assignment operator. */
 142   Scoped& operator=(Scoped&& aRhs) {
 143     MOZ_ASSERT(&aRhs != this, "self-move-assignment not allowed");
 144     this->~Scoped();
 145     new (this) Scoped(std::move(aRhs));
 146     return *this;
 147   }
 148
 149  private:
 150   explicit Scoped(const Scoped& aValue) = delete;
 151   Scoped& operator=(const Scoped& aValue) = delete;
 152
 153  private:
 154   Resource mValue;
 155   MOZ_DECL_USE_GUARD_OBJECT_NOTIFIER
 156 };
 157
 158 /*
 159  * SCOPED_TEMPLATE defines a templated class derived from Scoped
 160  * This allows to implement templates such as ScopedFreePtr.
 161  *
 162  * @param name The name of the class to define.
 163  * @param Traits A struct implementing clean-up. See the implementations
 164  * for more details.
 165  */
 166 #define SCOPED_TEMPLATE(name, Traits)                                         \
 167   template <typename Type>                                                    \
 168   struct MOZ_NON_TEMPORARY_CLASS name                                         \
 169       : public mozilla::Scoped<Traits<Type> > {                               \
 170     typedef mozilla::Scoped<Traits<Type> > Super;                             \
 171     typedef typename Super::Resource Resource;                                \
 172     name& operator=(Resource aRhs) {                                          \
 173       Super::operator=(aRhs);                                                 \
 174       return *this;                                                           \
 175     }                                                                         \
 176     name& operator=(name&& aRhs) {                                            \
 177       Super::operator=(std::move(aRhs));                                      \
 178       return *this;                                                           \
 179     }                                                                         \
 180     explicit name(MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM)                       \
 181         : Super(MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM_TO_PARENT) {}            \
 182     explicit name(Resource aRhs MOZ_GUARD_OBJECT_NOTIFIER_PARAM)              \
 183         : Super(aRhs MOZ_GUARD_OBJECT_NOTIFIER_PARAM_TO_PARENT) {}            \
 184     name(name&& aRhs MOZ_GUARD_OBJECT_NOTIFIER_PARAM)                         \
 185         : Super(std::move(aRhs) MOZ_GUARD_OBJECT_NOTIFIER_PARAM_TO_PARENT) {} \
 186                                                                               \
 187    private:                                                                   \
 188     explicit name(name&) = delete;                                            \
 189     name& operator=(name&) = delete;                                          \
 190   };
 191
 192 /*
 193  * MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE makes it easy to create scoped
 194  * pointers for types with custom deleters; just overload
 195  * TypeSpecificDelete(T*) in the same namespace as T to call the deleter for
 196  * type T.
 197  *
 198  * @param name The name of the class to define.
 199  * @param Type A struct implementing clean-up. See the implementations
 200  * for more details.
 201  * *param Deleter The function that is used to delete/destroy/free a
 202  *        non-null value of Type*.
 203  *
 204  * Example:
 205  *
 206  *   MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE(ScopedPRFileDesc, PRFileDesc, \
 207  *                                             PR_Close)
 208  *   ...
 209  *   {
 210  *       ScopedPRFileDesc file(PR_OpenFile(...));
 211  *       ...
 212  *   } // file is closed with PR_Close here
 213  */
 214 #define MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE(name, Type, Deleter) \
 215   template <>                                                          \
 216   inline void TypeSpecificDelete(Type* aValue) {                       \
 217     Deleter(aValue);                                                   \
 218   }                                                                    \
 219   typedef ::mozilla::TypeSpecificScopedPointer<Type> name;
 220
 221 template <typename T>
 222 void TypeSpecificDelete(T* aValue);
 223
 224 template <typename T>
 225 struct TypeSpecificScopedPointerTraits {
 226   typedef T* type;
 227   static type empty() { return nullptr; }
 228   static void release(type aValue) {
 229     if (aValue) {
 230       TypeSpecificDelete(aValue);
 231     }
 232   }
 233 };
 234
 235 SCOPED_TEMPLATE(TypeSpecificScopedPointer, TypeSpecificScopedPointerTraits)
 236
 237 } /* namespace mozilla */
 238
 239 #endif /* mozilla_Scoped_h */