Sylvestre Ledru
3035033c92
Convert xpcom/docs/*.rst to MyST-flavored Markdown. Update stringguide.xpidl :ref: targets to the explicit (stringguide-xpidl)= MyST anchor. Differential Revision: https://phabricator.services.mozilla.com/D304220
70 lines
3.0 KiB
Markdown
70 lines
3.0 KiB
Markdown
# 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.
|