Frequently Asked Questions

This section will help you if you're fixing a broken build, or have what you think is a quick obvious question, and you don't have time to read the Reference Manual. This FAQ usually just refers back directly to the appropriate answer, there. If you're looking here just to learn about nsCOMPtrs, you'll get a better introduction in the Getting Started Guide.

The FAQ is divided into sections to help you find what you're looking for faster. In most cases, the answer will just refer back into the reference manual, above. No need to explain things twice :-).

Buildtime Errors

The build just broke. It's not in your code, or it's not on your platform, but there's an nsCOMPtr on the line where the error is and you're suspicious. You're looking in the right place.

comparing an nsCOMPtr to a raw XPCOM interface pointer

declaring an nsCOMPtr to a forward-declared class

not linking to XPCOM

not including nsCOMPtr.h

different settings of NSCAP_FEATURE_DEBUG_PTR_TYPES

Runtime Errors

NS_ASSERTION "QueryInterface needed"

May be caused by a class that derives from a given interface, when you forgetting to also specify the interface name in the NS_IMPL_ISUPPORTS / NS_IMPL_THREADSAFE_ISUPPORTS macro.

For example, the assertion occurs when you convert the pointer to the object to a raw pointer to that interface, then assign the raw pointer to another nsCOMPtr for that interface.

NS_PRECONDITION "You can't dereference a NULL nsCOMPtr with operator->()"

NS_PRECONDITION "You can't dereference a NULL nsCOMPtr with operator*()"

Other issues

• printf("%x\n", mynsCOMPtr); can cause the program to crash on SIGILL (illegal instruction), and not on the line with the printf, which can make it tricky to figure out. For debugging purposes you can write printf("%x\n", mynsCOMPtr.get());

How do I...

initialize an nsCOMPtr?

Release an nsCOMPtr before it goes out of scope?

Assign 0 into it. Whenever an nsCOMPtr takes on a new value, it always Releases its old value, if any. Assigning in the value 0 is just like assigning in a raw pointer that happens to be NULL. The old referent will be Released. [See Initialization and Assignment for more details]

You should note, though, that there is a small performance penalty for this. The nsCOMPtr will still exercize logic in its destructor to attempt to Release the value it has at that time. The optimal solution is to arrange the lifetime of your nsCOMPtr to correspond to exactly how long you want to hold the reference. E.g., using blocks as in this sample

// The most efficient scheme is to scope your |nsCOMPtr| to live exactly as long
//  as you need to hold the reference

nsresult
SomeLongFunction( nsIBar* aBar )
  {
    nsresult rv;
    // ...

    {
      // I only need the |nsIFoo| interface for a short time
      //  so I control its lifetime by declaring it inside
      //  a block statement.

      nsCOMPtr<nsIFoo> foo( do_QueryInterface(aBar, &rv) );
      if ( foo )
        foo->DoSomeFooThing();

      // |foo| goes out of scope, and so |Release|s its referent, here
    }

    // ...tons of stuff here, during which I don't need an |nsIFoo|

    return rv;
  }

Editors Note: Move this discussion to the efficiency section, and link to it from here.

make an nsCOMPtr leak (for a debug test)?

call a getter that uses a raw XPCOM interface pointer as an `in/out' parameter?

call a getter that fills in an nsIFoo*& parameter?

call a getter that doesn't AddRef its result?

Any XPCOM function that returns an interface pointer, i.e., a `getter', must have already AddRefed that pointer. If it didn't, you should probably report it as a bug. No matter which code pattern you use to solve this problem, you should comment it, e.g., // Warning: this getter doesn't AddRef() its result. If the getter returns the new pointer as its function result, no worries,

General

Does nsCOMPtr bloat the code?

Are nsCOMPtrs fast? Can I use them in tight loops?

Bibliography

Web Resources

• nsCOMPtr.h, and nsCOMPtr.cpp are the source to nsCOMPtr. You can examine the source to nsCOMPtr online using (the wonderful) LXR. Exploring this code is not an adventure for the faint of heart.
• Some COM Ownership Guidelines.
• Interface Pointers Considered Harmful by Don Box originally appeared in the September 1995 issue of "The C++ Report".
• COM Smart Pointers Even More Harmful by Don Box is a follow-up article that originally appeared in the February 1996 issue of "The C++ Report".

Books

• Essential COM by Don Box.
• Effective COM by Don Box, et al.
• The C++ Programming Language (3rd Edition) by Bjarne Stroustrup.
• Effective C++ (2nd Edition): 50 Specific Ways to Improve Your Programs and Designs by Scott Meyers.
• More Effective C++ : 35 New Ways to Improve Your Programs and Designs by Scott Meyers.
• Effective C++ CD: 85 Specific Ways to Improve Your Programs and Designs by Scott Meyers.

People

• Don Box is a smart guy who has been writing about COM programming for a long time.