Automatic memory-ownership pointer supporting "resource acquisition is initialization.
More...
|
| | AutoPtr (Type *p=NULL) |
| | Construct, assuming ownership of the pointed-to object.
|
| | ~AutoPtr () |
| | Destructor - automatically cleans up the pointed-to object.
|
| | AutoPtr (AutoPtr &a) |
| | Copy construct, assuming ownership from the source AutoPtr.
|
| template<typename OtherType> |
| | AutoPtr (AutoPtr< OtherType, DestructorPolicy > &a) |
| | Conversion copy constructor.
|
| AutoPtr & | operator= (const AutoPtr &a) |
| | Assignment, takes over ownership from the source AutoPtr.
|
| template<typename OtherType> |
| AutoPtr & | operator= (AutoPtr< OtherType, DestructorPolicy > &a) |
| | Conversion assignment, takes over ownership of any type assignable to type from the source AutoPtr.
|
| Type & | operator* () const |
| | Dereferencing operator - works exactly like a plain pointer's operator*.
|
| Type * | operator-> () const |
| | Pointer-to-member dereferencing operator - works exactly like a plain pointer's operator->.
|
| Type * | Get () const |
| | Get the plain pointer back.
|
| Type * | Release () |
| | Relinquish ownership of the pointed-to object to the caller.
|
| void | Reset (Type *p=NULL) |
| | Assume ownership of a new object, any existing pointer will be deleted.
|
| bool | IsNull () const |
| | Addition to the textbook interface.
|
| | AutoPtr (const AutoPtrRef< Type > &ref) |
| | Construct from an AutoPtrRef.
|
| template<typename OtherType> |
| | operator AutoPtrRef< OtherType > () |
| | Convert to an AutoPtrRef.
|
| template<typename OtherType> |
| | operator AutoPtr< OtherType, DestructorPolicy > () |
| | Destructive copy-convert allowing for cast of the pointer type.
|
template<typename Type, typename DestructorPolicy = SinglePointerDestructor<Type>>
class MaxSDK::AutoPtr< Type, DestructorPolicy >
Automatic memory-ownership pointer supporting "resource acquisition is initialization.
"
This is a standardized implementation of std::auto_ptr from the STL, allowing
us to portably include AutoPtrs in the 3ds Max SDK without forcing a compiler
or runtime dll version on third-party developers. std::auto_ptrs are
described in your favourite STL documentation, in Scott Meyers's More
Effective C++ and on pp. 367-368 in Bjarne Stroustrup's The C++ Programming
Language. This implementation is based on Stroustrup and Meyers.
AutoPtrs grant the same mechanics as a regular pointer, so they can be
created, assigned and dereferenced much in the same way as a plain old
pointer. Additionally, AutoPtrs provide "resource acquisition is initialization" and automatic memory ownership management in two ways:
<ol>
<li>The object pointed to by the AutoPtr will be implicitly deleted when
the AutoPtr goes out of scope</li>
<li>Through "destructive copying" that causes a copied AutoPtr to surrender
ownership to the pointed to object.</li>
</ol>
This is a very useful technique for making the ownership semantics of a
function very clear. A function that takes an AutoPtr to an object as a
parameter is stating that it assumes ownership of the pointed to object and
that the caller must surrender ownership. A function that returns an
AutoPtr states that the caller must assume ownership of the pointed-to
object.
AutoPtrs help prevent memory leaks and lead to exception safe code by
guaranteeing that dynamically allocated objects will be deleted when the
AutoPtr goes out of scope. The following is unsafe code:
@code
void foo()
{
A *a = new A();
// ...
delete a;
}
\endcode
Will leak if any exception is thrown in the "..." part. Replacing with an AutoPtr guarantees that the memory is cleaned up, since leaving the function through an exception will cause the AutoPtr to go out of scope.
void foo()
{
}
AutoPtr(Type *p=NULL)
Construct, assuming ownership of the pointed-to object.
Definition autoptr.h:206
Since not all objects have the same destruction requirements, the AutoPtr template can be parameterized to support creating various types of AutoPtrs differentiated by their DestructorPolicy. Three standard forms, the default AutoPtr<Type>, ArrayAutoPtr<Type>, and DeleteThisAutoPtr<Type> are available. AutoPtr's default destructor policy is for use with a pointer pointing to a single object (one that uses new and delete). ArrayAutoPtr is for use with a pointer pointing to an array (one that uses new [] and delete []). DeleteThisAutoPtr is for use with Max types requiring clean up through a DeleteThis method.
The two standard implementations are probably enough to cover most cases. Other derivations would be used for, say, pointers using malloc and free or to hide the destructor implementation details by using an explicitly typed, non-templated DestructorPolicy to avoid having to inline the Delete method. This is necessary to implement explicit template instantiation for a forward declared type. The standard templates can't be explicitly instantiated on a forward declared type since they require that the destructor be defined.
NB: The destructive copy semantics mean that AutoPtrs are inappropriate for use in any of the STL's container classes. Classes with data members of type AutoPtr must be non-copyable (derive from class MaxSDK::Util::Noncopyable), or implement their own copy constructor and assignment operator where they deep-copy the object being owned by the AutoPtr.
NB2: Finally, be careful about passing AutoPtrs across DLL boundaries for DLLs compiled with different compilers or different memory allocation schemes. Objects traversing such boundaries must be deallocated on the same side as they were allocated. One way to guarantee this is to use it with objects derived from MaxHeapOperators, or to override a class's delete operator so that the code that actually frees the memory is on the correct side of the DLL boundary.
