1.. _module-pw_intrusive_ptr: 2 3---------------- 4pw_intrusive_ptr 5---------------- 6 7IntrusivePtr 8------------ 9``pw::IntrusivePtr`` is a smart shared pointer that relies on the pointed-at 10object to do the reference counting. Its API is based on ``std::shared_ptr`` but 11requires the pointed-at class to provide ``AddRef()`` and ``ReleaseRef()`` 12methods to do the reference counting. The easiest way to do that is to 13subclass ``pw::RefCounted``. Doing this will provide atomic reference counting 14and a ``Ptr`` type alias for the ``IntrusivePtr<T>``. 15 16``IntrusivePtr`` doesn't provide any weak pointer ability. 17 18``IntrusivePtr`` with a ``RefCounted``-based class always guarantees atomic 19operations on the reference counter, whereas ``std::shared_ptr`` falls back to a 20non-atomic control block when threading support is not enabled due to a design 21fault in the STL implementation. 22 23Similar to ``std::shared_ptr``, ``IntrusivePtr`` doesn't provide any 24thread-safety guarantees for the pointed-at object or for the pointer object 25itself. I.e. assigning and reading the same ``IntrusivePtr`` from multiple 26threads without external lock is not allowed. 27 28.. code-block:: cpp 29 30 class MyClass : public RefCounted<MyClass> { 31 // ... 32 }; 33 34 // Empty pointer, equals to nullptr. 35 // MyClass::Ptr is the same as IntrusivePtr<MyClass>. 36 MyClass::Ptr empty_ptr = IntrusivePtr<MyClass>(); 37 38 // Wrapping an externally created pointer. 39 MyClass raw_ptr = new MyClass(); 40 MyClass::Ptr ptr_1 = MyClass::Ptr(raw_ptr); 41 // raw_ptr shouldn't be used after this line if ptr_1 can go out of scope. 42 43 // Using MakeRefCounted() helper. 44 auto ptr_2 = MakeRefCounted<MyClass>(/* ... */); 45 46``IntrusivePtr`` can be passed as an argument by either const reference or 47value. Const reference is more preferable because it does not cause unnecessary 48copies (which results in atomic operations on the ref count). Passing by value 49is used when this ``IntrusivePtr`` is immediately stored (e.g. constructor that 50stores ``IntrusivePtr`` in the object field). In this case passing by value and 51move is more explicit in terms of intentions. It is also the behavior that 52clang-tidy checks suggest. 53 54``IntrusivePtr`` should almost always be returned by value. The only case when 55it can be returned by const reference is the trivial getter for the object 56field. When returning locally created ``IntrusivePtr`` or a pointer that was 57casted to the base class it MUST be returned by value. 58 59Recyclable 60---------- 61``pw::Recyclable`` is a mixin that can be used with supported smart pointers 62like ``pw::IntrusivePtr`` to specify a custom memory cleanup routine instead 63of `delete`. The cleanup routine is specified as a method with the signature 64``void pw_recycle()``. For example: 65 66.. code-block:: cpp 67 68 class Foo : public pw::Recyclable<Foo>, public pw::IntrusivePtr<Foo> { 69 public: 70 // public implementation here 71 private: 72 friend class pw::Recyclable<Foo>; 73 void pw_recycle() { 74 if (should_recycle())) { 75 do_recycle_stuff(); 76 } else { 77 delete this; 78 } 79 } 80 }; 81 82``Recyclable`` can be used to avoid heap allocation when using smart pointers, 83as the recycle routine can return memory to a memory pool. 84