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