| 1 |
.. title:: clang-tidy - cppcoreguidelines-owning-memory |
| 2 |
|
| 3 |
cppcoreguidelines-owning-memory |
| 4 |
=============================== |
| 5 |
|
| 6 |
This check implements the type-based semantics of ``gsl::owner<T*>``, which allows |
| 7 |
static analysis on code, that uses raw pointers to handle resources like |
| 8 |
dynamic memory, but won't introduce RAII concepts. |
| 9 |
|
| 10 |
This check implements `I.11 |
| 11 |
<https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#i11-never-transfer-ownership-by-a-raw-pointer-t-or-reference-t>`_, |
| 12 |
`C.33 |
| 13 |
<https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#c33-if-a-class-has-an-owning-pointer-member-define-a-destructor>`_, |
| 14 |
`R.3 |
| 15 |
<https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#r3-a-raw-pointer-a-t-is-non-owning>`_ |
| 16 |
and `GSL.Views |
| 17 |
<https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#SS-views>`_ |
| 18 |
from the C++ Core Guidelines. |
| 19 |
The definition of a ``gsl::owner<T*>`` is straight forward |
| 20 |
|
| 21 |
.. code-block:: c++ |
| 22 |
|
| 23 |
namespace gsl { template <typename T> owner = T; } |
| 24 |
|
| 25 |
It is therefore simple to introduce the owner even without using an implementation of |
| 26 |
the `Guideline Support Library <https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-gsl>`_. |
| 27 |
|
| 28 |
All checks are purely type based and not (yet) flow sensitive. |
| 29 |
|
| 30 |
The following examples will demonstrate the correct and incorrect initializations |
| 31 |
of owners, assignment is handled the same way. Note that both ``new`` and |
| 32 |
``malloc()``-like resource functions are considered to produce resources. |
| 33 |
|
| 34 |
.. code-block:: c++ |
| 35 |
|
| 36 |
// Creating an owner with factory functions is checked. |
| 37 |
gsl::owner<int*> function_that_returns_owner() { return gsl::owner<int*>(new int(42)); } |
| 38 |
|
| 39 |
// Dynamic memory must be assigned to an owner |
| 40 |
int* Something = new int(42); // BAD, will be caught |
| 41 |
gsl::owner<int*> Owner = new int(42); // Good |
| 42 |
gsl::owner<int*> Owner = new int[42]; // Good as well |
| 43 |
|
| 44 |
// Returned owner must be assigned to an owner |
| 45 |
int* Something = function_that_returns_owner(); // Bad, factory function |
| 46 |
gsl::owner<int*> Owner = function_that_returns_owner(); // Good, result lands in owner |
| 47 |
|
| 48 |
// Something not a resource or owner should not be assigned to owners |
| 49 |
int Stack = 42; |
| 50 |
gsl::owner<int*> Owned = &Stack; // Bad, not a resource assigned |
| 51 |
|
| 52 |
In the case of dynamic memory as resource, only ``gsl::owner<T*>`` variables are allowed |
| 53 |
to be deleted. |
| 54 |
|
| 55 |
.. code-block:: c++ |
| 56 |
|
| 57 |
// Example Bad, non-owner as resource handle, will be caught. |
| 58 |
int* NonOwner = new int(42); // First warning here, since new must land in an owner |
| 59 |
delete NonOwner; // Second warning here, since only owners are allowed to be deleted |
| 60 |
|
| 61 |
// Example Good, Ownership correctly stated |
| 62 |
gsl::owner<int*> Owner = new int(42); // Good |
| 63 |
delete Owner; // Good as well, statically enforced, that only owners get deleted |
| 64 |
|
| 65 |
The check will furthermore ensure, that functions, that expect a ``gsl::owner<T*>`` as |
| 66 |
argument get called with either a ``gsl::owner<T*>`` or a newly created resource. |
| 67 |
|
| 68 |
.. code-block:: c++ |
| 69 |
|
| 70 |
void expects_owner(gsl::owner<int*> o) { delete o; } |
| 71 |
|
| 72 |
// Bad Code |
| 73 |
int NonOwner = 42; |
| 74 |
expects_owner(&NonOwner); // Bad, will get caught |
| 75 |
|
| 76 |
// Good Code |
| 77 |
gsl::owner<int*> Owner = new int(42); |
| 78 |
expects_owner(Owner); // Good |
| 79 |
expects_owner(new int(42)); // Good as well, recognized created resource |
| 80 |
|
| 81 |
// Port legacy code for better resource-safety |
| 82 |
gsl::owner<FILE*> File = fopen("my_file.txt", "rw+"); |
| 83 |
FILE* BadFile = fopen("another_file.txt", "w"); // Bad, warned |
| 84 |
|
| 85 |
// ... use the file |
| 86 |
|
| 87 |
fclose(File); // Ok, File is annotated as 'owner<>' |
| 88 |
fclose(BadFile); // BadFile is not an 'owner<>', will be warned |
| 89 |
|
| 90 |
|
| 91 |
Options |
| 92 |
------- |
| 93 |
|
| 94 |
.. option:: LegacyResourceProducers |
| 95 |
|
| 96 |
Semicolon-separated list of fully qualified names of legacy functions that create |
| 97 |
resources but cannot introduce ``gsl::owner<>``. |
| 98 |
Defaults to ``::malloc;::aligned_alloc;::realloc;::calloc;::fopen;::freopen;::tmpfile``. |
| 99 |
|
| 100 |
|
| 101 |
.. option:: LegacyResourceConsumers |
| 102 |
|
| 103 |
Semicolon-separated list of fully qualified names of legacy functions expecting |
| 104 |
resource owners as pointer arguments but cannot introduce ``gsl::owner<>``. |
| 105 |
Defaults to ``::free;::realloc;::freopen;::fclose``. |
| 106 |
|
| 107 |
|
| 108 |
Limitations |
| 109 |
----------- |
| 110 |
|
| 111 |
Using ``gsl::owner<T*>`` in a typedef or alias is not handled correctly. |
| 112 |
|
| 113 |
.. code-block:: c++ |
| 114 |
|
| 115 |
using heap_int = gsl::owner<int*>; |
| 116 |
heap_int allocated = new int(42); // False positive! |
| 117 |
|
| 118 |
The ``gsl::owner<T*>`` is declared as a templated type alias. |
| 119 |
In template functions and classes, like in the example below, the information |
| 120 |
of the type aliases gets lost. Therefore using ``gsl::owner<T*>`` in a heavy templated |
| 121 |
code base might lead to false positives. |
| 122 |
|
| 123 |
Known code constructs that do not get diagnosed correctly are: |
| 124 |
|
| 125 |
- ``std::exchange`` |
| 126 |
- ``std::vector<gsl::owner<T*>>`` |
| 127 |
|
| 128 |
.. code-block:: c++ |
| 129 |
|
| 130 |
// This template function works as expected. Type information doesn't get lost. |
| 131 |
template <typename T> |
| 132 |
void delete_owner(gsl::owner<T*> owned_object) { |
| 133 |
delete owned_object; // Everything alright |
| 134 |
} |
| 135 |
|
| 136 |
gsl::owner<int*> function_that_returns_owner() { return gsl::owner<int*>(new int(42)); } |
| 137 |
|
| 138 |
// Type deduction does not work for auto variables. |
| 139 |
// This is caught by the check and will be noted accordingly. |
| 140 |
auto OwnedObject = function_that_returns_owner(); // Type of OwnedObject will be int* |
| 141 |
|
| 142 |
// Problematic function template that looses the typeinformation on owner |
| 143 |
template <typename T> |
| 144 |
void bad_template_function(T some_object) { |
| 145 |
// This line will trigger the warning, that a non-owner is assigned to an owner |
| 146 |
gsl::owner<T*> new_owner = some_object; |
| 147 |
} |
| 148 |
|
| 149 |
// Calling the function with an owner still yields a false positive. |
| 150 |
bad_template_function(gsl::owner<int*>(new int(42))); |
| 151 |
|
| 152 |
|
| 153 |
// The same issue occurs with templated classes like the following. |
| 154 |
template <typename T> |
| 155 |
class OwnedValue { |
| 156 |
public: |
| 157 |
const T getValue() const { return _val; } |
| 158 |
private: |
| 159 |
T _val; |
| 160 |
}; |
| 161 |
|
| 162 |
// Code, that yields a false positive. |
| 163 |
OwnedValue<gsl::owner<int*>> Owner(new int(42)); // Type deduction yield T -> int * |
| 164 |
// False positive, getValue returns int* and not gsl::owner<int*> |
| 165 |
gsl::owner<int*> OwnedInt = Owner.getValue(); |
| 166 |
|
| 167 |
Another limitation of the current implementation is only the type based checking. |
| 168 |
Suppose you have code like the following: |
| 169 |
|
| 170 |
.. code-block:: c++ |
| 171 |
|
| 172 |
// Two owners with assigned resources |
| 173 |
gsl::owner<int*> Owner1 = new int(42); |
| 174 |
gsl::owner<int*> Owner2 = new int(42); |
| 175 |
|
| 176 |
Owner2 = Owner1; // Conceptual Leak of initial resource of Owner2! |
| 177 |
Owner1 = nullptr; |
| 178 |
|
| 179 |
The semantic of a ``gsl::owner<T*>`` is mostly like a ``std::unique_ptr<T>``, therefore |
| 180 |
assignment of two ``gsl::owner<T*>`` is considered a move, which requires that the |
| 181 |
resource ``Owner2`` must have been released before the assignment. |
| 182 |
This kind of condition could be caught in later improvements of this check with |
| 183 |
flowsensitive analysis. Currently, the `Clang Static Analyzer` catches this bug |
| 184 |
for dynamic memory, but not for general types of resources. |