mfbt/Scoped.h

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   3  * You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 /* A number of structures to simplify scope-based RAII management. */
   6
   7 #ifndef mozilla_Scoped_h_
   8 #define mozilla_Scoped_h_
   9
  10 /*
  11  * Resource Acquisition Is Initialization is a programming idiom used
  12  * to write robust code that is able to deallocate resources properly,
  13  * even in presence of execution errors or exceptions that need to be
  14  * propagated.  The Scoped* classes defined in this header perform the
  15  * deallocation of the resource they hold once program execution
  16  * reaches the end of the scope for which they have been defined.
  17  *
  18  * This header provides the following RAII classes:
  19  *
  20  * - |ScopedFreePtr| - a container for a pointer, that automatically calls
  21  *   |free()| at the end of the scope;
  22  * - |ScopedDeletePtr| - a container for a pointer, that automatically calls
  23  *   |delete| at the end of the scope;
  24  * - |ScopedDeleteArray| - a container for a pointer to an array, that
  25  *   automatically calls |delete[]| at the end of the scope.
  26  *
  27  * The general scenario for each of the RAII classes 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  * Extension:
  45  *
  46  * In addition, this header provides class |Scoped| and macros |SCOPED_TEMPLATE|
  47  * and |MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE|  to simplify the definition
  48  * of RAII classes for other scenarios. These macros have been used to
  49  * automatically close file descriptors/file handles when reaching the end of
  50  * the scope, graphics contexts, etc.
  51  */
  52
  53 #include "mozilla/Attributes.h"
  54 #include "mozilla/GuardObjects.h"
  55
  56 namespace mozilla {
  57
  58 /*
  59  * Scoped is a helper to create RAII wrappers
  60  * Type argument |Traits| is expected to have the following structure:
  61  *
  62  *   struct Traits {
  63  *     // Define the type of the value stored in the wrapper
  64  *     typedef value_type type;
  65  *     // Returns the value corresponding to the uninitialized or freed state
  66  *     const static type empty();
  67  *     // Release resources corresponding to the wrapped value
  68  *     // This function is responsible for not releasing an |empty| value
  69  *     const static void release(type);
  70  *   }
  71  */
  72 template<typename Traits>
  73 class Scoped
  74 {
  75   public:
  76     typedef typename Traits::type Resource;
  77
  78     explicit Scoped(MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM)
  79       : value(Traits::empty())
  80     {
  81       MOZ_GUARD_OBJECT_NOTIFIER_INIT;
  82     }
  83     explicit Scoped(const Resource& v
  84                     MOZ_GUARD_OBJECT_NOTIFIER_PARAM)
  85       : value(v)
  86     {
  87       MOZ_GUARD_OBJECT_NOTIFIER_INIT;
  88     }
  89     ~Scoped() {
  90       Traits::release(value);
  91     }
  92
  93     // Constant getter
  94     operator const Resource&() const { return value; }
  95     const Resource& operator->() const { return value; }
  96     const Resource& get() const { return value; }
  97     // Non-constant getter.
  98     Resource& rwget() { return value; }
  99
 100     /*
 101      * Forget the resource.
 102      *
 103      * Once |forget| has been called, the |Scoped| is neutralized, i.e. it will
 104      * have no effect at destruction (unless it is reset to another resource by
 105      * |operator=|).
 106      *
 107      * @return The original resource.
 108      */
 109     Resource forget() {
 110       Resource tmp = value;
 111       value = Traits::empty();
 112       return tmp;
 113     }
 114
 115     /*
 116      * Perform immediate clean-up of this |Scoped|.
 117      *
 118      * If this |Scoped| is currently empty, this method has no effect.
 119      */
 120     void dispose() {
 121       Traits::release(value);
 122       value = Traits::empty();
 123     }
 124
 125     bool operator==(const Resource& other) const {
 126       return value == other;
 127     }
 128
 129     /*
 130      * Replace the resource with another resource.
 131      *
 132      * Calling |operator=| has the side-effect of triggering clean-up. If you do
 133      * not want to trigger clean-up, you should first invoke |forget|.
 134      *
 135      * @return this
 136      */
 137     Scoped<Traits>& operator=(const Resource& other) {
 138       return reset(other);
 139     }
 140     Scoped<Traits>& reset(const Resource& other) {
 141       Traits::release(value);
 142       value = other;
 143       return *this;
 144     }
 145
 146   private:
 147     explicit Scoped(const Scoped<Traits>& value) MOZ_DELETE;
 148     Scoped<Traits>& operator=(const Scoped<Traits>& value) MOZ_DELETE;
 149
 150   private:
 151     Resource value;
 152     MOZ_DECL_USE_GUARD_OBJECT_NOTIFIER
 153 };
 154
 155 /*
 156  * SCOPED_TEMPLATE defines a templated class derived from Scoped
 157  * This allows to implement templates such as ScopedFreePtr.
 158  *
 159  * @param name The name of the class to define.
 160  * @param Traits A struct implementing clean-up. See the implementations
 161  * for more details.
 162  */
 163 #define SCOPED_TEMPLATE(name, Traits)                          \
 164 template<typename Type>                                        \
 165 struct name : public mozilla::Scoped<Traits<Type> >            \
 166 {                                                              \
 167     typedef mozilla::Scoped<Traits<Type> > Super;              \
 168     typedef typename Super::Resource Resource;                 \
 169     name& operator=(Resource ptr) {                            \
 170       Super::operator=(ptr);                                   \
 171       return *this;                                            \
 172     }                                                          \
 173     explicit name(MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM)        \
 174       : Super(MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM_TO_PARENT)  \
 175     {}                                                         \
 176     explicit name(Resource ptr                                 \
 177                   MOZ_GUARD_OBJECT_NOTIFIER_PARAM)             \
 178       : Super(ptr MOZ_GUARD_OBJECT_NOTIFIER_PARAM_TO_PARENT)   \
 179     {}                                                         \
 180   private:                                                     \
 181     explicit name(name& source) MOZ_DELETE;                    \
 182     name& operator=(name& source) MOZ_DELETE;                  \
 183 };
 184
 185 /*
 186  * ScopedFreePtr is a RAII wrapper for pointers that need to be free()d.
 187  *
 188  *   struct S { ... };
 189  *   ScopedFreePtr<S> foo = malloc(sizeof(S));
 190  *   ScopedFreePtr<char> bar = strdup(str);
 191  */
 192 template<typename T>
 193 struct ScopedFreePtrTraits
 194 {
 195     typedef T* type;
 196     static T* empty() { return NULL; }
 197     static void release(T* ptr) { free(ptr); }
 198 };
 199 SCOPED_TEMPLATE(ScopedFreePtr, ScopedFreePtrTraits)
 200
 201 /*
 202  * ScopedDeletePtr is a RAII wrapper for pointers that need to be deleted.
 203  *
 204  *   struct S { ... };
 205  *   ScopedDeletePtr<S> foo = new S();
 206  */
 207 template<typename T>
 208 struct ScopedDeletePtrTraits : public ScopedFreePtrTraits<T>
 209 {
 210     static void release(T* ptr) { delete ptr; }
 211 };
 212 SCOPED_TEMPLATE(ScopedDeletePtr, ScopedDeletePtrTraits)
 213
 214 /*
 215  * ScopedDeleteArray is a RAII wrapper for pointers that need to be delete[]ed.
 216  *
 217  *   struct S { ... };
 218  *   ScopedDeleteArray<S> foo = new S[42];
 219  */
 220 template<typename T>
 221 struct ScopedDeleteArrayTraits : public ScopedFreePtrTraits<T>
 222 {
 223     static void release(T* ptr) { delete [] ptr; }
 224 };
 225 SCOPED_TEMPLATE(ScopedDeleteArray, ScopedDeleteArrayTraits)
 226
 227 /*
 228  * MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE makes it easy to create scoped
 229  * pointers for types with custom deleters; just overload
 230  * TypeSpecificDelete(T*) in the same namespace as T to call the deleter for
 231  * type T.
 232  *
 233  * @param name The name of the class to define.
 234  * @param Type A struct implementing clean-up. See the implementations
 235  * for more details.
 236  * *param Deleter The function that is used to delete/destroy/free a
 237  *        non-null value of Type*.
 238  *
 239  * Example:
 240  *
 241  *   MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE(ScopedPRFileDesc, PRFileDesc, \
 242  *                                             PR_Close)
 243  *   ...
 244  *   {
 245  *       ScopedPRFileDesc file(PR_OpenFile(...));
 246  *       ...
 247  *   } // file is closed with PR_Close here
 248  */
 249 #define MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE(name, Type, Deleter) \
 250 template <> inline void TypeSpecificDelete(Type * value) { Deleter(value); } \
 251 typedef ::mozilla::TypeSpecificScopedPointer<Type> name;
 252
 253 template <typename T> void TypeSpecificDelete(T * value);
 254
 255 template <typename T>
 256 struct TypeSpecificScopedPointerTraits
 257 {
 258     typedef T* type;
 259     const static type empty() { return NULL; }
 260     const static void release(type value)
 261     {
 262       if (value)
 263         TypeSpecificDelete(value);
 264     }
 265 };
 266
 267 SCOPED_TEMPLATE(TypeSpecificScopedPointer, TypeSpecificScopedPointerTraits)
 268
 269 } /* namespace mozilla */
 270
 271 #endif // mozilla_Scoped_h_