This directory contains a variety of pointer-like objects (aka smart pointers). This is a brief overview of what they are and how they should be used. Refer to individual header files for details. C++ is not memory safe, so use these types to help guard against potential memory bugs. There are other pointer-like object types implemented elsewhere that may be right for a given use case, such as
std::unique_ptr<T>. More on all types in video form here and in a doc here.
Use for class fields/members that would otherwise be a native pointer.
This is a weakly refcounted wrapper for a native pointer (also called a raw pointer). When the object is deleted, the allocator will “poison” the memory that object occupied and keep the memory around so it’s not reused. This reduces the risk and impact of a use-after-free bug.
Depending on the use case, it's possible a smart pointer with additional features would be more appropriate, but if none of those are applicable or necesssary,
raw_ptr<T> is much safer than a native pointer.
Use when a reference to an object might outlive the object itself.
These are useful for asynchronous work, which is common in Chrome. If an async task references other objects or state, and it's possible for that state to be destroyed before the task runs, those references should be held in a
WeakPtr<T> is associated with a
WeakPtrFactory<T>. When the associated factory (usually owned by T) is destroyed, all
WeakPtr<T> are invalidated (becomes null) rather than becoming use-after-frees. If such references should never outlive the object, consider using SafeRef instead.
Use to express that a reference to an object must not outlive the object.
An example is if you have a class member that you want to guarantee outlives the class itself. SafeRef automatically enforces the lifetime assumptions and eliminates the need for validity checks.
If the assumption that the object is valid is broken, then the process terminates safely and generates a crash report. Though not ideal, it's preferable to a potentially undiscovered security bug.
This type is built on top of WeakPtr, so if you want a
SafeRef<T>, T needs a WeakPtrFactory as a member. It works like
WeakPtr, but doesn‘t allow for a null state. There’s also overlap with
raw_ptr, though this was implemented first.
Use when you want manually managed strong refcounting. Use carefully!
It’s an owning smart pointer, so it owns a pointer to something allocated in the heap and gives shared ownership of the underlying object, since it can be copied. When all
scoped_refptrs pointing to the same object are gone, that object gets destroyed.
This is Chrome‘s answer to
std::shared_ptr<T>. It additionally requires T to inherit from
RefCountedThreadSafe, since the ref counting happens in the object itself, unlike
shared_ptr<T>. It’s preferred for an object to remain on the same thread, as
RefCounted is much cheaper. If there are
scoped_refptrs to the same object on different threads, use
RedCountedThreadSafe, since accesses to the reference count can race. In this case, without external synchronization, the destructor can run on any thread. If the destructor interacts with other systems it is important to control and know which thread has the last reference to the object, or you can end up with flakiness.