# Reference Counting Helpers

## RefPtr versus nsCOMPtr

The general rule of thumb is to use `nsCOMPtr<T>` when `T` is an
interface type which inherits from `nsISupports`, and `RefPtr<T>` when
`T` is a concrete type.

This basic rule derives from some `nsCOMPtr<T>` code being factored into
the `nsCOMPtr_base` base class, which stores the pointer as a
`nsISupports*`. This design was intended to save some space in the binary
(though it is unclear if it still does). Since `nsCOMPtr` stores the
pointer as `nsISupports*`, it must be possible to unambiguously cast from
`T*` to `nsISupports**`. Many concrete classes inherit from more than
one XPCOM interface, meaning that they cannot be used with `nsCOMPtr`,
which leads to the suggestion to use `RefPtr` for these classes.

`nsCOMPtr<T>` also requires that the target type `T` be a valid target
for `QueryInterface` so that it can assert that the stored pointer is a
canonical `T` pointer (i.e. that `mRawPtr->QueryInterface(T_IID) ==
mRawPtr`).

## do_XXX() nsCOMPtr helpers

There are a number of `do_XXX` helper methods across the codebase which can
be assigned into `nsCOMPtr` (and sometimes `RefPtr`) to perform explicit
operations based on the target pointer type.

In general, when these operations succeed, they will initialize the smart
pointer with a valid value, and otherwise they will silently initialize the
smart pointer to `nullptr`.

### `do_QueryInterface` and `do_QueryObject`

Attempts to cast the provided object to the target class using the XPCOM
`QueryInterface` mechanism. In general, use `do_QueryInterface` may only
be used to cast between interface types in a `nsCOMPtr<T>`, and
`do_QueryObject` in situations when downcasting to concrete types.

### `do_GetInterface`

Looks up an object implementing the requested interface using the
`nsIInterfaceRequestor` interface. If the target object doesn't implement
`nsIInterfaceRequestor` or doesn't provide the given interface, initializes
the smart pointer with `nullptr`.

### `do_GetService`

Looks up the component defined by the passed-in CID or ContractID string in
the component manager, and returns a pointer to the service instance. This
may start the service if it hasn't been started already. The resulting
service will be cast to the target interface type using `QueryInterface`.

### `do_CreateInstance`

Looks up the component defined by the passed-in CID or ContractID string in
the component manager, creates and returns a new instance. The resulting
object will be cast to the target interface type using `QueryInterface`.

### `do_QueryReferent` and `do_GetWeakReference`

When passed a `nsIWeakReference*` (e.g. from a `nsWeakPtr`),
`do_QueryReferent` attempts to re-acquire a strong reference to the held
type, and cast it to the target type with `QueryInterface`. Initializes the
smart pointer with `nullptr` if either of these steps fail.

In contrast `do_GetWeakReference` does the opposite, using
`QueryInterface` to cast the type to `nsISupportsWeakReference*`, and
acquire a `nsIWeakReference*` to the passed-in object.