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/. */
7 /* DEPRECATED: Use UniquePtr.h instead. */
9 #ifndef mozilla_Scoped_h
10 #define mozilla_Scoped_h
13 * DEPRECATED: Use UniquePtr.h instead.
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 via the |SCOPED_TEMPLATE|
19 * and |MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLTE| macros perform the
20 * deallocation of the resource they hold once program execution
21 * reaches the end of the scope for which they have been defined.
22 * These macros have been used to automatically close file
23 * descriptors/file handles when reaching the end of the scope,
24 * graphics contexts, etc.
26 * The general scenario for RAII classes created by the above macros
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()|
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
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.
47 #include "mozilla/Assertions.h"
48 #include "mozilla/Attributes.h"
49 #include "mozilla/GuardObjects.h"
54 * Scoped is a helper to create RAII wrappers
55 * Type argument |Traits| is expected to have the following structure:
59 * // Define the type of the value stored in the wrapper
60 * typedef value_type type;
61 * // Returns the value corresponding to the uninitialized or freed state
62 * const static type empty();
63 * // Release resources corresponding to the wrapped value
64 * // This function is responsible for not releasing an |empty| value
65 * const static void release(type);
68 template <typename Traits
>
69 class MOZ_NON_TEMPORARY_CLASS Scoped
{
71 typedef typename
Traits::type Resource
;
73 explicit Scoped(MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM
)
74 : mValue(Traits::empty()) {
75 MOZ_GUARD_OBJECT_NOTIFIER_INIT
;
78 explicit Scoped(const Resource
& aValue MOZ_GUARD_OBJECT_NOTIFIER_PARAM
)
80 MOZ_GUARD_OBJECT_NOTIFIER_INIT
;
83 /* Move constructor. */
84 Scoped(Scoped
&& aOther MOZ_GUARD_OBJECT_NOTIFIER_PARAM
)
85 : mValue(std::move(aOther
.mValue
)) {
86 MOZ_GUARD_OBJECT_NOTIFIER_INIT
;
87 aOther
.mValue
= Traits::empty();
90 ~Scoped() { Traits::release(mValue
); }
93 operator const Resource
&() const { return mValue
; }
94 const Resource
& operator->() const { return mValue
; }
95 const Resource
& get() const { return mValue
; }
96 // Non-constant getter.
97 Resource
& rwget() { return mValue
; }
100 * Forget the resource.
102 * Once |forget| has been called, the |Scoped| is neutralized, i.e. it will
103 * have no effect at destruction (unless it is reset to another resource by
106 * @return The original resource.
109 Resource tmp
= mValue
;
110 mValue
= Traits::empty();
115 * Perform immediate clean-up of this |Scoped|.
117 * If this |Scoped| is currently empty, this method has no effect.
120 Traits::release(mValue
);
121 mValue
= Traits::empty();
124 bool operator==(const Resource
& aOther
) const { return mValue
== aOther
; }
127 * Replace the resource with another resource.
129 * Calling |operator=| has the side-effect of triggering clean-up. If you do
130 * not want to trigger clean-up, you should first invoke |forget|.
134 Scoped
& operator=(const Resource
& aOther
) { return reset(aOther
); }
136 Scoped
& reset(const Resource
& aOther
) {
137 Traits::release(mValue
);
142 /* Move assignment operator. */
143 Scoped
& operator=(Scoped
&& aRhs
) {
144 MOZ_ASSERT(&aRhs
!= this, "self-move-assignment not allowed");
146 new (this) Scoped(std::move(aRhs
));
151 explicit Scoped(const Scoped
& aValue
) = delete;
152 Scoped
& operator=(const Scoped
& aValue
) = delete;
156 MOZ_DECL_USE_GUARD_OBJECT_NOTIFIER
160 * SCOPED_TEMPLATE defines a templated class derived from Scoped
161 * This allows to implement templates such as ScopedFreePtr.
163 * @param name The name of the class to define.
164 * @param Traits A struct implementing clean-up. See the implementations
167 #define SCOPED_TEMPLATE(name, Traits) \
168 template <typename Type> \
169 struct MOZ_NON_TEMPORARY_CLASS name \
170 : public mozilla::Scoped<Traits<Type> > { \
171 typedef mozilla::Scoped<Traits<Type> > Super; \
172 typedef typename Super::Resource Resource; \
173 name& operator=(Resource aRhs) { \
174 Super::operator=(aRhs); \
177 name& operator=(name&& aRhs) = default; \
179 explicit name(MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM) \
180 : Super(MOZ_GUARD_OBJECT_NOTIFIER_ONLY_PARAM_TO_PARENT) {} \
181 explicit name(Resource aRhs MOZ_GUARD_OBJECT_NOTIFIER_PARAM) \
182 : Super(aRhs MOZ_GUARD_OBJECT_NOTIFIER_PARAM_TO_PARENT) {} \
183 name(name&& aRhs MOZ_GUARD_OBJECT_NOTIFIER_PARAM) \
184 : Super(std::move(aRhs) MOZ_GUARD_OBJECT_NOTIFIER_PARAM_TO_PARENT) {} \
187 explicit name(const name&) = delete; \
188 name& operator=(const name&) = delete; \
192 * MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE makes it easy to create scoped
193 * pointers for types with custom deleters; just overload
194 * TypeSpecificDelete(T*) in the same namespace as T to call the deleter for
197 * @param name The name of the class to define.
198 * @param Type A struct implementing clean-up. See the implementations
200 * *param Deleter The function that is used to delete/destroy/free a
201 * non-null value of Type*.
205 * MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE(ScopedPRFileDesc, PRFileDesc, \
209 * ScopedPRFileDesc file(PR_OpenFile(...));
211 * } // file is closed with PR_Close here
213 #define MOZ_TYPE_SPECIFIC_SCOPED_POINTER_TEMPLATE(name, Type, Deleter) \
215 inline void TypeSpecificDelete(Type* aValue) { \
218 typedef ::mozilla::TypeSpecificScopedPointer<Type> name;
220 template <typename T
>
221 void TypeSpecificDelete(T
* aValue
);
223 template <typename T
>
224 struct TypeSpecificScopedPointerTraits
{
226 static type
empty() { return nullptr; }
227 static void release(type aValue
) {
229 TypeSpecificDelete(aValue
);
234 SCOPED_TEMPLATE(TypeSpecificScopedPointer
, TypeSpecificScopedPointerTraits
)
236 } /* namespace mozilla */
238 #endif /* mozilla_Scoped_h */