mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-12-05 03:54:35 +00:00
272 lines
8.9 KiB
C++
272 lines
8.9 KiB
C++
/* 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_
|