File: internal_usage.md

package info (click to toggle)
foonathan-memory 0.7-3
  • links: PTS, VCS
  • area: main
  • in suites: bullseye
  • size: 1,748 kB
  • sloc: cpp: 12,014; xml: 139; sh: 49; makefile: 22
file content (386 lines) | stat: -rw-r--r-- 12,499 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
# Writing classes using a RawAllocator

Compared to the requirements an `AllocatorAwareContainer` has to fulfill,
it is very easy to use a `RawAllocator` in a container.
There is no need to worry about comparing allocators, `select_on_container_copy_construction()`,
`propagate_on_container_move_assignment` or the undefined behavior that sometimes happens if you `swap()` a container.

## The Allocator version

To demonstrate this, consider a simple `deep_copy_ptr`. `deep_copy_ptr` is like `std::unique_ptr` but provides a copy constructor
which will perform a copy of the object.
Unlike `std::unique_ptr` it will take a full-blown `Allocator`. Then it will be transformed to use a [RawAllocator].
It is only meant to demonstrate the use of allocator classes and not to be a real use smart pointer class
(it is pretty dumb, it copies the pointee on copy but invalidates on move...).
So, this is it:

```cpp
template <typename T, class Allocator = std::allocator<T>>
class deep_copy_ptr
: Allocator
{
    using traits = std::allocator_traits<Allocator>;
public:
    using value_type = typename traits::value_type;
    using allocator_type = Allocator;

    explicit deep_copy_ptr(const allocator_type &alloc = allocator_type{})
    : allocator_type(alloc), ptr_(nullptr) {}

    deep_copy_ptr(value_type value, const allocator_type &alloc = allocator_type{})
    : allocator_type(alloc), ptr_(create(*this, std::move(value))) {}

    deep_copy_ptr(const deep_copy_ptr &other)
    : allocator_type(traits::select_on_container_copy_construction(other)),
      ptr_(create(*this, *other))
    {}

    deep_copy_ptr(deep_copy_ptr &&other) noexcept
    : allocator_type(std::move(other)),
      ptr_(other.ptr_)
    {
        other.ptr_ = nullptr;
    }

    ~deep_copy_ptr() noexcept
    {
        destroy();
    }

    deep_copy_ptr& operator=(const deep_copy_ptr &other)
    {
        if (traits::propagate_on_container_copy_assignment::value && static_cast<Allocator&>(*this) != other)
        {
            allocator_type alloc(other);
            auto ptr = create(alloc, *other);
            destroy();

            Allocator::operator=(std::move(alloc));
            ptr_ = ptr;
        }
        else
        {
            auto ptr = create(*this, *other);
            destroy();
            ptr_ = ptr;
        }
        return *this;
    }

    deep_copy_ptr& operator=(deep_copy_ptr &&other) noexcept(traits::propagate_on_container_move_assignment::value)
    {
        if (traits::propagate_on_container_move_assignment::value && static_cast<allocator_type&>(*this) != other)
        {
            allocator_type::operator=(std::move(other));
            ptr_ = other.ptr_;
            other.ptr_ = nullptr;
        }
        else if (static_cast<allocator_type&>(*this) == other)
        {
            ptr_ = other.ptr_;
            other.ptr_ = nullptr;
        }
        else
        {
            auto ptr = create(*this, std::move(*other));
            destroy();
            ptr_ = ptr;
        }
        return *this;
    }

    friend void swap(deep_copy_ptr &a, deep_copy_ptr &b) noexcept
    {
        using std::swap;
        if (traits::propagate_on_container_swap::value)
            swap(static_cast<allocator_type&>(a), static_cast<allocator_type&>(b));
        else
            assert(static_cast<allocator_type&>(a) == b);
        swap(a.ptr_, b.ptr_);
    }

    explicit operator bool() const
    {
        return !!ptr_;
    }

    T& operator*()
    {
        return *ptr_;
    }

    const T& operator*() const
    {
        return *ptr_;
    }

    typename traits::pointer operator->()
    {
        return ptr_;
    }

    typename traits::const_pointer operator->() const
    {
        return ptr_;
    }

private:
    template <typename ... Args>
    typename traits::pointer create(allocator_type &alloc, Args&&... args)
    {
        auto ptr = traits::allocate(alloc, 1);
        try
        {
            traits::construct(alloc, ptr, std::forward<Args>(args)...);
        }
        catch (...)
        {
            traits::deallocate(alloc, ptr, 1);
            throw;
        }
        return ptr;
    }

    void destroy() noexcept
    {
        if (ptr_)
        {
            traits::destroy(*this, ptr_);
            traits::deallocate(*this, ptr_, 1);
        }
    }

    typename traits::pointer ptr_;
};
```

I am not going to go into much detail about this code, since it is just to demonstrate the complexity involved with the `Allocator` model.
To note is the following:

* The `Allocator` is inherited privately to use the empty base optimization if it is an empty type.
Also the allocator is *owned* by the pointer.
* All access to the `Allocator` is done through the `std::allocator_traits` class.
In addition, the actual `value_type` and pointer must be obtained from the traits class and its appropriate functions called to construct/destroy the object.
* The copy constructor must call `traits::select_on_container_copy_construction()`, the move constructor can just move the allocator.
* Copy and Move assignment and `swap()` only exchange the container if the appropriate `traits::propagate_on_container_XXX` is `true`.
This involves a lot of complexity since if it is `false` - which is the default! - the old memory has to be deallocated on the old allocator
and the new memory allocated on the new allocator if the allocators aren't *equal* - even for move!
Also note the `assert()` in `swap()`: Since `swap()` must not throw, it cannot do the reallocation if the propagation is `false`.

## The RawAllocator version

This is now a step-by-step review of the changes in the version that uses a [RawAllocator].

```cpp
template <typename T, class RawAllocator = memory::default_allocator>
class deep_copy_ptr
: memory::allocator_reference<RawAllocator>
```
The default allocator is now [default_allocator]. Its actual type can be changed when building this library,
but it is similar to `std::allocator`.
Also the allocator is stored in a [allocator_reference].
This is recommended for three reasons:

a) Usage requirement: `RawAllocator` classes are only required to be moveable. [allocator_reference] is copyable, this allows copying the `deep_copy_ptr`.

b) Simplicity: [allocator_reference] provides the full interface without using the [allocator_traits] class.
It has already done the wrapping for you.

c) Ownership: The `deep_copy_ptr` doesn't *own* the allocator, it can be shared with other classes or objects.
This is a useful semantic change which is often required anyway.
*Note: The passed allocator object must now live as long as the container object, except for stateless allocators!*

The reference is inherited too for the same reason:
It is empty for stateless allocators. They are constructed on-the-fly.
This also means that they can be passed in as a temporary.
For stateful allocators it stores a pointer. The user has to ensure that the referenced allocator object then outlives the `deep_copy_ptr` object.

```cpp
    using allocator_ref = memory::allocator_reference<RawAllocator>;
public:
    using value_type = T;
    using allocator_type = typename allocator_ref::allocator_type;

    explicit deep_copy_ptr(allocator_ref alloc = allocator_type{})
    : allocator_ref(alloc), ptr_(nullptr) {}

    deep_copy_ptr(value_type value, allocator_ref alloc = allocator_type{})
    : allocator_ref(alloc), ptr_(create(std::move(value))) {}

    deep_copy_ptr(const deep_copy_ptr &other)
    : allocator_ref(other),
      ptr_(create(*other))
    {}

    deep_copy_ptr(deep_copy_ptr &&other) noexcept
    : allocator_ref(std::move(other)),
      ptr_(other.ptr_)
    {
        other.ptr_ = nullptr;
    }
```

Not much changed with the typedefs: The traits typedef can be removed, instead there is one for the reference.
The `value_type` is now the template parameter directly but the `allocator_type` is defined in the reference through the traits.
This allows rebinding to support `Allocator` classes.

The constructors now take an `allocator_ref` instead of the `allocator_type` directly but otherwise are left unchanged.
Note that the assignment of a default constructed `allocator_type` only compiles for stateless allocators,
since the reference does not actual store a reference to them. For stateful it wil not compile.
Since only the reference is copied and not the allocator there is no need for a special treatment in copying.
`create()` no longer needs to take an allocator as reference so this argument can be omitted.

The destructor has not changed at all, it still only calls the helper function `destroy()`.

Copy and move assignment operators can now use the copy(move)-and-swap-idiom and do not need to worry about all the propagation stuff
since the allocator is held by reference. Same goes for `swap()` which just swaps the reference and pointer.

The accessor functions have not changed, except that the actual pointer type is now simply `T*` and no longer defined in the traits.

```cpp
template <typename ... Args>
T* create(Args&&... args)
{
    auto storage = this->allocate_node(sizeof(T), alignof(T));
    try
    {
        ::new(storage) T(std::forward<Args>(args)...);
    }
    catch (...)
    {
        this->deallocate_node(storage, sizeof(T), alignof(T));
        throw;
    }
    return static_cast<T*>(storage);
}

void destroy() noexcept
{
    if (ptr_)
    {
        ptr_->~T();
        this->deallocate_node(ptr_, sizeof(T), alignof(T));
    }
}
```

The helper functions `create()` and `destroy()` no only perform the (de-)allocation through the allocator,
constructor/destructor call is done manually. Note that the pointer returned by `allocate_node()` is `void*`
and that you have to explicitly specify `this->` due to the template name lookup rules.

This is now the full `RawAllocator` version of `deep_copy_ptr`:

```cpp
template <typename T, class RawAllocator = memory::default_allocator>
class deep_copy_ptr
: memory::allocator_reference<RawAllocator>
{
    using allocator_ref = memory::allocator_reference<RawAllocator>;
public:
    using value_type = T;
    using allocator_type = typename allocator_ref::allocator_type;

    explicit deep_copy_ptr(allocator_ref alloc = allocator_type{})
    : allocator_ref(alloc), ptr_(nullptr) {}

    deep_copy_ptr(value_type value, allocator_ref alloc = allocator_type{})
    : allocator_ref(alloc), ptr_(create(std::move(value))) {}

    deep_copy_ptr(const deep_copy_ptr &other)
    : allocator_ref(other),
      ptr_(create(*other))
    {}

    deep_copy_ptr(deep_copy_ptr &&other) noexcept
    : allocator_ref(std::move(other)),
      ptr_(other.ptr_)
    {
        other.ptr_ = nullptr;
    }

    ~deep_copy_ptr() noexcept
    {
        destroy();
    }

    deep_copy_ptr& operator=(const deep_copy_ptr &other)
    {
        deep_copy_ptr tmp(other);
        swap(*this, tmp);
        return *this;
    }

    deep_copy_ptr& operator=(deep_copy_ptr &&other) noexcept
    {
        deep_copy_ptr tmp(std::move(other));
        swap(*this, tmp);
        return *this;
    }

    friend void swap(deep_copy_ptr &a, deep_copy_ptr &b) noexcept
    {
        using std::swap;
        swap(static_cast<allocator_ref&>(a), static_cast<allocator_ref&>(b));
        swap(a.ptr_, b.ptr_);
    }

    explicit operator bool() const
    {
        return !!ptr_;
    }

    T& operator*()
    {
        return *ptr_;
    }

    const T& operator*() const
    {
        return *ptr_;
    }

    T* operator->()
    {
        return ptr_;
    }

    const T* operator->() const
    {
        return ptr_;
    }

private:
    template <typename ... Args>
    T* create(Args&&... args)
    {
        auto storage = this->allocate_node(sizeof(T), alignof(T));
        try
        {
            ::new(storage) T(std::forward<Args>(args)...);
        }
        catch (...)
        {
            this->deallocate_node(storage, sizeof(T), alignof(T));
            throw;
        }
        return static_cast<T*>(storage);
    }

    void destroy() noexcept
    {
        if (ptr_)
        {
            ptr_->~T();
            this->deallocate_node(ptr_, sizeof(T), alignof(T));
        }
    }

    T *ptr_;
};
```

[default_allocator]: \ref foonathan::memory::default_allocator
[allocator_reference]: \ref foonathan::memory::allocator_reference
[allocator_traits]: \ref foonathan::memory::allocator_traits
[allocator_deallocator]: \ref foonathan::memory::allocator_deallocator
[RawAllocator]: md_doc_concepts.html#concept_rawallocator