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.