зеркало из https://github.com/mozilla/gecko-dev.git
590 строки
14 KiB
C++
590 строки
14 KiB
C++
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
|
|
/*
|
|
* The contents of this file are subject to the Netscape Public License
|
|
* Version 1.0 (the "NPL"); you may not use this file except in
|
|
* compliance with the NPL. You may obtain a copy of the NPL at
|
|
* http://www.mozilla.org/NPL/
|
|
*
|
|
* Software distributed under the NPL is distributed on an "AS IS" basis,
|
|
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
|
|
* for the specific language governing rights and limitations under the
|
|
* NPL.
|
|
*
|
|
* The Initial Developer of this code under the NPL is Netscape
|
|
* Communications Corporation. Portions created by Netscape are
|
|
* Copyright (C) 1998 Netscape Communications Corporation. All Rights
|
|
* Reserved.
|
|
*/
|
|
|
|
#ifndef COM_auto_ptr_h___
|
|
#define COM_auto_ptr_h___
|
|
|
|
|
|
|
|
// Wrapping includes can speed up compiles (see "Large Scale C++ Software Design")
|
|
#ifndef nsDebug_h___
|
|
#include "nsDebug.h"
|
|
// for |NS_PRECONDITION|
|
|
#endif
|
|
|
|
#ifndef nsISupports_h___
|
|
#include "nsISupports.h"
|
|
// for |nsresult|, |NS_IF_ADDREF|, et al
|
|
#endif
|
|
|
|
|
|
|
|
/*
|
|
WARNING:
|
|
The code in this file should be considered EXPERIMENTAL. It defies several of our
|
|
current coding conventions; in particular, it is based on templates. It is not to
|
|
be used in production code under any circumstances, until such time as our current
|
|
coding-conventions barring templates can be relaxed. At that time, this warning
|
|
will be removed.
|
|
|
|
It is checked-in only so that concerned parties can experiment, to see if it fills
|
|
a useful (and affordable) role.
|
|
|
|
NOT FOR USE IN PRODUCTION CODE!
|
|
*/
|
|
|
|
#if defined(NOT_PRODUCTION_CODE) && defined(USE_EXPERIMENTAL_SMART_POINTERS)
|
|
|
|
|
|
/* USER MANUAL
|
|
|
|
What is |COM_auto_ptr|?
|
|
|
|
|COM_auto_ptr| is a `smart-pointer'. It is a template class that manages
|
|
|AddRef| and |Release| so that you don't have to. It helps you write code that is
|
|
leak-proof, exception safe, and significantly less verbose than you would with
|
|
straight COM interface pointers. With |COM_auto_ptr|, you may never have to
|
|
call |AddRef| or |Release| by hand.
|
|
|
|
You still have to understand COM. You still have to know which functions
|
|
return interface pointers that have already been |AddRef|ed and which don't.
|
|
You still have to ensure you program logic doesn't produce circularly referencing
|
|
garbage. |COM_auto_ptr| is not a panacea. It is, however, helpful, easy to use,
|
|
well-tested, and polite. It doesn't require that a function author cooperate with
|
|
you, nor does your use force others to use it.
|
|
|
|
|
|
Why does |COM_auto_ptr| have such a funny name? I.e., why doesn't it follow our
|
|
naming conventions?
|
|
|
|
The name of this class is very important. It is designed to communicate the purpose
|
|
of the class easily to any programmer new to the project, who is already familiar with
|
|
|std::auto_ptr| and who knows that COM requires ref-counting. Relating this class'
|
|
name to |auto_ptr| is more important to clarity than following the local naming
|
|
convention.
|
|
|
|
|
|
How do I use |COM_auto_ptr|?
|
|
|
|
Typically, you can use a |COM_auto_ptr| exactly as you would a standard COM
|
|
interface pointer:
|
|
|
|
IFoo* fooP; COM_auto_ptr<IFoo> fooP;
|
|
// ... // ...
|
|
fooP->SomeFunction(x, y, z); fooP->SomeFunction(x, y, z);
|
|
AnotherFunction(fooP); AnotherFunction(fooP);
|
|
|
|
if ( fooP ) if ( fooP )
|
|
// ... // ...
|
|
|
|
if ( fooP == barP ) if ( fooP == barP )
|
|
// ... // ...
|
|
|
|
There are some differences, though. In particular, you can't call |AddRef| or |Release|
|
|
through a |COM_auto_ptr| directly, nor would you need to. |AddRef| is called for you
|
|
whenever you assign a COM interface pointer _into_ a |COM_auto_ptr|. |Release| is
|
|
called on the old value, and also when the |COM_auto_ptr| goes out of scope. Trying
|
|
to call |AddRef| or |Release| yourself will generate a compile-time error.
|
|
|
|
fooP->AddRef(); // fooP->AddRef(); // ERROR: no permission
|
|
fooP->Release(); // fooP->Release(); // ERROR: no permission
|
|
|
|
The final difference is that a bare |COM_auto_ptr| (or rather a pointer to it) can't
|
|
be supplied as an argument to a function that `fills in' a COM interface pointer.
|
|
Rather it must be wrapped with a utility call that says whether the function calls
|
|
|AddRef| before returning, e.g.,
|
|
|
|
...->QueryInterface(riid, &fooP) ...->QueryInterface(riid, func_AddRefs(fooP))
|
|
|
|
LookupFoo(&fooP); LookupFoo( func_doesnt_AddRef(fooP) );
|
|
|
|
Don't worry. It's a compile-time error if you forget to wrap it.
|
|
|
|
|
|
IFoo* foo = 0;
|
|
nsresult status = CreateIFoo(&foo);
|
|
if ( NS_SUCCEEDED(status) )
|
|
{
|
|
IBar* bar = 0;
|
|
if ( NS_SUCCEEDED(status = foo->QueryInterface(riid, &bar)) )
|
|
{
|
|
IFooBar* foobar = 0;
|
|
if ( NS_SUCCEEDED(status = CreateIFooBar(foo, bar, &foobar)) )
|
|
{
|
|
foobar->DoTheReallyHardThing();
|
|
foobar->Release();
|
|
}
|
|
bar->Release();
|
|
}
|
|
foo->Release();
|
|
}
|
|
|
|
|
|
COM_auto_ptr<IFoo> fooP;
|
|
nsresult status = CreateIFoo( func_AddRefs(fooP) );
|
|
if ( NS_SUCCEEDED(status) )
|
|
{
|
|
COM_auto_ptr<IBar> barP;
|
|
if ( NS_SUCCEEDED(status = foo->QueryInterface(riid, func_AddRefs(barP))) )
|
|
{
|
|
COM_auto_ptr<IFooBar> fooBarP;
|
|
if ( NS_SUCCEEDED(status = CreateIFooBar(fooP, barP, func_AddRefs(fooBarP))) )
|
|
fooBarP->DoTheReallyHardThing();
|
|
}
|
|
}
|
|
|
|
|
|
|
|
|
|
Where should I use |COM_auto_ptr|?
|
|
|
|
|
|
Is there an easy way to convert my current code?
|
|
|
|
|
|
|
|
|
|
Where _shouldn't_ I use |COM_auto_ptr|?
|
|
|
|
What do I have to beware of?
|
|
*/
|
|
|
|
|
|
|
|
/*
|
|
Set up some #defines to turn off a couple of troublesome C++ features.
|
|
Interestingly, none of the compilers barf on template stuff.
|
|
|
|
Ideally, we would want declarations like these in a configuration file
|
|
that that everybody would get. Deciding exactly how to do that should
|
|
be part of the process of moving from experimental to production.
|
|
*/
|
|
|
|
#if defined(__GNUG__) && (__GNUC_MINOR__ <= 90) && !defined(SOLARIS)
|
|
#define NO_MEMBER_USING_DECLARATIONS
|
|
#endif
|
|
|
|
#if defined(_MSC_VER) && (_MSC_VER<1100)
|
|
#define NO_EXPLICIT
|
|
#define NO_BOOL
|
|
#endif
|
|
|
|
#if defined(IRIX)
|
|
#define NO_MEMBER_USING_DECLARATIONS
|
|
#define NO_EXPLICIT
|
|
#define NO_NEW_CASTS
|
|
#define NO_BOOL
|
|
#endif
|
|
|
|
|
|
#ifdef NO_EXPLICIT
|
|
#define explicit
|
|
#endif
|
|
|
|
#ifndef NO_NEW_CASTS
|
|
#define STATIC_CAST(T,x) static_cast<T>(x)
|
|
#define REINTERPRET_CAST(T,x) reinterpret_cast<T>(x)
|
|
#else
|
|
#define STATIC_CAST(T,x) ((T)(x))
|
|
#define REINTERPRET_CAST(T,x) ((T)(x))
|
|
#endif
|
|
|
|
#ifndef NO_BOOL
|
|
typedef bool CAP_BOOL;
|
|
#else
|
|
typedef PRBool CAP_BOOL;
|
|
#endif
|
|
|
|
|
|
template <class T>
|
|
class nsDerivedSafe : public T
|
|
/*
|
|
No client should ever see or have to type the name of this class. It is the
|
|
artifact that makes it a compile-time error to call |AddRef| and |Release|
|
|
on a |COM_auto_ptr|.
|
|
|
|
See |COM_auto_ptr::operator->|, |COM_auto_ptr::operator*|, et al.
|
|
*/
|
|
{
|
|
private:
|
|
#ifndef NO_MEMBER_USING_DECLARATIONS
|
|
using T::AddRef;
|
|
using T::Release;
|
|
#else
|
|
nsrefcnt AddRef();
|
|
nsrefcnt Release();
|
|
#endif
|
|
};
|
|
|
|
#if defined(NO_MEMBER_USING_DECLARATIONS) && defined(NEED_UNUSED_VIRTUAL_IMPLEMENTATIONS)
|
|
template <class T>
|
|
nsrefcnt
|
|
nsDerivedSafe<T>::AddRef()
|
|
{
|
|
return 0;
|
|
}
|
|
|
|
template <class T>
|
|
nsrefcnt
|
|
nsDerivedSafe<T>::Release()
|
|
{
|
|
return 0;
|
|
}
|
|
|
|
#endif
|
|
|
|
|
|
|
|
|
|
#if 0
|
|
template <class T>
|
|
struct nsDontAddRef
|
|
/*
|
|
...cooperates with |COM_auto_ptr| to allow you to assign in a pointer _without_
|
|
|AddRef|ing it. You would rarely use this directly, but rather through the
|
|
machinery of |func_AddRefs| in the argument list to functions that |AddRef|
|
|
their results before returning them to the caller.
|
|
|
|
See also |func_AddRefs()| and |class nsFuncAddRefs|.
|
|
*/
|
|
{
|
|
explicit
|
|
nsDontAddRef( T* aRawPtr )
|
|
: mRawPtr(aRawPtr)
|
|
{
|
|
// nothing else to do here
|
|
}
|
|
|
|
T* mRawPtr;
|
|
};
|
|
|
|
template <class T>
|
|
nsDontAddRef<T>
|
|
dont_AddRef( T* aRawPtr )
|
|
/*
|
|
...makes typing easier, because it deduces the template type, e.g.,
|
|
you write |dont_AddRef(fooP)| instead of |nsDontAddRef<IFoo>(fooP)|.
|
|
|
|
Like the class it is shorthand for, you would rarely use this directly,
|
|
but rather through |func_AddRefs|.
|
|
*/
|
|
{
|
|
return nsDontAddRef<T>(aRawPtr);
|
|
}
|
|
#endif
|
|
|
|
|
|
|
|
|
|
template <class T>
|
|
class COM_auto_ptr
|
|
/*
|
|
...
|
|
*/
|
|
{
|
|
public:
|
|
typedef T element_type;
|
|
|
|
explicit
|
|
COM_auto_ptr( T* aRawPtr = 0 )
|
|
: mRawPtr(aRawPtr),
|
|
mIsAwaitingAddRef(0)
|
|
{
|
|
NS_IF_ADDREF(mRawPtr);
|
|
}
|
|
|
|
#if 0
|
|
explicit
|
|
COM_auto_ptr( const nsDontAddRef<T>& aSmartPtr )
|
|
: mRawPtr(aSmartPtr.mRawPtr),
|
|
mIsAwaitingAddRef(0)
|
|
{
|
|
// nothing else to do here
|
|
}
|
|
#endif
|
|
|
|
COM_auto_ptr( const COM_auto_ptr<T>& aSmartPtr )
|
|
: mRawPtr(aSmartPtr.mRawPtr),
|
|
mIsAwaitingAddRef(0)
|
|
{
|
|
NS_IF_ADDREF(mRawPtr);
|
|
}
|
|
|
|
~COM_auto_ptr()
|
|
{
|
|
if ( mRawPtr && !mIsAwaitingAddRef )
|
|
NS_RELEASE(mRawPtr);
|
|
}
|
|
|
|
COM_auto_ptr&
|
|
operator=( T* rhs )
|
|
{
|
|
reset(rhs);
|
|
return *this;
|
|
}
|
|
|
|
#if 0
|
|
COM_auto_ptr&
|
|
operator=( const nsDontAddRef<T>& rhs )
|
|
{
|
|
if ( mRawPtr && !mIsAwaitingAddRef )
|
|
NS_RELEASE(mRawPtr);
|
|
mIsAwaitingAddRef = 0;
|
|
mRawPtr = rhs.mRawPtr;
|
|
return *this;
|
|
}
|
|
#endif
|
|
|
|
COM_auto_ptr&
|
|
operator=( const COM_auto_ptr& rhs )
|
|
{
|
|
reset(rhs.mRawPtr);
|
|
return *this;
|
|
}
|
|
|
|
nsDerivedSafe<T>*
|
|
operator->() const
|
|
// returns a |nsDerivedSafe<T>*| to deny clients the use of |AddRef| and |Release|
|
|
{
|
|
NS_PRECONDITION(mRawPtr != 0, "You can't dereference a NULL COM_auto_ptr with operator->().");
|
|
return get();
|
|
}
|
|
|
|
nsDerivedSafe<T>&
|
|
operator*() const
|
|
// returns a |nsDerivedSafe<T>*| to deny clients the use of |AddRef| and |Release|
|
|
{
|
|
NS_PRECONDITION(mRawPtr != 0, "You can't dereference a NULL COM_auto_ptr with operator*().");
|
|
return *get();
|
|
}
|
|
|
|
operator nsDerivedSafe<T>*() const
|
|
{
|
|
return get();
|
|
}
|
|
|
|
nsDerivedSafe<T>*
|
|
get() const
|
|
// returns a |nsDerivedSafe<T>*| to deny clients the use of |AddRef| and |Release|
|
|
{
|
|
return REINTERPRET_CAST(nsDerivedSafe<T>*, mRawPtr);
|
|
}
|
|
|
|
void
|
|
reset( T* aRawPtr = 0 )
|
|
{
|
|
NS_IF_ADDREF(aRawPtr);
|
|
if ( mRawPtr && !mIsAwaitingAddRef )
|
|
NS_RELEASE(mRawPtr);
|
|
mIsAwaitingAddRef = 0;
|
|
mRawPtr = aRawPtr;
|
|
}
|
|
|
|
|
|
// private:
|
|
// template <class T> friend class nsFuncAddRefs;
|
|
// template <class T> friend class nsFuncDoesntAddRef;
|
|
|
|
T**
|
|
StartAssignment( CAP_BOOL awaiting_AddRef )
|
|
{
|
|
if ( mRawPtr && !mIsAwaitingAddRef )
|
|
NS_RELEASE(mRawPtr);
|
|
mIsAwaitingAddRef = awaiting_AddRef;
|
|
mRawPtr = 0;
|
|
return &mRawPtr;
|
|
}
|
|
|
|
void
|
|
FinishAssignment()
|
|
{
|
|
if ( mIsAwaitingAddRef )
|
|
{
|
|
NS_IF_ADDREF(mRawPtr);
|
|
mIsAwaitingAddRef = 0;
|
|
}
|
|
}
|
|
|
|
private:
|
|
T* mRawPtr;
|
|
CAP_BOOL mIsAwaitingAddRef;
|
|
};
|
|
|
|
|
|
|
|
template <class T>
|
|
inline
|
|
CAP_BOOL
|
|
operator==( const COM_auto_ptr<T>& aLeft, const T*const aRight )
|
|
{
|
|
return aLeft.get() == aRight;
|
|
}
|
|
|
|
template <class T>
|
|
inline
|
|
CAP_BOOL
|
|
operator!=( const COM_auto_ptr<T>& aLeft, const T*const aRight )
|
|
{
|
|
return aLeft.get() != aRight;
|
|
}
|
|
|
|
template <class T>
|
|
inline
|
|
CAP_BOOL
|
|
operator==( const T*const aLeft, const COM_auto_ptr<T>& aRight )
|
|
{
|
|
return aLeft == aRight.get();
|
|
}
|
|
|
|
template <class T>
|
|
inline
|
|
CAP_BOOL
|
|
operator!=( const T*const aLeft, const COM_auto_ptr<T>& aRight )
|
|
{
|
|
return aLeft != aRight.get();
|
|
}
|
|
|
|
|
|
|
|
|
|
template <class T>
|
|
class nsFuncAddRefs
|
|
/*
|
|
...
|
|
|
|
This class is designed to be used for anonymous temporary objects in the
|
|
argument list of calls that return COM interface pointers, e.g.,
|
|
|
|
COM_auto_ptr<IFoo> fooP;
|
|
...->QueryInterface(iid, nsFuncAddRefs<IFoo>(fooP))
|
|
...->QueryInterface(iid, func_AddRefs(fooP))
|
|
|
|
When initialized with a |COM_auto_ptr|, as in the example above, it returns
|
|
a |void**| (or |T**| if needed) that the outer call (|QueryInterface| in this
|
|
case) can fill in. When this temporary object goes out of scope, just after
|
|
the call returns, its destructor assigned the resulting interface pointer, i.e.,
|
|
|QueryInterface|s result, into the |COM_auto_ptr| it was initialized with.
|
|
|
|
See also |nsFuncDoesntAddRef|.
|
|
*/
|
|
{
|
|
public:
|
|
explicit
|
|
nsFuncAddRefs( COM_auto_ptr<T>& aSmartPtr )
|
|
: mTargetSmartPtr(&aSmartPtr)
|
|
{
|
|
// nothing else to do
|
|
}
|
|
|
|
operator void**()
|
|
{
|
|
return REINTERPRET_CAST(void**, mTargetSmartPtr->StartAssignment(0));
|
|
}
|
|
|
|
T*&
|
|
operator*()
|
|
{
|
|
NS_PRECONDITION(mTargetSmartPtr != 0, "func_AddRefs into no destination");
|
|
return *(mTargetSmartPtr->StartAssignment(0));
|
|
}
|
|
|
|
operator T**()
|
|
{
|
|
NS_PRECONDITION(mTargetSmartPtr != 0, "func_AddRefs into no destination");
|
|
return mTargetSmartPtr->StartAssignment(0);
|
|
}
|
|
|
|
private:
|
|
COM_auto_ptr<T>* mTargetSmartPtr;
|
|
};
|
|
|
|
template <class T>
|
|
inline
|
|
nsFuncAddRefs<T>
|
|
func_AddRefs( COM_auto_ptr<T>& aSmartPtr )
|
|
{
|
|
return nsFuncAddRefs<T>(aSmartPtr);
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
template <class T>
|
|
class nsFuncDoesntAddRef
|
|
/*
|
|
...
|
|
*/
|
|
{
|
|
public:
|
|
explicit
|
|
nsFuncDoesntAddRef( COM_auto_ptr<T>& aSmartPtr )
|
|
: mTargetSmartPtr(&aSmartPtr)
|
|
{
|
|
// nothing else to do
|
|
}
|
|
|
|
nsFuncDoesntAddRef( nsFuncDoesntAddRef<T>& F )
|
|
: mTargetSmartPtr(F.mTargetSmartPtr)
|
|
{
|
|
F.mTargetSmartPtr = 0;
|
|
}
|
|
|
|
~nsFuncDoesntAddRef()
|
|
{
|
|
if ( mTargetSmartPtr )
|
|
mTargetSmartPtr->FinishAssignment();
|
|
}
|
|
|
|
operator void**()
|
|
{
|
|
return REINTERPRET_CAST(void**, mTargetSmartPtr->StartAssignment(1));
|
|
}
|
|
|
|
T*&
|
|
operator*()
|
|
{
|
|
NS_PRECONDITION(mTargetSmartPtr != 0, "func_doesnt_AddRef into no destination");
|
|
return *(mTargetSmartPtr->StartAssignment(1));
|
|
}
|
|
|
|
operator T**()
|
|
{
|
|
NS_PRECONDITION(mTargetSmartPtr != 0, "func_doesnt_AddRef into no destination");
|
|
return mTargetSmartPtr->StartAssignment(1);
|
|
}
|
|
|
|
private:
|
|
nsFuncDoesntAddRef<T> operator=( const nsFuncDoesntAddRef<T>& ); // not to be implemented
|
|
|
|
private:
|
|
COM_auto_ptr<T>* mTargetSmartPtr;
|
|
};
|
|
|
|
template <class T>
|
|
inline
|
|
nsFuncDoesntAddRef<T>
|
|
func_doesnt_AddRef( COM_auto_ptr<T>& aSmartPtr )
|
|
{
|
|
return nsFuncDoesntAddRef<T>(aSmartPtr);
|
|
}
|
|
|
|
#endif // defined(NOT_PRODUCTION_CODE) && defined(USE_EXPERIMENTAL_SMART_POINTERS)
|
|
|
|
#endif // !defined(COM_auto_ptr_h___)
|