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.