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 absl::optional<T> and 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 T*.

This is a weakly refcounted wrapper for a T* (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 necessary, raw_ptr<T> is preferred over a T*.

For more information, see raw_ptr.md; for guidance on usage, see the style guide.

Use for class fields/members that would otherwise be a T&.

This shares much in common with raw_ptr<T>, but asserts that the raw_ref<T> is not nullable.

For more information, see raw_ptr.md; for guidance on usage, see the style guide.

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>. Each 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_refptr<T>s 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 RefCounted or 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_refptr<T>s to the same object on different threads, use RefCountedThreadSafe, since accesses to the reference count can race. In this case, without external synchronization, the destructor of scoped_refptr<T>, which decreases the reference count by one, can run on any thread.

Inheriting from RefCountedThreadSafe by itself doesn't make a class T or the underlying object of scoped_refptr<T> thread-safe: It merely ensures that the counter manipulated by scoped_refptr<T> is thread-safe.

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.