MySQL 8.3.0
Source Code Documentation
element_map.h
Go to the documentation of this file.
1/* Copyright (c) 2015, 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#ifndef DD_CACHE__ELEMENT_MAP_INCLUDED
24#define DD_CACHE__ELEMENT_MAP_INCLUDED
25
26#include <assert.h>
27#include <cstddef> // size_t
28#include <map> // std::map
29#include <set> // std::set
30
31#include "sql/malloc_allocator.h" // Malloc_allocator.
32#include "sql/psi_memory_key.h" // key_memory_DD_cache_infrastructure
33
34namespace dd {
35namespace cache {
36
37/**
38 Implementation of a map between a key type and an element type.
39
40 The map supports storing associations between instances of the key
41 type K and pointers to the element type E. Additionally, the map provides
42 support for registering keys that have been searched for in the map
43 without being present. This allows registering a cache miss to avoid
44 situations where several similar cache misses are handled simultaneously.
45 Instead, only the first cache miss needs to be processed, while the
46 subsequent ones can just wait for the first one to complete.
47
48 There are no expectations as far as the element type E is concerned.
49 Tracking object usage, memory management, loading and evicting elements,
50 locking and synchronization, as well as registering cache misses are all
51 issues that are handled by users of this interface.
52
53 Basic assumptions regarding correct usage is implemented in terms of
54 asserts to verify that, e.g., a key does not already exist in the map
55 when it is added. There is, however, no assumptions regarding the
56 relationship between the set of missed keys and the state of the map.
57
58 There is support for representing missed keys, but the usage of this
59 feature is left to the outer layer; e.g., this class does not assert
60 that an element has been registered as missing before it is added to
61 the map.
62
63 @note The element pointer in a key/value pair may not be NULL.
64
65 @tparam K Key type.
66 @tparam E Element type (a Cache_element wrapping some dictionary
67 object type).
68*/
69
70template <typename K, typename E>
72 public:
73 typedef std::map<K, E *, std::less<K>,
75 Element_map_type; // Real map type.
76 typedef typename Element_map_type::const_iterator
77 Const_iterator; // Const iterator type.
78 typedef typename Element_map_type::iterator Iterator; // Iterator type.
79
80 private:
81 Element_map_type m_map; // The real map instance.
82 std::set<K, std::less<K>,
84 m_missed; // Cache misses being handled.
85
86 public:
88 : m_map(std::less<K>(), Malloc_allocator<std::pair<const K, E *>>(
90 m_missed(std::less<K>(),
92 } /* purecov: tested */
93
94 /**
95 Get an iterator to the beginning of the map.
96
97 Const and non-const variants.
98
99 @return Iterator to the beginning of the map.
100 */
101
102 /* purecov: begin inspected */
103 Const_iterator begin() const { return m_map.begin(); }
104 /* purecov: end */
105
106 Iterator begin() { return m_map.begin(); }
107
108 /**
109 Get an iterator to one past the end of the map.
110
111 Const and non-const variants.
112
113 @return Iterator to one past the end of the map.
114 */
115
116 /* purecov: begin inspected */
117 Const_iterator end() const { return m_map.end(); }
118 /* purecov: end */
119
120 Iterator end() { return m_map.end(); }
121
122 /**
123 Return the number of elements in the map.
124
125 @return Number of elements in the map.
126 */
127
128 size_t size() const { return m_map.size(); }
129
130 /**
131 Check if the given key is present in the map.
132
133 If the key is present in the map, return true, otherwise false.
134
135 @param key The key to look for.
136
137 @return true if present, otherwise false.
138 */
139
140 bool is_present(const K &key) const { return m_map.find(key) != m_map.end(); }
141
142 /**
143 Get the element associated with the given key.
144
145 If the element is present in the map, return a pointer to it. If the
146 element is not present, return NULL as the element pointer.
147
148 @param key The key to use for looking up the element.
149 @param [out] element The element associated with the key (if present),
150 or NULL (if not present).
151 */
152
153 void get(const K &key, E **element) const {
154 assert(element);
155 typename Element_map_type::const_iterator it = m_map.find(key);
156 if (it == m_map.end())
157 *element = nullptr;
158 else {
159 assert(it->second);
160 *element = it->second;
161 }
162 }
163
164 /**
165 Put the element into the map and associate it with the given key.
166
167 The element may not be NULL, and the key may not be already present.
168
169 @param key The key to be associated with the element.
170 @param element The element to be associated with the key.
171 */
172
173 void put(const K &key, E *element) {
174 assert(element);
175 assert(m_map.find(key) == m_map.end());
176 m_map.insert(typename Element_map_type::value_type(key, element));
177 }
178
179 /**
180 Remove an element from the map.
181
182 The key/value pair, as indicated by the key, is removed from the map.
183 The element being pointed to is not deleted. The key must be present in
184 the map.
185
186 @param key The key to be removed.
187 */
188
189 void remove(const K &key) {
190 assert(m_map.find(key) != m_map.end());
191 m_map.erase(key);
192 }
193
194 /**
195 Check if the given key has been missed in the cache.
196
197 @param key Key representing element to check for recent cache miss.
198 @return true if the element has been missed, otherwise false.
199 */
200
201 bool is_missed(const K &key) const {
202 return m_missed.find(key) != m_missed.end();
203 }
204
205 /**
206 Register the given key as being missed in the cache.
207
208 The key cannot already be reported as missing.
209
210 @param key Key representing element missed in the cache.
211 */
212
213 void set_missed(const K &key) {
214 assert(m_missed.find(key) == m_missed.end());
215 m_missed.insert(key);
216 }
217
218 /**
219 Register that the miss of a key has been handled.
220
221 The key must have been reported as missing.
222
223 @param key Key representing element previously missed in the cache.
224 */
225
226 void set_miss_handled(const K &key) {
227 assert(m_missed.find(key) != m_missed.end());
228 m_missed.erase(key);
229 }
230
231 /**
232 Debug dump of the element map to stderr.
233
234 Iterates over all elements and dumps debug information for each
235 of them.
236 */
237
238 /* purecov: begin inspected */
239 void dump() const {
240#ifndef NDEBUG
242 for (it = m_map.begin(); it != m_map.end(); it++) it->second->dump();
243#endif
244 }
245 /* purecov: end */
246};
247
248} // namespace cache
249} // namespace dd
250
251#endif // DD_CACHE__ELEMENT_MAP_INCLUDED
Malloc_allocator is a C++ STL memory allocator based on my_malloc/my_free.
Definition: malloc_allocator.h:62
Implementation of a map between a key type and an element type.
Definition: element_map.h:71
Element_map()
Definition: element_map.h:87
Element_map_type::iterator Iterator
Definition: element_map.h:78
bool is_missed(const K &key) const
Check if the given key has been missed in the cache.
Definition: element_map.h:201
bool is_present(const K &key) const
Check if the given key is present in the map.
Definition: element_map.h:140
size_t size() const
Return the number of elements in the map.
Definition: element_map.h:128
void set_missed(const K &key)
Register the given key as being missed in the cache.
Definition: element_map.h:213
Const_iterator begin() const
Get an iterator to the beginning of the map.
Definition: element_map.h:103
void get(const K &key, E **element) const
Get the element associated with the given key.
Definition: element_map.h:153
std::map< K, E *, std::less< K >, Malloc_allocator< std::pair< const K, E * > > > Element_map_type
Definition: element_map.h:75
std::set< K, std::less< K >, Malloc_allocator< K > > m_missed
Definition: element_map.h:84
Const_iterator end() const
Get an iterator to one past the end of the map.
Definition: element_map.h:117
Element_map_type::const_iterator Const_iterator
Definition: element_map.h:77
void remove(const K &key)
Remove an element from the map.
Definition: element_map.h:189
Element_map_type m_map
Definition: element_map.h:81
void put(const K &key, E *element)
Put the element into the map and associate it with the given key.
Definition: element_map.h:173
Iterator begin()
Definition: element_map.h:106
void dump() const
Debug dump of the element map to stderr.
Definition: element_map.h:239
Iterator end()
Definition: element_map.h:120
void set_miss_handled(const K &key)
Register that the miss of a key has been handled.
Definition: element_map.h:226
uint16_t value_type
Definition: vt100.h:183
The version of the current data dictionary table definitions.
Definition: dictionary_client.h:42
Definition: varlen_sort.h:174
PSI_memory_key key_memory_DD_cache_infrastructure
Definition: psi_memory_key.cc:36
required string key
Definition: replication_asynchronous_connection_failover.proto:59