mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-10-07 09:54:42 +00:00
87810a2b88
This change involved migrating a number of pages, including the DMD documentation, XPIDL documentation, and the Internal String Guide to Firefox Source Docs, as well as performing a review/update to these documents to be more accurate and current. In addition, some additional sections were written in the various documents to elaborate on important features which were not present when the documents were originally written, and a few new documents were written to add basic documentaiton for other XPCOM components. The following MDN pages were migrated in this patch: https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPIDL https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Guide/Internal_strings https://developer.mozilla.org/en-US/docs/Mozilla/Performance/DMD Differential Revision: https://phabricator.services.mozilla.com/D110424
88 lines
3.3 KiB
ReStructuredText
88 lines
3.3 KiB
ReStructuredText
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
|
|
once 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.
|
|
|
|
|
|
|
|
|
|
|
|
|