1# //base/memory Types 2 3## Overview 4This directory contains a variety of pointer-like objects (aka smart pointers). 5This is a brief overview of what they are and how they should be used. Refer to 6individual header files for details. C++ is not memory safe, so use these types 7to help guard against potential memory bugs. 8There are other pointer-like object types implemented elsewhere that may be 9right for a given use case, such as `absl::optional<T>` and 10`std::unique_ptr<T>`. More on all types in video form 11[here](https://youtu.be/MpwbWSEDfjM?t=582s) and in a doc 12[here](https://docs.google.com/document/d/1VRevv8JhlP4I8fIlvf87IrW2IRjE0PbkSfIcI6-UbJo/edit?usp=sharing). 13 14## `raw_ptr<T>` 15Use for class fields/members that would otherwise be a `T*`. 16 17This is a weakly refcounted wrapper for a `T*` (also called a raw 18pointer). When the object is deleted, the allocator will "poison" the memory 19that object occupied and keep the memory around so it’s not reused. This reduces 20the risk and impact of a use-after-free bug. 21 22Depending on the use case, it's possible a smart pointer with additional 23features would be more appropriate, but if none of those are applicable or 24necessary, `raw_ptr<T>` is preferred over a `T*`. 25 26For more information, see [`raw_ptr.md`](./raw_ptr.md); for guidance on 27usage, see 28[the style guide](../../styleguide/c++/c++.md#non_owning-pointers-in-class-fields). 29 30## `raw_ref<T>` 31Use for class fields/members that would otherwise be a `T&`. 32 33This shares much in common with `raw_ptr<T>`, but asserts that the 34`raw_ref<T>` is not nullable. 35 36For more information, see [`raw_ptr.md`](./raw_ptr.md); for guidance on 37usage, see 38[the style guide](../../styleguide/c++/c++.md#non_owning-pointers-in-class-fields). 39 40## `base::WeakPtr<T>` 41Use when a reference to an object might outlive the object itself. 42 43These are useful for asynchronous work, which is common in Chrome. If an async 44task references other objects or state, and it's possible for that state to be 45destroyed before the task runs, those references should be held in a 46`WeakPtr<T>`. Each `WeakPtr<T>` is associated with a `WeakPtrFactory<T>`. When 47the associated factory (usually owned by T) is destroyed, all `WeakPtr<T>` are 48invalidated (becomes null) rather than becoming use-after-frees. If such 49references should never outlive the object, consider using SafeRef instead. 50 51## `base::SafeRef<T>` 52Use to express that a reference to an object must not outlive the object. 53 54An example is if you have a class member that you want to guarantee outlives the 55class itself. SafeRef automatically enforces the lifetime assumptions and 56eliminates the need for validity checks. 57 58If the assumption that the object is valid is broken, then the process 59terminates safely and generates a crash report. Though not ideal, it's 60preferable to a potentially undiscovered security bug. 61 62This type is built on top of WeakPtr, so if you want a `SafeRef<T>`, T needs a 63WeakPtrFactory as a member. It works like `WeakPtr`, but doesn't allow for a 64null state. There's also overlap with `raw_ptr`, though this was implemented 65first. 66 67## `scoped_refptr<T>` 68Use when you want manually managed strong refcounting. Use carefully! 69 70It’s an owning smart pointer, so it owns a pointer to something allocated in the 71heap and gives shared ownership of the underlying object, since it can be 72copied. When all `scoped_refptr<T>`s pointing to the same object are gone, that 73object gets destroyed. 74 75This is Chrome's answer to `std::shared_ptr<T>`. It additionally requires T to 76inherit from `RefCounted` or `RefCountedThreadSafe`, since the ref counting 77happens in the object itself, unlike `shared_ptr<T>`. 78 79It's preferred for an object to remain on the same thread, as `RefCounted` is 80much cheaper. If there are `scoped_refptr<T>`s to the same object on different 81threads, use `RefCountedThreadSafe`, since accesses to the reference count can 82race. In this case, without external synchronization, the destructor of 83`scoped_refptr<T>`, which decreases the reference count by one, can run on any 84thread. 85 86Inheriting from `RefCountedThreadSafe` by itself doesn't make a class `T` or the 87underlying object of `scoped_refptr<T>` thread-safe: It merely ensures that the 88counter manipulated by `scoped_refptr<T>` is thread-safe. 89 90If the destructor interacts with other systems it is important to 91control and know which thread has the last reference to the object, or you can 92end up with flakiness. 93