From 2176a3dd18ae3567c1d4f28b2d6d8471e850b69e Mon Sep 17 00:00:00 2001 From: Andreas Kling Date: Fri, 20 Mar 2020 14:14:39 +0100 Subject: [PATCH] Documentation: Tweak document about smart pointers a bit Add notes about assigning between FooPtr / NonnullFooPtr. --- Documentation/SmartPointers.md | 79 +++++++++++++++++++--------------- 1 file changed, 44 insertions(+), 35 deletions(-) diff --git a/Documentation/SmartPointers.md b/Documentation/SmartPointers.md index 8410e6cdfaf..339a3e335b9 100644 --- a/Documentation/SmartPointers.md +++ b/Documentation/SmartPointers.md @@ -1,9 +1,9 @@ -# Serenity smart pointers +# SerenityOS smart pointers ---- ## Introduction -There are three main C++ smart pointer types used in the Serenity operating system. Each type describes the ownership (or lack thereof) of the pointee. +There are three main C++ smart pointer types used in SerenityOS. Each type describes the ownership (or lack thereof) of the pointee. The reason for using these pointers is to make it explicit through code who owns which resources, and how ownership is transferred. They also serve as a guard against memory leaks and use-after-free bugs. @@ -11,62 +11,71 @@ The reason for using these pointers is to make it explicit through code who owns ---- ## OwnPtr and NonnullOwnPtr -OwnPtr is used for single-owner objects. An object held by an OwnPtr is owned by that OwnPtr, and not by anybody else. +`OwnPtr` is used for single-owner objects. An object held in an `OwnPtr` is owned by that `OwnPtr`, and not by anybody else. -This means that the OwnPtr is responsible for deleting the pointee when the OwnPtr goes out of scope. +This means that the `OwnPtr` is responsible for deleting the pointee when the `OwnPtr` goes out of scope. -NonnullOwnPtr is a special variant of OwnPtr with one additional property: it cannot be null. NonnullOwnPtr is suitable as a return type from functions that are guaranteed to never return null, and as an argument type where ownership is transferred, and the argument may not be null. In other words, if OwnPtr is "\*", then NonnullOwnPtr is "&". +`NonnullOwnPtr` is a special variant of `OwnPtr` with one additional property: it cannot be null. `NonnullOwnPtr` is suitable as a return type from functions that are guaranteed to never return null, and as an argument type where ownership is transferred, and the argument may not be null. In other words, if `OwnPtr` is "\*", then `NonnullOwnPtr` is "&". -There is a make() helper that creates a new object and returns it wrapped in an NonnullOwnPtr. +There is a `make()` helper that creates a new object and returns it wrapped in an `NonnullOwnPtr`. - { - NonnullOwnPtr my_object = make(); - my_object->do_stuff(); - // my_object goes out of scope here, and the Foo will be deleted. - } +```cpp +{ + NonnullOwnPtr my_object = make(); + my_object->do_stuff(); + // my_object goes out of scope here, and the Foo will be deleted. +} +``` +Note: A `NonnullOwnPtr` can be assigned to an `OwnPtr` but not vice versa. To transform an known-non-null `OwnPtr` into a `NonnullOwnPtr`, use `OwnPtr::release_nonnull()`. ---- ## RefPtr and NonnullRefPtr -RefPtr is used for multiple-owner objects. An object held by a RefPtr is owned together by every pointer pointing to that object. +`RefPtr` is used for multiple-owner objects. An object held by a `RefPtr` is owned together by every pointer pointing to that object. Shared ownership is implemented via reference counting. -NonnullRefPtr is a special variant of RefPtr with one additional property: it cannot be null. NonnullRefPtr is suitable as a return type from functions that are guaranteed to never return null, and as an argument type where the argument may not be null. In other words, if RefPtr is "\*", then NonnullRefPtr is "&". +`NonnullRefPtr` is a special variant of `RefPtr` with one additional property: it cannot be null. `NonnullRefPtr` is suitable as a return type from functions that are guaranteed to never return null, and as an argument type where the argument may not be null. In other words, if `RefPtr` is "\*", then `NonnullRefPtr` is "&". -Objects can only be held by RefPtr if they meet certain criteria. Specifically, they need to implement the functions `ref()` and `unref()`. +Objects can only be held by `RefPtr` if they meet certain criteria. Specifically, they need to implement the functions `ref()` and `unref()`. -To make a class T reference counted, you can simply make it inherit from RefCounted. This will add all the necessary pieces to T. +To make a class `T` reference-counted, you can simply make it inherit from `RefCounted`. This will add all the necessary pieces to `T`. -**Note:** When constructing a RefCounted-derived class, the reference count starts out at 1 (since 0 would mean that the object has no owners and should be deleted.) The object must therefore be "adopted" by someone who takes responsibility of that 1. This is done through the global `adopt()` function: +**Note:** When constructing an object that derives from `RefCounted`, the reference count starts out at 1 (since 0 would mean that the object has no owners and should be deleted.) The object must therefore be "adopted" by someone who takes responsibility of that 1. This is done through the global `adopt()` function: - class Bar : public RefCounted { - ... - }; +```cpp +class Bar : public RefCounted { + ... +}; - RefPtr our_object = adopt(*new Bar); - RefPtr another_owner = our_object; +RefPtr our_object = adopt(*new Bar); +RefPtr another_owner = our_object; +``` -In the above example, the Bar object will only be deleted once both "our\_object" and "another\_owner" are gone. +In the above example, the Bar object will only be deleted once both `our_object` and `another_owner` are gone. + +Note: A `NonnullRefPtr` can be assigned to a `RefPtr` but not vice versa. To transform an known-non-null `RefPtr` into a `NonnullRefPtr`, either use `RefPtr::release_nonnull()` or simply dereference the `RefPtr` using its `operator*`. ---- ## WeakPtr -WeakPtr is used for object that somebody else owns. When the pointee of a WeakPtr is deleted, the WeakPtr will magically become null. +`WeakPtr` is used for objects that somebody else owns. When the pointee of a `WeakPtr` is deleted, the `WeakPtr` will magically become null. -Behind the scenes, this is implemented using the Weakable template. If you want to make it possible for a class to be weakly-pointed-to, have it inherit from Weakable. +Behind the scenes, this is implemented using the `Weakable` template. If you want to make it possible for a class `T` to be weakly-pointed-to, have it inherit from `Weakable`. -To create a WeakPtr, use `make_weak_ptr()`: +To create a `WeakPtr` to a weakable object, use `make_weak_ptr()`: - class Baz : public Weakable { - .... - }; +```cpp +class Baz : public Weakable { + .... +}; - WeakPtr a_baz; - { - OwnPtr my_baz = make(); - a_baz = my_baz->make_weak_ptr(); - // a_baz now points to my_baz - } - // a_baz is now null, since my_baz went out of scope. +WeakPtr a_baz; +{ + OwnPtr my_baz = make(); + a_baz = my_baz->make_weak_ptr(); + // a_baz now points to my_baz +} +// a_baz is now null, since my_baz went out of scope. +```