already AddRefed
From MDC
already_AddRefed cooperates with nsCOMPtr to allow you to assign in a pointer without
AddRefing it.
You might want to use this as a return type from a function that produces an already 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: xpcom/glue/nsCOMPtr.h.
[edit] Example
...
already_AddRefed<nsIFoo> GetFoo() {
// OK, this is a contrived example.
nIFoo* foo = mFoo;
NS_IF_ADDREF(foo);
return foo;
}
...
// The following assignment doesn't perform an additional AddRef,
// as it would do if GetFoo() returned a raw pointer.
nsCOMPtr<nsIFoo> foo = GetFoo();