If you have never used
nsCOMPtrs before, this section is for you. If you're already familiar with
nsCOMPtrs, then you might want to skip ahead to the Reference Manual or the FAQ. Don't worry; the Getting Started Guide is short.
nsCOMPtr is a tool to help prevent leaks.
nsCOMPtr is a "smart pointer". It is a template class that acts, syntactically, just like an ordinary pointer in C or C++, i.e., you can apply
-> to it to "get to" what it points at.
nsCOMPtr is smart in that, unlike a raw C++ pointer to an XPCOM object,
QueryInterface for you.
nsCOMPtr is defined in the source files:
...though you probably don't want to look in there, just yet.
nsCOMPtr, you can write code that is shorter, cleaner, clearer, and safer, than you can with raw XPCOM interface pointers.
XPCOM Basics: Ownership and Reference Counting
This is a quick refresher on some fundamental issues of XPCOM. You should already know this, and should be able to just skim this short section. If this is unfamiliar material, you're not ready for
nsCOMPtrs yet. A good place to learn about the basic rules and reasoning behind COM is in Essential COM by Don Box. Don Box gets into more of the details, traps, and pitfalls of COM in Effective COM. You should also have a reasonable knowledge of C++. Probably the three most helpful books on this topic are The C++ Programming Language by Bjarne Stroustrup, Effective C++, and More Effective C++ by Scott Meyers.
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
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
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
CreateInstance. All good getters
AddRefthe 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.
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
Additionally, the class using raw XPCOM interface pointers will need a destructor to
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
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.
In most cases, you'll use an
nsCOMPtr exactly as you would a raw XPCOM interface pointer. Note the slight difference in declaration.
There are two main differences. First: you no longer need, nor are you allowed, to call
Second: you can't just pass the address of an
nsCOMPtr to a getter expecting to return a result through a raw XPCOM interface pointer parameter. You have to `annotate' the
nsCOMPtr with the
That's it. You now know enough to start using
nsCOMPtrs. There are a few other details you will want to know as you use
nsCOMPtr in more complicated situations, but what you've just learned will cover 90% of your uses.
A Few Details
There are a couple more things that will help you get the most out of
Very often, you first get an interface pointer by calling
QueryInterface is a getter like any other, and you already know one way to call it, applying the
getter_AddRefs rule, as described above.
QueryInterface is used so frequently, though, that
nsCOMPtr has a special facility to call it. This facility is type-safe, and it enables an
nsCOMPtr to be directly constructed from the result of
QueryInterface. Construction from the correct value is more efficient that construction followed by assignment. This facility is the
do_QueryInterface directive. Using
do_QueryInterface, the sample above would look like this
nsCOMPtr happily calls
Release implicitly. This same favor is not extended to
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
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.
nsCOMPtr Doesn't Do
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
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.
Plainly, the author believed (though perhaps with some question) that the
AddRef automatically as it was assigned into
*aFileSpec. This is not the case. An
nsCOMPtr automatically calls
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.
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
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
AddRefs when you assign in to it. It does nothing when you assign out of it.
Where should I use
You should use an
nsCOMPtr any place you use an interface pointer as an owning reference, i.e., where you call
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 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
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() don't return an
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:
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
Compare this to the most frequent leaks caused by returning a raw pointer you have already
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
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
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.
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.
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 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
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
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 (see, e.g., the
nsCOMPtr side of Comparison 1). As stated above, with no directives, the
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 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.