diff options
author | Lorry Tar Creator <lorry-tar-importer@baserock.org> | 2013-12-11 22:24:18 +0000 |
---|---|---|
committer | <> | 2014-07-24 09:30:59 +0000 |
commit | 59e2936f588aa945e8dcd6c737523c299067e9d0 (patch) | |
tree | 97e74980cc54baa19de5faa11f5a50a0121a48ea /mfbt/Scoped.h | |
download | mozjs24-59e2936f588aa945e8dcd6c737523c299067e9d0.tar.gz |
Imported from /home/lorry/working-area/delta_mozilla_mozjs24/mozjs-24.2.0.tar.bz2.HEADmozjs-24.2.0master
Diffstat (limited to 'mfbt/Scoped.h')
-rw-r--r-- | mfbt/Scoped.h | 271 |
1 files changed, 271 insertions, 0 deletions
diff --git a/mfbt/Scoped.h b/mfbt/Scoped.h new file mode 100644 index 0000000..677a1a3 --- /dev/null +++ b/mfbt/Scoped.h @@ -0,0 +1,271 @@ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this file, + * You can obtain one at http://mozilla.org/MPL/2.0/. */ + +/* A number of structures to simplify scope-based RAII management. */ + +#ifndef mozilla_Scoped_h_ +#define mozilla_Scoped_h_ + +/* + * Resource Acquisition Is Initialization is a programming idiom used + * to write robust code that is able to deallocate resources properly, + * even in presence of execution errors or exceptions that need to be + * propagated. The Scoped* classes defined in this header perform the + * deallocation of the resource they hold once program execution + * reaches the end of the scope for which they have been defined. + * + * This header provides the following RAII classes: + * + * - |ScopedFreePtr| - a container for a pointer, that automatically calls + * |free()| at the end of the scope; + * - |ScopedDeletePtr| - a container for a pointer, that automatically calls + * |delete| at the end of the scope; + * - |ScopedDeleteArray| - a container for a pointer to an array, that + * automatically calls |delete[]| at the end of the scope. + * + * The general scenario for each of the RAII classes is the following: + * + * ScopedClass foo(create_value()); + * // ... In this scope, |foo| is defined. Use |foo.get()| or |foo.rwget()| + * to access the value. + * // ... In case of |return| or |throw|, |foo| is deallocated automatically. + * // ... If |foo| needs to be returned or stored, use |foo.forget()| + * + * Note that the RAII classes defined in this header do _not_ perform any form + * of reference-counting or garbage-collection. These classes have exactly two + * behaviors: + * + * - if |forget()| has not been called, the resource is always deallocated at + * the end of the scope; + * - if |forget()| has been called, any control on the resource is unbound + * and the resource is not deallocated by the class. + * + * Extension: + * + * In addition, this header provides class |Scoped| and macros |SCOPED_TEMPLATE| + * and |MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE| to simplify the definition + * of RAII classes for other scenarios. These macros have been used to + * automatically close file descriptors/file handles when reaching the end of + * the scope, graphics contexts, etc. + */ + +#include "mozilla/Attributes.h" +#include "mozilla/GuardObjects.h" + +namespace mozilla { + +/* + * Scoped is a helper to create RAII wrappers + * Type argument |Traits| is expected to have the following structure: + * + * struct Traits { + * // Define the type of the value stored in the wrapper + * typedef value_type type; + * // Returns the value corresponding to the uninitialized or freed state + * const static type empty(); + * // Release resources corresponding to the wrapped value + * // This function is responsible for not releasing an |empty| value + * const static void release(type); + * } + */ +template<typename Traits> +class Scoped +{ + public: + typedef typename Traits::type Resource; + + explicit Scoped(MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM) + : value(Traits::empty()) + { + MOZ_GUARD_OBJECT_NOTIFIER_INIT; + } + explicit Scoped(const Resource& v + MOZ_GUARD_OBJECT_NOTIFIER_PARAM) + : value(v) + { + MOZ_GUARD_OBJECT_NOTIFIER_INIT; + } + ~Scoped() { + Traits::release(value); + } + + // Constant getter + operator const Resource&() const { return value; } + const Resource& operator->() const { return value; } + const Resource& get() const { return value; } + // Non-constant getter. + Resource& rwget() { return value; } + + /* + * Forget the resource. + * + * Once |forget| has been called, the |Scoped| is neutralized, i.e. it will + * have no effect at destruction (unless it is reset to another resource by + * |operator=|). + * + * @return The original resource. + */ + Resource forget() { + Resource tmp = value; + value = Traits::empty(); + return tmp; + } + + /* + * Perform immediate clean-up of this |Scoped|. + * + * If this |Scoped| is currently empty, this method has no effect. + */ + void dispose() { + Traits::release(value); + value = Traits::empty(); + } + + bool operator==(const Resource& other) const { + return value == other; + } + + /* + * Replace the resource with another resource. + * + * Calling |operator=| has the side-effect of triggering clean-up. If you do + * not want to trigger clean-up, you should first invoke |forget|. + * + * @return this + */ + Scoped<Traits>& operator=(const Resource& other) { + return reset(other); + } + Scoped<Traits>& reset(const Resource& other) { + Traits::release(value); + value = other; + return *this; + } + + private: + explicit Scoped(const Scoped<Traits>& value) MOZ_DELETE; + Scoped<Traits>& operator=(const Scoped<Traits>& value) MOZ_DELETE; + + private: + Resource value; + MOZ_DECL_USE_GUARD_OBJECT_NOTIFIER +}; + +/* + * SCOPED_TEMPLATE defines a templated class derived from Scoped + * This allows to implement templates such as ScopedFreePtr. + * + * @param name The name of the class to define. + * @param Traits A struct implementing clean-up. See the implementations + * for more details. + */ +#define SCOPED_TEMPLATE(name, Traits) \ +template<typename Type> \ +struct name : public mozilla::Scoped<Traits<Type> > \ +{ \ + typedef mozilla::Scoped<Traits<Type> > Super; \ + typedef typename Super::Resource Resource; \ + name& operator=(Resource ptr) { \ + Super::operator=(ptr); \ + return *this; \ + } \ + explicit name(MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM) \ + : Super(MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM_TO_PARENT) \ + {} \ + explicit name(Resource ptr \ + MOZ_GUARD_OBJECT_NOTIFIER_PARAM) \ + : Super(ptr MOZ_GUARD_OBJECT_NOTIFIER_PARAM_TO_PARENT) \ + {} \ + private: \ + explicit name(name& source) MOZ_DELETE; \ + name& operator=(name& source) MOZ_DELETE; \ +}; + +/* + * ScopedFreePtr is a RAII wrapper for pointers that need to be free()d. + * + * struct S { ... }; + * ScopedFreePtr<S> foo = malloc(sizeof(S)); + * ScopedFreePtr<char> bar = strdup(str); + */ +template<typename T> +struct ScopedFreePtrTraits +{ + typedef T* type; + static T* empty() { return NULL; } + static void release(T* ptr) { free(ptr); } +}; +SCOPED_TEMPLATE(ScopedFreePtr, ScopedFreePtrTraits) + +/* + * ScopedDeletePtr is a RAII wrapper for pointers that need to be deleted. + * + * struct S { ... }; + * ScopedDeletePtr<S> foo = new S(); + */ +template<typename T> +struct ScopedDeletePtrTraits : public ScopedFreePtrTraits<T> +{ + static void release(T* ptr) { delete ptr; } +}; +SCOPED_TEMPLATE(ScopedDeletePtr, ScopedDeletePtrTraits) + +/* + * ScopedDeleteArray is a RAII wrapper for pointers that need to be delete[]ed. + * + * struct S { ... }; + * ScopedDeleteArray<S> foo = new S[42]; + */ +template<typename T> +struct ScopedDeleteArrayTraits : public ScopedFreePtrTraits<T> +{ + static void release(T* ptr) { delete [] ptr; } +}; +SCOPED_TEMPLATE(ScopedDeleteArray, ScopedDeleteArrayTraits) + +/* + * MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE makes it easy to create scoped + * pointers for types with custom deleters; just overload + * TypeSpecificDelete(T*) in the same namespace as T to call the deleter for + * type T. + * + * @param name The name of the class to define. + * @param Type A struct implementing clean-up. See the implementations + * for more details. + * *param Deleter The function that is used to delete/destroy/free a + * non-null value of Type*. + * + * Example: + * + * MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE(ScopedPRFileDesc, PRFileDesc, \ + * PR_Close) + * ... + * { + * ScopedPRFileDesc file(PR_OpenFile(...)); + * ... + * } // file is closed with PR_Close here + */ +#define MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE(name, Type, Deleter) \ +template <> inline void TypeSpecificDelete(Type * value) { Deleter(value); } \ +typedef ::mozilla::TypeSpecificScopedPointer<Type> name; + +template <typename T> void TypeSpecificDelete(T * value); + +template <typename T> +struct TypeSpecificScopedPointerTraits +{ + typedef T* type; + const static type empty() { return NULL; } + const static void release(type value) + { + if (value) + TypeSpecificDelete(value); + } +}; + +SCOPED_TEMPLATE(TypeSpecificScopedPointer, TypeSpecificScopedPointerTraits) + +} /* namespace mozilla */ + +#endif // mozilla_Scoped_h_ |