MySQL 8.3.0
Source Code Documentation
memory_resource.h
Go to the documentation of this file.
1/* Copyright (c) 2023, Oracle and/or its affiliates.
2
3 This program is free software; you can redistribute it and/or modify
4 it under the terms of the GNU General Public License, version 2.0,
5 as published by the Free Software Foundation.
6
7 This program is also distributed with certain software (including
8 but not limited to OpenSSL) that is licensed under separate terms,
9 as designated in a particular file or component or in included license
10 documentation. The authors of MySQL hereby grant you an additional
11 permission to link the program and your derivative works with the
12 separately licensed software that they have included with MySQL.
13
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License, version 2.0, for more details.
18
19 You should have received a copy of the GNU General Public License
20 along with this program; if not, write to the Free Software
21 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22
23/// @file memory_resource.h
24///
25/// @brief Class that wraps resources in a polymorphic manner.
26
27#ifndef MYSQL_BINLOG_EVENT_RESOURCE_MEMORY_RESOURCE_H
28#define MYSQL_BINLOG_EVENT_RESOURCE_MEMORY_RESOURCE_H
29
30#include <cstdlib>
31#include <functional>
32
33/// @addtogroup GroupLibsMysqlBinlogEvent
34/// @{
35
37
38/// Polymorphism-free memory resource class with custom allocator and
39/// deallocator functions.
40///
41/// This is used as the "back-end" for Allocator objects. The
42/// allocator and deallocator functions are member objects of type
43/// std::function, specified as constructor arguments.
44///
45/// Example: a class that needs to allocate memory, and should have a
46/// way to use a specified PSI key, can be implemented as follows:
47///
48/// - For each type the class needs to allocate, it has one member
49/// object of type Allocator. The constructor takes a
50/// Memory_resource parameter, which defaults to a
51/// default-constructed Memory_resource. The constructor passes the
52/// Memory_resource to the Allocator constructors. The class calls
53/// the Allocator member functions for its memory management.
54///
55/// - API clients that don't need a PSI key don't need to pass a
56/// Memory_resource to the constructor; they use the default value
57/// for the parameter. API clients that need a PSI key, pass a
58/// Memory_resource object where the allocate/deallocate functions
59/// are PSI-enabled. Such a Memory_resource object can be obtained
60/// from the factory function @c psi_memory_resource in
61/// sql/psi_memory_resource.h.
62///
63/// Notes on design choices:
64///
65/// We avoid using polymorphism to configure the behavior of the
66/// allocate/deallocate member functions. Classes that use
67/// polymorphic memory resources would have to take a reference or
68/// pointer to the memory resource as argument, so either the class
69/// can't own the memory resource or it has to be dynamically
70/// allocated. If the class can't own the memory resource, it
71/// complicates the usage since the caller has to ensure the
72/// Memory_resource outlives the class that uses it. If the
73/// Memory_resource has to be allocated dynamically, that allocation
74/// cannot use a custom Memory_resource, which may defeat the purpose
75/// of using custom Memory_resources to track all allocations.
76///
77/// We also avoid static polymorphism, since every user of a
78/// statically polymorphic Memory_resource would have to be a
79/// template, which has two problems: first, two classes with the same
80/// behavior but different allocation strategies would be different
81/// types. Second, any class that allocates memory and has a
82/// requirement that the API client can configure the Memory_resource,
83/// has to be templated and therefore be defined in a header.
84///
85/// With the current solution, the caller just creates a
86/// Memory_resource object and passes it to the allocator.
88 public:
89 using Size_t = std::size_t;
90 using Ptr_t = void *;
91 using Allocator_t = std::function<Ptr_t(Size_t)>;
92 using Deallocator_t = std::function<void(Ptr_t)>;
93
94 /// Construct a new Memory_resource that uses the given allocator
95 /// and deallocator.
96 ///
97 /// @param allocator The allocator, e.g. std::malloc or my_malloc.
98 ///
99 /// @param deallocator The deallocator, e.g. std::free or my_free.
100 Memory_resource(const Allocator_t &allocator,
101 const Deallocator_t &deallocator)
102 : m_allocator(allocator), m_deallocator(deallocator) {}
103
104 /// Construct a new Memory_resource that uses std::malloc and std::free.
106
107 /// Allocate memory using the provided allocator.
108 ///
109 /// @param n The size.
110 ///
111 /// @return The new memory.
112 void *allocate(Size_t n) const { return m_allocator(n); }
113
114 /// Deallocate memory using the provided deallocator.
115 ///
116 /// @param p The pointer.
117 void deallocate(Ptr_t p) const { m_deallocator(p); }
118
119 /// Return the deallocator.
121
122 private:
123 /// The allocator object.
125
126 /// The deallocator object.
128};
129
130} // namespace mysql::binlog::event::resource
131
132/// @}
133
134#endif // MYSQL_BINLOG_EVENT_RESOURCE_MEMORY_RESOURCE_H
Polymorphism-free memory resource class with custom allocator and deallocator functions.
Definition: memory_resource.h:87
std::function< void(Ptr_t)> Deallocator_t
Definition: memory_resource.h:92
const Deallocator_t m_deallocator
The deallocator object.
Definition: memory_resource.h:127
void * Ptr_t
Definition: memory_resource.h:90
const Allocator_t m_allocator
The allocator object.
Definition: memory_resource.h:124
void deallocate(Ptr_t p) const
Deallocate memory using the provided deallocator.
Definition: memory_resource.h:117
Memory_resource()
Construct a new Memory_resource that uses std::malloc and std::free.
Definition: memory_resource.h:105
std::size_t Size_t
Definition: memory_resource.h:89
Deallocator_t get_deallocator() const
Return the deallocator.
Definition: memory_resource.h:120
void * allocate(Size_t n) const
Allocate memory using the provided allocator.
Definition: memory_resource.h:112
Memory_resource(const Allocator_t &allocator, const Deallocator_t &deallocator)
Construct a new Memory_resource that uses the given allocator and deallocator.
Definition: memory_resource.h:100
std::function< Ptr_t(Size_t)> Allocator_t
Definition: memory_resource.h:91
const char * p
Definition: ctype-mb.cc:1234
#define malloc(A)
Definition: lexyy.cc:914
#define free(A)
Definition: lexyy.cc:915
Definition: allocator.h:39
Definition: varlen_sort.h:174
int n
Definition: xcom_base.cc:508