already_AddRefed

« XPCOM API Reference

already_AddRefed in association with nsCOMPtr allows you to assign in a pointer without AddRefing it.

You may want to use this as a return type from a function that has already produced an  AddRefed pointer as a result. In fact, it is preferred to use already_AddRefed in this case over returning a raw pointer or nsCOMPtr (see the nsCOMPtr user manual).

Defined in: mfbt/AlreadyAddRefed.h.

Example

...
already_AddRefed<nsIFoo> GetFoo() {
  nsIFoo* foo = mFoo;
  NS_IF_ADDREF(foo);
  return foo;
}

// or

already_AddRefed<nsIFoo> GetFoo() {
  nsCOMPtr<nsIFoo> foo = mFoo; 
  // ...
  return foo.forget();
}
...
// The following assignment doesn't perform an additional AddRef,
// as it would do if GetFoo() returned a raw pointer.
nsCOMPtr<nsIFoo> foo = GetFoo();

See also

nsCOMPtr, getterAddRefs(), dont_AddRef().