xpcom/docs/refptr.rst

   1 Reference Counting Helpers
   2 ==========================
   3
   4 RefPtr versus nsCOMPtr
   5 ----------------------
   6
   7 The general rule of thumb is to use ``nsCOMPtr<T>`` when ``T`` is an
   8 interface type which inherits from ``nsISupports``, and ``RefPtr<T>`` when
   9 ``T`` is a concrete type.
  10
  11 This basic rule derives from some ``nsCOMPtr<T>`` code being factored into
  12 the ``nsCOMPtr_base`` base class, which stores the pointer as a
  13 ``nsISupports*``. This design was intended to save some space in the binary
  14 (though it is unclear if it still does). Since ``nsCOMPtr`` stores the
  15 pointer as ``nsISupports*``, it must be possible to unambiguously cast from
  16 ``T*`` to ``nsISupports**``. Many concrete classes inherit from more than
  17 one XPCOM interface, meaning that they cannot be used with ``nsCOMPtr``,
  18 which leads to the suggestion to use ``RefPtr`` for these classes.
  19
  20 ``nsCOMPtr<T>`` also requires that the target type ``T`` be a valid target
  21 for ``QueryInterface`` so that it can assert that the stored pointer is a
  22 canonical ``T`` pointer (i.e. that ``mRawPtr->QueryInterface(T_IID) ==
  23 mRawPtr``).
  24
  25 do_XXX() nsCOMPtr helpers
  26 -------------------------
  27
  28 There are a number of ``do_XXX`` helper methods across the codebase which can
  29 be assigned into ``nsCOMPtr`` (and sometimes ``RefPtr``) to perform explicit
  30 operations based on the target pointer type.
  31
  32 In general, when these operations succeed, they will initialize the smart
  33 pointer with a valid value, and otherwise they will silently initialize the
  34 smart pointer to ``nullptr``.
  35
  36 ``do_QueryInterface`` and ``do_QueryObject``
  37 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  38
  39 Attempts to cast the provided object to the target class using the XPCOM
  40 ``QueryInterface`` mechanism. In general, use ``do_QueryInterface`` may only
  41 be used to cast between interface types in a ``nsCOMPtr<T>``, and
  42 ``do_QueryObject`` in situations when downcasting to concrete types.
  43
  44
  45 ``do_GetInterface``
  46 ~~~~~~~~~~~~~~~~~~~
  47
  48 Looks up an object implementing the requested interface using the
  49 ``nsIInterfaceRequestor`` interface. If the target object doesn't implement
  50 ``nsIInterfaceRequestor`` or doesn't provide the given interface, initializes
  51 the smart pointer with ``nullptr``.
  52
  53
  54 ``do_GetService``
  55 ~~~~~~~~~~~~~~~~~
  56
  57 Looks up the component defined by the passed-in CID or ContractID string in
  58 the component manager, and returns a pointer to the service instance. This
  59 may start the service if it hasn't been started already. The resulting
  60 service will be cast to the target interface type using ``QueryInterface``.
  61
  62
  63 ``do_CreateInstance``
  64 ~~~~~~~~~~~~~~~~~~~~~
  65
  66 Looks up the component defined by the passed-in CID or ContractID string in
  67 the component manager, creates and returns a new instance. The resulting
  68 object will be cast to the target interface type using ``QueryInterface``.
  69
  70
  71 ``do_QueryReferent`` and ``do_GetWeakReference``
  72 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  73
  74 When passed a ``nsIWeakReference*`` (e.g. from a ``nsWeakPtr``),
  75 ``do_QueryReferent`` attempts to re-acquire a strong reference to the held
  76 type, and cast it to the target type with ``QueryInterface``. Initializes the
  77 smart pointer with ``nullptr`` if either of these steps fail.
  78
  79 In contrast ``do_GetWeakReference`` does the opposite, using
  80 ``QueryInterface`` to cast the type to ``nsISupportsWeakReference*``, and
  81 acquire a ``nsIWeakReference*`` to the passed-in object.