This translation is incomplete. Please help translate this article from English



什么是 nsCOMPtr?

nsCOMPtr 是防止内存泄漏的一种工具。

nsCOMPtr 是一种智能指针。 它是一个模板类,在使用上类似C/C++中的普通指针。如:可使用*或者->得到其所指定的内容。nsCOMPtr之所以智能,是因为它不像一般指向XPCOM对象的指针,nsCOMPtr还管理AddRef, Release, 和QueryInterface方法。 nsCOMPtr是在以下源文件中定义的:

...though you probably don't want to look in there, just yet.


[XP]COM Basics: Ownership and Reference Counting

这段是对XPCOM的一些基本问题的一个复习。对nsCOMPtrs的理解,需要对XPCOM有一个基本的认识。您可通过以下方式对XPCOM进行学习。Don BoxEssential COM 介绍了COM的基本规则和使用。 Don Box 在 Effective COM.一书中更详尽的说明了COM的细节,缺陷和易犯的错误。您还需要对C++有基本的了解。这里列举三本比较有用的书:Bjarne Stroustrup 的 The C++ Programming Language,Scott Meyers 的 Effective C++More Effective C++

All XPCOM objects are allocated on the heap. Clients don't get to know much about the implementation of any such object. They reference it only through a pointer to an `interface', i.e., the static type of the pointer is a pointer to an abstract base class, the actual object pointed to is a class derived from that abstract base class. The XPCOM object is said to `implement that interface'. The client's reference to the object is typically called `an interface pointer'.

An object may implement many interfaces. Each interface is (at least conceptually) separately `reference counted'. That is, the interface keeps a count of the number of clients holding references to it. When that count goes to zero, the interface may delete itself. Clients are expected to keep this reference count accurate by incrementing it when they acquire a reference to the interface, and decrementing it before they let go. To facilitate this, all interfaces inherit from an abstract base class that provides the member functions AddRef, and Release.

A rule of XPCOM is that any function that creates or returns an interface pointer will have already AddRefed it. The caller can then hold onto the reference indefinitely, calling Release when it no longer needs it. When the last pointer to an interface is Released, the interface (and consequently, typically the underlying object) will delete itself. As long as there is an outstanding AddRef against the interface, it continues to exist. If you forget to call Release, the object will leak, i.e., the storage for that object will never be reclaimed. Leaks are bad :-).

A reference through which you will call AddRef and Release is called an owning reference. It holds a stake in the underlying object. That object cannot go away until the owning reference has relinquished its claim. Not all references need to be owning references. In fact, if two objects somehow end up owning each other (even transitively) it becomes difficult for either of those object to be reclaimed without adding some `out-of-band' mechanism for breaking the ownership cycle. The document Some COM Ownership Guidelines provides some hints on when ownership is needed. The following lists are good starting point, but by no means complete.

You use an owning reference when

  • you created the object;
  • you got the object from a function that might have created it, e.g., any `getter' function, such as QueryInterface, or CreateInstance. All good getters AddRef the interface pointers they produce, thus providing you with an owning reference;
  • you will hold onto the reference longer than the scope of the function in which you acquired it, e.g., you got it as a parameter, but you're hanging onto it in a member variable (see, for example, Comparison 1, below).

You don't need an owning reference when

  • the object is passed in as a parameter, and you don't need to keep it any longer than the scope of this function;
  • the object's lifetime is known to contain yours in some well defined way, e.g., in the nodes of a tree, parent nodes keep owning references to their children, children need not keep owning references to their parents.

It turns out that reference counting by hand is hard for programmers to get right. It may sound simple, but in practice it's very easy to forget to Release at the appropriate moment. Or to AddRef too many or too few times.

How does nsCOMPtr help?

nsCOMPtr manages AddRef, Release, and other red-tape for you. An nsCOMPtr looks and acts as much like a raw XPCOM interface pointer as C allows, but it knows it owns the object it points to. This takes a little getting used to on your part, but ends up with less typing, clearer, safer code, and less leaks.

For instance, here is a typical snippet of code (at its most compact) where you assign a XPCOM interface pointer into a member variable, i.e., the body of a `setter' function, side-by-side using raw XPCOM interface pointers and nsCOMPtrs. 



// raw [XP]COM interface pointers...
// given: |nsIFoo* mFooPtr;|

   |AddRef| the new value if it's not
   |NULL|; assign it in; and |Release|
   the old value, if any (so we don't
   leak it).
   This order of assignment is special
   and must be used to avoid particular
   ownership bugs.

nsIFoo* temp = mFooPtr;
mFooPtr = aFooPtr;
// |nsCOMPtr|...
// given: |nsCOMPtr<nsIFoo> mFooPtr;|

   This assignment automatically
   |Release|s the old value in
   |mFooPtr|, if any, and |AddRef|s the
   new one, in the appropriate sequence
   to avoid the ownership bug mentioned

mFooPtr = aFooPtr;

Additionally, the class using raw XPCOM interface pointers will need a destructor to Release mFooPtr; and a constructor to ensure that mFooPtr is initially set to NULL (or some other reasonable value).

nsCOMPtr helps you write code that is leak-proof, exception safe, and significantly less verbose than you would with raw XPCOM interface pointers. With nsCOMPtr, you may never have to call AddRef, Release, or QueryInterface by hand.

You still have to understand XPCOM. You still have to know which functions return interface pointers that have already been AddRefed and which don't. You still have to ensure your program logic doesn't produce circularly referencing garbage. nsCOMPtr 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.


The Basics


对照 2. 相似点: nsCOMPtr类似于 XPCOM接口指针
// raw [XP]COM interface pointers...

nsIFoo* fooPtr = 0;
 // ...
fooPtr->SomeFunction(x, y, z);

if ( fooPtr )
  // ...

if ( fooPtr == foo2Ptr )
  // ...
// |nsCOMPtr|...

nsCOMPtr<nsIFoo> fooPtr;
// ...
fooPtr->SomeFunction(x, y, z);

if ( fooPtr )
  // ...

if ( fooPtr == foo2Ptr )
  // ...



对照 3. 不同点: AddRef Release 对于 nsCOMPtrs 来说是非法的。
// raw [XP]COM interface pointers...
// given: |nsIFoo* mFooPtr;|

    Note: this sequence is not the
    correct order to do assign
    raw pointers anyway (see
    Comparison 1) but I need it
    for this comparison.


mFooPtr = aFooPtr;

// |nsCOMPtr|...
// given: |nsCOMPtr<nsIFoo> mFooPtr;|

    You no longer need, nor will the
    compiler let you, call |AddRef|,
    or |Release|.

  // Error: |Release| is private
mFooPtr = aFooPtr;
  // Error: |AddRef| is private


第二:使用 getter_AddRefs 标识nsCOMPtr,作为获取指针返回值的函数的参数,而不能只使用nsCOMPtr的地址作为参数。

对照 4. 不同点: nsCOMPtr 作为输出参数时,使用 getter_AddRefs。
// raw [XP]COM interface pointers...

nsIFoo* foo;

// |nsCOMPtr|s...

nsCOMPtr<nsIFoo> foo;







以下是更多细节让您更了解 nsCOMPtr

通常,通过调用 QueryInterface 获取接口指针 QueryInterface 是一个 getter 函数,由以上方法,可通过 getter_AddRefs 方法来获取。

The hard way to QueryInterface into an nsCOMPtr.
// A way (though not the best way) to |QueryInterface| into an |nsCOMPtr|...

nsCOMPtr<nsIFoo> foo;

nsresult rv = bar->QueryInterface(NS_GET_IID(nsIFoo), getter_AddRefs(foo));

  // Or, if you're a savvy [XP]COM programmer,
  //  you use the type-safe version...
nsresult rv = CallQueryInterface(bar, getter_AddRefs(foo));

因为 QueryInterface 使用频繁,nsCOMPtr 提供了一种特殊方式对其调用。这种方式是类型安全的,QueryInterface的返回值能直接构造nsCOMPtr。这种构造方式比通过赋值进行构造效率更高。这种方式是 do_QueryInterface 。通过使用这种方式,以上例子可写为:

How to QueryInterface into an nsCOMPtr.
// The best way to |QueryInterface| into an |nsCOMPtr|...

nsresult rv;
nsCOMPtr<nsIFoo> foo( do_QueryInterface(bar, &rv) );

  // Or, if you don't care about the |nsresult|
nsCOMPtr<nsIFoo> foo( do_QueryInterface(bar) );

nsCOMPtr happily calls AddRef and Release implicitly. This same favor is not extended to QueryInterface. nsCOMPtr does not QueryInterface on assignment without your explicit permission in the form of the do_QueryInterface directive. You need never worry about hidden queries. However, be aware that if you should have queried but didn't, e.g., when assigning in a raw pointer where C allows the assignment, but XPCOM wouldn't, nsCOMPtr will assert at runtime. Use do_QueryInterface whenever you assign in a pointer to a XPCOM interface of a different type, even if that type happens to derive from the base type of the nsCOMPtr


对照6. do_QueryInterface 避免了XPCOM 中的类型错误。
class nsIBar
  : public nsIFoo ... { ... };

nsIBar* p = ...;

  // C   thinks every |nsIBar*| is an
  //  |nsIFoo*|, therefore, C   allows
  //  this...
nsCOMPtr<nsIFoo> foo = p;
  //  ...even though it is an [XP]COM
  //  type error
class nsIBar
  : public nsIFoo ... { ... };

nsIBar* p = ...;

  // No type error here...
nsCOMPtr<nsIFoo> foo( do_QueryInterface(p) );

Remember, the C type system and the XPCOM type system are really two independent things. Because XPCOM interfaces are expressed as abstract C base classes, you may be tempted to let C handle the differences, or to use C casts to navigate between interface types. This is wrong. The only sanctioned way to get between XPCOM types is with QueryInterface. In the example above, there is no reason to assume that the nsIFoo* C pulls out of p would be the same one that p->QueryInterface() would return.

dont_AddRef is a similar directive that helps you when you assign in a pointer that has already been AddRefed, e.g., because you called a getter that returned the pointer as its function result.

Using dont_AddRef.
nsCOMPtr<nsIFoo> foo( dont_AddRef(CreateFoo()) );
  // |CreateFoo| |AddRef|s its result, as all good getters do

Something nsCOMPtr Doesn't Do

An nsCOMPtr does all that is necessary to behave as an owning reference. A given nsCOMPtr does not, however, cooperate in making other owning pointers. After learning how nsCOMPtr automatically AddRefs a pointer as it is being assigned in, the natural assumption is that it does the same thing when assigning out. Here is a snippet of code that demonstrates this misconception.

// Incorrect assumptions about |nsCOMPtr|...

nsCacheRecord::GetFileSpec( nsIFileSpec** aFileSpecResult )
      ...fills in the callers |nsFileSpec*| (which the caller supplied
      the address of) with a copy of my member variable |mFileSpec|,
      an |nsCOMPtr|.  I.e., this function is a `getter'.

      Remember: good [XP]COM getters always |AddRef| their result.
    // ...
    *aFileSpec = mFileSpec;
      // the |nsCOMPtr| should take care of the refcount here, right?
    return NS_OK;

Plainly, the author believed (though perhaps with some question) that the nsCOMPtr, mFileSpec, would AddRef automatically as it was assigned into *aFileSpec. This is not the case. An nsCOMPtr automatically calls AddRef and Release (only) on its own behalf. In all other situations, it is designed to be a drop in replacement for a raw XPCOM pointer. Where ever an nsCOMPtr is used in a situation where a raw pointer is needed, the nsCOMPtr automatically provides one.

// |nsCOMPtr| produces a raw pointer when needed...

nsCOMPtr<nsIFoo> foo = ...;

  // 1.  Assigning into a raw pointer
nsIFoo* raw_foo = foo;

  // 2.  Assigning into another |nsCOMPtr|
nsCOMPtr<nsIFoo> foo2 = foo;

  // 3.  As a parameter

  // 4.  Testing the value in an |if| expression
  // 5.  Calling a member function
if ( foo )

In all of these cases, pretty much the exact same code is executed (case 2 is slightly different, but the intent is the same). In each case, you are essentially extracting the raw pointer value for your own purpose. If the nsCOMPtr AddRefed the value each time you did that, cases 4 and 5 would obviously always generate leaks. SetFoo, from case 3, would have to be written two different ways when given an nsCOMPtr, it would know the value was already AddRefed, and when given a raw pointer it would assume the value was not AddRefed. Actually the contradictions run deeper than that. All these cases show that automatically AddRefing on `output' makes nsCOMPtrs and raw-pointers act differently from the point of view of the clients. The goal is to make them act the same so that nsCOMPtrs can be a drop in replacement (modulo managing its own `ownership').

Given what you now know, the rule is predictable. As described above, and unless you tell it otherwise, an nsCOMPtr AddRefs when you assign in to it. It does nothing when you assign out of it.

Where should I use nsCOMPtrs?

You should use an nsCOMPtr any place you use an interface pointer as an owning reference, i.e., where you call AddRef and Release on it. You should use nsCOMPtr as a member variable, where it will simplify setters, and eliminate constructors, destructors, and assignment operators. You should use nsCOMPtr on the stack, where it makes calling QueryInterface almost pleasant, and eliminates the complex logic that falls out of error handling.

Where shouldn't I use nsCOMPtrs?

Don't use nsCOMPtrs where you don't need an owning reference. See Some COM Ownership Guidelines. nsCOMPtr is designed to be used with XPCOM interfaces, so don't use it with non-interfaces with specific exceptions described below. Don't use nsCOMPtrs in XPCOM interfaces. Don't use them in plain old C code; nsCOMPtrs are, of course, a C only construct. Never cast an nsCOMPtr, it's almost guaranteed to leak.

nsCOMPtrs for non-interface classes

Appropriately formatted answer to come, in the meanwhile, the full details are available in this news posting (via Google Groups).

nsCOMPtrs in function signatures

In general, you won't want to use nsCOMPtr in the signature of XPCOM (i.e., `scriptable') functions. nsCOMPtr is not currently directly supported by IDL. However, you may sometime be tempted to use an nsCOMPtr in a non-scriptable function.

nsCOMPtr<T> f() 不返回 nsCOMPtr

This practice is dangerous. Returning an AddRefed pointer in almost any form as a function result leads to several potential errors, some of which are leaks, some of which are dangling pointers. Returning an nsCOMPtr may seem like a good idea (since it tells clients you are giving them ownership), however it can be the cause of an dangling pointer. Consider:

// Don't return |nsCOMPtr|s...
nsCOMPtr<nsIFoo> CreateFoo();
// ...

nsIFoo* myFoo = CreateFoo(); // Oops: |myFoo| now dangles!
  // |CreateFoo| returns an |nsCOMPtr|, which
  //  automatically |Release|s right after this
  //  assignment.  Now |myFoo| refers to a
  //  deleted object.

You can tell callers you are giving them ownership in a way that doesn't pose this hazard by returning a already_AddRefed<T> (see bug #59212). An nsCOMPtr knows not to AddRef a value that is already_AddRefed.

// Preferred form: if you must return a pointer, use |already_AddRefed|...
already_AddRefed<nsIFoo> CreateFoo();
// ...

nsIFoo* myFoo1 = CreateFoo(); // doesn't dangle
nsCOMPtr<nsIFoo> myFoo2( CreateFoo() ); // doesn't leak
nsCOMPtr<nsIFoo> myFoo3( dont_AddRef(CreateFoo()) ); // redundant, but legal and correct

Compare this to the most frequent leaks caused by returning a raw pointer you have already AddRefed:

// Don't return raw pointers; that incites leaks...
nsIFoo* CreateFoo(); // returns an |AddRef|ed pointer
// ...

nsCOMPtr<nsIFoo> myFoo = CreateFoo(); // Oops: leak;
nsCOMPtr<nsIFoo> myFoo( dont_AddRef(CreateFoo()) );
  // Since |CreateFoo| already |AddRef|s its result, we must remind
  //  our |nsCOMPtr| not to.  It's easy to forget.  Prevent it in advance
  //  by not returning pointers as function results, or else by returning
  //  an |already_AddRefed<T>| as above.
void f( nsCOMPtr<T> ) don't pass an nsCOMPtr by value

This practice is wasteful, but not otherwise harmful. There is no need to AddRef parameters, as they are guaranteed to live as long as the function call. You only need to AddRef them as you store them in a structure that will live longer than the function call. Which means the appropriate member of that structure should be an nsCOMPtr, not the function parameter. Additionally, this signature may confuse callers into thinking they need an nsCOMPtr just to call the function.

void f( const nsCOMPtr<T>& ) don't pass an nsCOMPtr by const reference

Exactly as the signature above, this practice is wasteful, but not otherwise harmful, and has the same impact as passing an nsCOMPtr by value if the caller only supplied a raw pointer.

void f( nsCOMPtr<T>* ) avoid passing an nsCOMPtr by address, if possible

This practice requires callers to have an nsCOMPtr, and requires them to do a little extra work, as operator& for nsCOMPtrs is private (to help prevent leaks caused by casting; also see bug 59414). This is an acceptable way to declare `in/out' parameters, but prefer passing nsCOMPtrs by reference, as below.

// Passing an |nsCOMPtr| by pointer requires extra work...
void f( nsCOMPtr<nsIFoo>* );
// ...

nsCOMPtr<nsIFoo> myFoo = ...;

f( address_of(myFoo) );
void f( nsCOMPtr<T>& ) do pass an nsCOMPtr by reference for `in/out' parameters

This is the prefered scheme for providing `in/out' parameters. If you were to use a raw pointer instead, your function couldn't know what ownership relationship the caller had to the input value, and hence, couldn't know whether to Release it or not before assigning in the new value. By declaring the parameter as an nsCOMPtr&, the relationship is explicit.


An nsCOMPtr is an owning reference. Whatever it points to has been AddRefed, counting the nsCOMPtr as one of its `owners'. An nsCOMPtr always calls Release before letting go, whether the nsCOMPtr is letting go so that it can point to a different object, or because the nsCOMPtr is going out of scope. Any time a new value is assigned into an nsCOMPtr, the nsCOMPtr automatically always Releases its old referent, if any, and (unless you tell it you already have) AddRefs the new.

You use an nsCOMPtr exactly as you would a raw XPCOM interface pointer in almost all cases. You won't have to explictly call AddRef or Release through it, nor will the compiler allow it. The only place you can't use an nsCOMPtr without change is where a raw XPCOM interface pointer is an `out' parameter. In this case, you wrap the nsCOMPtr with getter_AddRefs (see Comparison 4).

When assigning into an nsCOMPtr, you will usually just supply another pointer (either a raw XPCOM interface pointer or an nsCOMPtr), with no additional directives { web.link("#Comparison_1", "Comparison 1") }}). As stated above, with no directives, the nsCOMPtr will Release its old referent, if any, and AddRef the new. This is appropriate when the thing you're assigning in hasn't yet been AddRefed to account for the new reference. This is typically the case when you are assigning in a pointer that you didn't call a function to get, e.g., one that was passed in as a parameter, or that you pulled out of a structure.

You can tell nsCOMPtr it doesn't need to AddRef the new value on assignment by wrapping the new value in dont_AddRef. Do this, for example, when you got the new value from a function which, like all good XPCOM getters, already called AddRef on your behalf.

You may not assign in a pointer to a different interface type; you must first query it to the right type (see, e.g., Comparison 6 and the surrounding discussion). nsCOMPtr never calls QueryInterface implicitly, i.e., you must call it yourself, or explictly ask nsCOMPtr to call it with do_QueryInterface. The do_QueryInterface directive allows you to do the query as part of the assignment. This better facilitates constructing an nsCOMPtr directly from the right value, rather than constructing it and assigning in the correct value later. Construction alone is more efficient than construction followed by assignment. Prefer construction over assignment whereever reasonable. Be careful not to apply do_QueryInterface to a function returning an AddRefed pointer [see this short section for an explanation]

For more details, continue on to the Reference Manual.