mirror of
https://github.com/klzgrad/naiveproxy.git
synced 2024-12-01 01:36:09 +03:00
85 lines
4.1 KiB
Markdown
85 lines
4.1 KiB
Markdown
|
# //base/memory Types
|
|||
|
|
|
|||
|
|
## Overview
|
|||
|
|
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](https://youtu.be/MpwbWSEDfjM?t=582s) and in a doc
|
|||
|
|
[here](https://docs.google.com/document/d/1VRevv8JhlP4I8fIlvf87IrW2IRjE0PbkSfIcI6-UbJo/edit?usp=sharing).
|
|||
|
|
|
|||
|
|
## `raw_ptr<T>`
|
|||
|
|
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`](./raw_ptr.md); for guidance on
|
|||
|
|
usage, see
|
|||
|
|
[the style guide](../../styleguide/c++/c++.md#non_owning-pointers-in-class-fields).
|
|||
|
|
|
|||
|
|
## `raw_ref<T>`
|
|||
|
|
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`](./raw_ptr.md); for guidance on
|
|||
|
|
usage, see
|
|||
|
|
[the style guide](../../styleguide/c++/c++.md#non_owning-pointers-in-class-fields).
|
|||
|
|
|
|||
|
|
## `base::WeakPtr<T>`
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
## `base::SafeRef<T>`
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
## `base::scoped_refptr<T>`
|
|||
|
|
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`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`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 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.
|