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 in this header perform the
  19  * deallocation of the resource they hold once program execution
  20  * reaches the end of the scope for which they have been defined.
  21  *
  22  * This header provides the following RAII classes:
  23  *
  24  * - |ScopedFreePtr| - a container for a pointer, that automatically calls
  25  *   |free()| at the end of the scope;
  26  * - |ScopedDeletePtr| - a container for a pointer, that automatically calls
  27  *   |delete| at the end of the scope;
  28  *
  29  * |ScopedDeleteArray| is removed in favor of |UniquePtr<T[]>|.
  30  *
  31  * The general scenario for each of the RAII classes is the following:
  32  *
  33  * ScopedClass foo(create_value());
  34  * // ... In this scope, |foo| is defined. Use |foo.get()| or |foo.rwget()|
  35  *        to access the value.
  36  * // ... In case of |return| or |throw|, |foo| is deallocated automatically.
  37  * // ... If |foo| needs to be returned or stored, use |foo.forget()|
  38  *
  39  * Note that the RAII classes defined in this header do _not_ perform any form
  40  * of reference-counting or garbage-collection. These classes have exactly two
  41  * behaviors:
  42  *
  43  * - if |forget()| has not been called, the resource is always deallocated at
  44  *   the end of the scope;
  45  * - if |forget()| has been called, any control on the resource is unbound
  46  *   and the resource is not deallocated by the class.
  47  *
  48  * Extension:
  49  *
  50  * In addition, this header provides class |Scoped| and macros |SCOPED_TEMPLATE|
  51  * and |MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE|  to simplify the definition
  52  * of RAII classes for other scenarios. These macros have been used to
  53  * automatically close file descriptors/file handles when reaching the end of
  54  * the scope, graphics contexts, etc.
  55  */
  56
  57 #include "mozilla/Assertions.h"
  58 #include "mozilla/Attributes.h"
  59 #include "mozilla/GuardObjects.h"
  60 #include "mozilla/Move.h"
  61 #include "mozilla/NullPtr.h"
  62
  63 namespace mozilla {
  64
  65 /*
  66  * Scoped is a helper to create RAII wrappers
  67  * Type argument |Traits| is expected to have the following structure:
  68  *
  69  *   struct Traits
  70  *   {
  71  *     // Define the type of the value stored in the wrapper
  72  *     typedef value_type type;
  73  *     // Returns the value corresponding to the uninitialized or freed state
  74  *     const static type empty();
  75  *     // Release resources corresponding to the wrapped value
  76  *     // This function is responsible for not releasing an |empty| value
  77  *     const static void release(type);
  78  *   }
  79  */
  80 template<typename Traits>
  81 class Scoped
  82 {
  83 public:
  84   typedef typename Traits::type Resource;
  85
  86   explicit Scoped(MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM)
  87     : mValue(Traits::empty())
  88   {
  89     MOZ_GUARD_OBJECT_NOTIFIER_INIT;
  90   }
  91
  92   explicit Scoped(const Resource& aValue
  93                   MOZ_GUARD_OBJECT_NOTIFIER_PARAM)
  94     : mValue(aValue)
  95   {
  96     MOZ_GUARD_OBJECT_NOTIFIER_INIT;
  97   }
  98
  99   /* Move constructor. */
 100   explicit Scoped(Scoped&& aOther
 101                   MOZ_GUARD_OBJECT_NOTIFIER_PARAM)
 102     : mValue(Move(aOther.mValue))
 103   {
 104     MOZ_GUARD_OBJECT_NOTIFIER_INIT;
 105     aOther.mValue = Traits::empty();
 106   }
 107
 108   ~Scoped() { Traits::release(mValue); }
 109
 110   // Constant getter
 111   operator const Resource&() const { return mValue; }
 112   const Resource& operator->() const { return mValue; }
 113   const Resource& get() const { return mValue; }
 114   // Non-constant getter.
 115   Resource& rwget() { return mValue; }
 116
 117   /*
 118    * Forget the resource.
 119    *
 120    * Once |forget| has been called, the |Scoped| is neutralized, i.e. it will
 121    * have no effect at destruction (unless it is reset to another resource by
 122    * |operator=|).
 123    *
 124    * @return The original resource.
 125    */
 126   Resource forget()
 127   {
 128     Resource tmp = mValue;
 129     mValue = Traits::empty();
 130     return tmp;
 131   }
 132
 133   /*
 134    * Perform immediate clean-up of this |Scoped|.
 135    *
 136    * If this |Scoped| is currently empty, this method has no effect.
 137    */
 138   void dispose()
 139   {
 140     Traits::release(mValue);
 141     mValue = Traits::empty();
 142   }
 143
 144   bool operator==(const Resource& aOther) const { return mValue == aOther; }
 145
 146   /*
 147    * Replace the resource with another resource.
 148    *
 149    * Calling |operator=| has the side-effect of triggering clean-up. If you do
 150    * not want to trigger clean-up, you should first invoke |forget|.
 151    *
 152    * @return this
 153    */
 154   Scoped& operator=(const Resource& aOther) { return reset(aOther); }
 155
 156   Scoped& reset(const Resource& aOther)
 157   {
 158     Traits::release(mValue);
 159     mValue = aOther;
 160     return *this;
 161   }
 162
 163   /* Move assignment operator. */
 164   Scoped& operator=(Scoped&& aRhs)
 165   {
 166     MOZ_ASSERT(&aRhs != this, "self-move-assignment not allowed");
 167     this->~Scoped();
 168     new(this) Scoped(Move(aRhs));
 169     return *this;
 170   }
 171
 172 private:
 173   explicit Scoped(const Scoped& aValue) MOZ_DELETE;
 174   Scoped& operator=(const Scoped& aValue) MOZ_DELETE;
 175
 176 private:
 177   Resource mValue;
 178   MOZ_DECL_USE_GUARD_OBJECT_NOTIFIER
 179 };
 180
 181 /*
 182  * SCOPED_TEMPLATE defines a templated class derived from Scoped
 183  * This allows to implement templates such as ScopedFreePtr.
 184  *
 185  * @param name The name of the class to define.
 186  * @param Traits A struct implementing clean-up. See the implementations
 187  * for more details.
 188  */
 189 #define SCOPED_TEMPLATE(name, Traits)                                         \
 190 template<typename Type>                                                       \
 191 struct name : public mozilla::Scoped<Traits<Type> >                           \
 192 {                                                                             \
 193   typedef mozilla::Scoped<Traits<Type> > Super;                               \
 194   typedef typename Super::Resource Resource;                                  \
 195   name& operator=(Resource aRhs)                                              \
 196   {                                                                           \
 197     Super::operator=(aRhs);                                                   \
 198     return *this;                                                             \
 199   }                                                                           \
 200   name& operator=(name&& aRhs)                                                \
 201   {                                                                           \
 202     Super::operator=(Move(aRhs));                                             \
 203     return *this;                                                             \
 204   }                                                                           \
 205   explicit name(MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM)                         \
 206     : Super(MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM_TO_PARENT)                   \
 207   {}                                                                          \
 208   explicit name(Resource aRhs                                                 \
 209                 MOZ_GUARD_OBJECT_NOTIFIER_PARAM)                              \
 210     : Super(aRhs                                                              \
 211             MOZ_GUARD_OBJECT_NOTIFIER_PARAM_TO_PARENT)                        \
 212   {}                                                                          \
 213   explicit name(name&& aRhs                                                   \
 214                 MOZ_GUARD_OBJECT_NOTIFIER_PARAM)                              \
 215     : Super(Move(aRhs)                                                        \
 216             MOZ_GUARD_OBJECT_NOTIFIER_PARAM_TO_PARENT)                        \
 217   {}                                                                          \
 218 private:                                                                      \
 219   explicit name(name&) MOZ_DELETE;                                            \
 220   name& operator=(name&) MOZ_DELETE;                                          \
 221 };
 222
 223 /*
 224  * ScopedFreePtr is a RAII wrapper for pointers that need to be free()d.
 225  *
 226  *   struct S { ... };
 227  *   ScopedFreePtr<S> foo = malloc(sizeof(S));
 228  *   ScopedFreePtr<char> bar = strdup(str);
 229  */
 230 template<typename T>
 231 struct ScopedFreePtrTraits
 232 {
 233   typedef T* type;
 234   static T* empty() { return nullptr; }
 235   static void release(T* aPtr) { free(aPtr); }
 236 };
 237 SCOPED_TEMPLATE(ScopedFreePtr, ScopedFreePtrTraits)
 238
 239 /*
 240  * ScopedDeletePtr is a RAII wrapper for pointers that need to be deleted.
 241  *
 242  *   struct S { ... };
 243  *   ScopedDeletePtr<S> foo = new S();
 244  */
 245 template<typename T>
 246 struct ScopedDeletePtrTraits : public ScopedFreePtrTraits<T>
 247 {
 248   static void release(T* aPtr) { delete aPtr; }
 249 };
 250 SCOPED_TEMPLATE(ScopedDeletePtr, ScopedDeletePtrTraits)
 251
 252 /*
 253  * MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE makes it easy to create scoped
 254  * pointers for types with custom deleters; just overload
 255  * TypeSpecificDelete(T*) in the same namespace as T to call the deleter for
 256  * type T.
 257  *
 258  * @param name The name of the class to define.
 259  * @param Type A struct implementing clean-up. See the implementations
 260  * for more details.
 261  * *param Deleter The function that is used to delete/destroy/free a
 262  *        non-null value of Type*.
 263  *
 264  * Example:
 265  *
 266  *   MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE(ScopedPRFileDesc, PRFileDesc, \
 267  *                                             PR_Close)
 268  *   ...
 269  *   {
 270  *       ScopedPRFileDesc file(PR_OpenFile(...));
 271  *       ...
 272  *   } // file is closed with PR_Close here
 273  */
 274 #define MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE(name, Type, Deleter) \
 275 template <> inline void TypeSpecificDelete(Type* aValue) { Deleter(aValue); } \
 276 typedef ::mozilla::TypeSpecificScopedPointer<Type> name;
 277
 278 template <typename T> void TypeSpecificDelete(T* aValue);
 279
 280 template <typename T>
 281 struct TypeSpecificScopedPointerTraits
 282 {
 283   typedef T* type;
 284   static type empty() { return nullptr; }
 285   static void release(type aValue)
 286   {
 287     if (aValue) {
 288       TypeSpecificDelete(aValue);
 289     }
 290   }
 291 };
 292
 293 SCOPED_TEMPLATE(TypeSpecificScopedPointer, TypeSpecificScopedPointerTraits)
 294
 295 } /* namespace mozilla */
 296
 297 #endif /* mozilla_Scoped_h */