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