MySQL 8.3.0
Source Code Documentation
gtidset.h
Go to the documentation of this file.
1/* Copyright (c) 2021, 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 MYSQL_GTID_GTID_SET_H
24#define MYSQL_GTID_GTID_SET_H
25
26#include <cstddef>
27#include <map>
28#include <set>
29#include <sstream>
30
32#include "mysql/gtid/global.h"
33#include "mysql/gtid/gtid.h"
34#include "mysql/gtid/tag.h"
35#include "mysql/gtid/tsid.h"
36
37/// @addtogroup GroupLibsMysqlGtid
38/// @{
39
40namespace mysql::gtid {
41
42/**
43 * @brief This class represents a range of transaction identifiers.
44 *
45 * A transaction identifier is composed of two parts, the UUID and the sequence
46 * number.
47 *
48 * There can be multiple transaction identifiers for a given UUID. When their
49 * sequence number are contiguous they can be represented as an interval. This
50 * is the class that represents on of those intervals.
51 *
52 */
54 public:
55 /// In 'UUID:GNO-GNO', this is the '-'
56 static const inline std::string SEPARATOR_GNO_START_END{"-"};
57
58 private:
61
62 public:
63 virtual ~Gno_interval() = default;
64
65 /**
66 * @brief Copy assignment.
67 *
68 * @note This operator does not perform any check about the other interval
69 * being valid or not. It is up to the caller to verify that if needed.
70 *
71 * @param other The other interval to copy.
72 * @return Gno_interval& a reference to the copied interval.
73 */
74 Gno_interval &operator=(const Gno_interval &other);
75
76 /**
77 * @brief Construct a new Gno_interval object from the other one provided.
78 *
79 * @note This operator does not perform any check about the other interval
80 * being valid or not. It is up to the caller to verify that if needed.
81 *
82 * @param other The object to copy.
83 */
84 Gno_interval(const Gno_interval &other);
85
86 /**
87 * @brief Compares this interval with another one. Returns true if there is a
88 * match.
89 *
90 * @note This operator does not perform any check about the other interval
91 * being valid or not. It is up to the caller to verify that if needed, before
92 * calling this member function.
93 *
94 * @param other The other interval to compare this one with.
95 * @return true If both intervals match.
96 * @return false If intervals do not match.
97 */
98 virtual bool operator==(const Gno_interval &other) const;
99
100 /**
101 * @brief Construct a new Gno_interval object.
102 *
103 * @param start The start of the interval (inclusive).
104 * @param end The end of the interval (inclusive).
105 */
107
108 /**
109 * @brief Establishes a total order between two intervals.
110 *
111 * Total order is determined using the start and end values of
112 * the interval.
113 *
114 * An interval A comes before interval B if its start value is smaller
115 * than the start value of B.
116 *
117 * If B's start value is smaller than A's start value then B comes
118 * before A.
119 *
120 * If A and B have the same start value, the the end of the intervals
121 * are checked and if A has a lower interval end than B, then A is
122 * considered to come before B in that case.
123 *
124 * @note This operator does not perform any check about the other interval
125 * being valid or not. It is up to the caller to verify that if needed, before
126 * calling this member function.
127 *
128 * @param other the other interval.
129 * @return true if this is smaller than the other
130 * @return false if this is equal or greater than the other.
131 */
132 virtual bool operator<(const Gno_interval &other) const;
133
134 /**
135 * @brief This checks whether this interval intersects with the other.
136 *
137 * @note This operator does not perform any check about the other interval
138 * being valid or not. It is up to the caller to verify that if needed, before
139 * calling this member function.
140 *
141 * @param other The other interval to check against this one.
142 * @return true if the intervals intersect.
143 * @return false if it does not intersect.
144 */
145 virtual bool intersects(const Gno_interval &other) const;
146
147 /**
148 * @brief Checks if this interval is contiguous with the other one.
149 *
150 * Two intervals are contiguous if they do not intersect but there
151 * are no gaps between them. No gaps means that the upper limit of
152 * interval A is the value immediately preceding the lower limit
153 * of interval B, under numeric natural ordering.
154 *
155 * @note This operator does not perform any check about the other interval
156 * being valid or not. It is up to the caller to verify that if needed, before
157 * calling this member function.
158 *
159 * @param other the interval to check against.
160 * @return true if the intervals are contiguous.
161 * @return false otherwise.
162 */
163 virtual bool contiguous(const Gno_interval &other) const;
164
165 /**
166 * @brief Checks if the other interval intersects or is contiguous with this
167 * one.
168 *
169 * @param other The interval to check against this one.
170 * @return true if the other interval intersects or is contiguous with this
171 * one.
172 * @return false otherwise.
173 */
174 virtual bool intersects_or_contiguous(const Gno_interval &other) const;
175
176 /**
177 * @brief Adds the other interval to this one.
178 *
179 * For this operation to complete successfully, the intervals must
180 * intersect or be contiguous. Otherwise, the operation will fail.
181 *
182 * @note This operator does not perform any check about the other interval
183 * being valid or not. It is up to the caller to verify that if needed, before
184 * calling this member function.
185 *
186 * @param other The interval to add to this one.
187 * @return true if the adding was not successful.
188 * @return false if the adding was successful.
189 */
190 virtual bool add(const Gno_interval &other);
191
192 /**
193 * @brief Gets the first sequence number in the interval.
194 *
195 * @return the first sequence number of the interval.
196 */
197 virtual gno_t get_start() const;
198
199 /**
200 * @brief Gets the last sequence number in the interval.
201 *
202 * @return the last sequence number in the interval.
203 */
204 virtual gno_t get_end() const;
205
206 /**
207 * @brief Number of entries in this interval.
208 *
209 * @return the size of the interval.
210 */
211 virtual std::size_t count() const;
212
213 /**
214 * @brief Gets a human readable representation of this identifier.
215 *
216 * @return A human readable representation of this identifier.
217 */
218 virtual std::string to_string() const;
219
220 /**
221 * @brief Checks whether this interval is valid or not.
222 *
223 * An interval is invalid if the start value is smaller than 0 or
224 * if the start is larger than the end of the interval.
225 *
226 * @return true if the interval is valid, false otherwise.
227 */
228 virtual bool is_valid() const;
229};
230
231/**
232 * @brief This class represents a set of transaction identifiers.
233 *
234 * A set of transaction identifiers contains zero or more entries. When there
235 * are multiple entries, there can multiple intervals as well. Different
236 * intervals may share the same UUID part or not. This class abstracts that
237 * in-memory representation.
238 *
239 */
240class Gtid_set {
241 public:
242 static const inline std::string empty_gtid_set_str{""};
243 /// In 'UUID:INTERVAL:INTERVAL', this is the second ':'
244 static const inline std::string separator_interval{":"};
245 /// In 'SID:GNO,SID:GNO', this is the ','
246 static const inline std::string separator_uuid_set{","};
249
250 protected:
251 [[NODISCARD]] virtual bool do_add(const Tsid &tsid,
252 const Gno_interval &interval);
253 [[NODISCARD]] virtual bool do_add(const Uuid &uuid, const Tag &tag,
254 const Gno_interval &interval);
255
256 public:
257 /**
258 * @brief Tsid_interval_map is a 2-level map between tsids and an ordered
259 * set of Gno_intervals.
260 * Uuid is mapped into GTID tags, each pair of Uuid and Tag (TSID) is mapped
261 * into ordered set of gno intervals
262 */
263 using Interval_set = std::set<Gno_interval>;
264 using Tag_interval_map = std::map<Tag, Interval_set>;
265 using Tsid_interval_map = std::map<Uuid, Tag_interval_map>;
266
267 Gtid_set() = default;
268 virtual ~Gtid_set();
269
270 Gtid_set(const Gtid_set &other) = delete;
271
272 /**
273 * @brief Copy assignment.
274 *
275 * @note This operator does not check whether the parameters are valid
276 * or not. The caller should perform such check before calling this member
277 * function.
278 *
279 * @param other the Gtid_set to be copied over to this one.
280 * @return Gtid_set& a reference to the copied Gtid_set.
281 */
282 Gtid_set &operator=(const Gtid_set &other);
283
284 /**
285 * @brief Compares this set with another one.
286 *
287 * @param other The other set to compare this one with.
288 * @return true If both sets match.
289 * @return false If sets do not match.
290 */
291 virtual bool operator==(const Gtid_set &other) const;
292
293 /**
294 * @brief Iterates through recorded TSIDs and returns
295 * format of the Gtid_set
296 *
297 * @return Format of this GTID set
298 * @see Gtid_format
299 */
300 virtual Gtid_format get_gtid_set_format() const;
301
302 /**
303 * @brief Adds a new interval indexed by the given uuid.
304 *
305 * @note This member function does not check whether the parameters are valid
306 * or not. The caller should perform such check before calling this member
307 * function.
308 *
309 * @return true if the there was an error adding the interval, false
310 * otherwise.
311 */
312 [[NODISCARD]] virtual bool add(const Tsid &tsid,
313 const Gno_interval &interval);
314
315 /**
316 * @brief Gets a copy of the internal set.
317 *
318 * @return an internal copy of the given set.
319 */
320 virtual const Tsid_interval_map &get_gtid_set() const;
321
322 /**
323 * @brief Add a set of identifiers to this one.
324 *
325 * @note This member function does not check whether the parameters are valid
326 * or not. The caller should perform such check before calling this member
327 * function.
328 *
329 * @param other the set to add to this one.
330 * @return true if there was a failure adding the gtids.
331 * @return false otherwise.
332 */
333 virtual bool add(const Gtid_set &other);
334
335 /**
336 * @brief Get the num TSIDs held in the GTID set
337 *
338 * @return std::size_t Number of TSIDs
339 */
340 virtual std::size_t get_num_tsids() const;
341
342 /**
343 * @brief Adds the given identifier to this set.
344 *
345 * @note This member function does not check whether the parameters are valid
346 * or not. The caller should perform such check before calling this member
347 * function.
348 *
349 * @param gtid the identifier to add.
350 * @return true if it failed while adding the identifier.
351 * @return false otherwise.
352 */
353 virtual bool add(const Gtid &gtid);
354
355 /**
356 * @brief Checks whether this set contains the given identifier.
357 *
358 * @note This member function does not check whether the parameters are valid
359 * or not. The caller should perform such check before calling this member
360 * function.
361 *
362 * @param gtid the gtid to check whehther it exists in this set or not.
363 * @return true if the identifier exists in this set.
364 * @return false if the identifier does not exist in this set.
365 */
366 virtual bool contains(const Gtid &gtid) const;
367
368 /**
369 * @brief A human readable representation of this set.
370 *
371 * @return a human readable representation of this set.
372 */
373 virtual std::string to_string() const;
374
375 /**
376 * @brief Resets this set, making it empty.
377 *
378 */
379 virtual void reset();
380
381 /**
382 * @brief Returns true if this is an empty set.
383 *
384 * @return true
385 * @return false
386 */
387 virtual bool is_empty() const;
388
389 /**
390 * @brief Gets the number of entries in this set.
391 *
392 * @return the cardinality of this set.
393 */
394 virtual std::size_t count() const;
395
396 protected:
397 /**
398 * @brief An ordered map of entries mapping Uuid to a list of intervals.
399 */
401};
402
403} // namespace mysql::gtid
404
405/// @}
406
407#endif // MYSQL_GTID_GTID_SET_H
This class represents a range of transaction identifiers.
Definition: gtidset.h:53
virtual bool intersects_or_contiguous(const Gno_interval &other) const
Checks if the other interval intersects or is contiguous with this one.
Definition: gtidset.cpp:74
virtual bool operator==(const Gno_interval &other) const
Compares this interval with another one.
Definition: gtidset.cpp:45
static const std::string SEPARATOR_GNO_START_END
In 'UUID:GNO-GNO', this is the '-'.
Definition: gtidset.h:56
gno_t m_start
Definition: gtidset.h:59
virtual ~Gno_interval()=default
Gno_interval(const Gno_interval &other)
Construct a new Gno_interval object from the other one provided.
Definition: gtidset.cpp:36
virtual gno_t get_start() const
Gets the first sequence number in the interval.
Definition: gtidset.cpp:78
virtual std::string to_string() const
Gets a human readable representation of this identifier.
Definition: gtidset.cpp:90
gno_t m_next_gno_after_end
Definition: gtidset.h:60
Gno_interval & operator=(const Gno_interval &other)
Copy assignment.
Definition: gtidset.cpp:39
virtual bool intersects(const Gno_interval &other) const
This checks whether this interval intersects with the other.
Definition: gtidset.cpp:58
virtual bool add(const Gno_interval &other)
Adds the other interval to this one.
Definition: gtidset.cpp:81
virtual gno_t get_end() const
Gets the last sequence number in the interval.
Definition: gtidset.cpp:79
virtual std::size_t count() const
Number of entries in this interval.
Definition: gtidset.cpp:29
virtual bool operator<(const Gno_interval &other) const
Establishes a total order between two intervals.
Definition: gtidset.cpp:50
virtual bool contiguous(const Gno_interval &other) const
Checks if this interval is contiguous with the other one.
Definition: gtidset.cpp:68
virtual bool is_valid() const
Checks whether this interval is valid or not.
Definition: gtidset.cpp:99
This class represents a set of transaction identifiers.
Definition: gtidset.h:240
virtual std::size_t count() const
Gets the number of entries in this set.
Definition: gtidset.cpp:276
virtual std::string to_string() const
A human readable representation of this set.
Definition: gtidset.cpp:224
Gtid_set(const Gtid_set &other)=delete
static const std::string separator_uuid_set
In 'SID:GNO,SID:GNO', this is the ','.
Definition: gtidset.h:246
virtual bool operator==(const Gtid_set &other) const
Compares this set with another one.
Definition: gtidset.cpp:112
virtual bool do_add(const Tsid &tsid, const Gno_interval &interval)
Definition: gtidset.cpp:158
std::map< Uuid, Tag_interval_map > Tsid_interval_map
Definition: gtidset.h:265
std::set< Gno_interval > Interval_set
Tsid_interval_map is a 2-level map between tsids and an ordered set of Gno_intervals.
Definition: gtidset.h:263
static const std::string separator_interval
In 'UUID:INTERVAL:INTERVAL', this is the second ':'.
Definition: gtidset.h:244
virtual Gtid_format get_gtid_set_format() const
Iterates through recorded TSIDs and returns format of the Gtid_set.
Definition: gtidset.cpp:292
static const std::string empty_gtid_set_str
Definition: gtidset.h:242
virtual bool add(const Tsid &tsid, const Gno_interval &interval)
Adds a new interval indexed by the given uuid.
Definition: gtidset.cpp:204
virtual void reset()
Resets this set, making it empty.
Definition: gtidset.cpp:290
virtual const Tsid_interval_map & get_gtid_set() const
Gets a copy of the internal set.
Definition: gtidset.cpp:154
virtual bool contains(const Gtid &gtid) const
Checks whether this set contains the given identifier.
Definition: gtidset.cpp:251
virtual bool is_empty() const
Returns true if this is an empty set.
Definition: gtidset.cpp:274
std::map< Tag, Interval_set > Tag_interval_map
Definition: gtidset.h:264
Tsid_interval_map m_gtid_set
An ordered map of entries mapping Uuid to a list of intervals.
Definition: gtidset.h:400
Gtid_set & operator=(const Gtid_set &other)
Copy assignment.
Definition: gtidset.cpp:105
virtual std::size_t get_num_tsids() const
Get the num TSIDs held in the GTID set.
Definition: gtidset.cpp:266
Represents a MySQL Global Transaction Identifier.
Definition: gtid.h:50
Representation of the GTID tag.
Definition: tag.h:50
Represents Transaction Source Identifier which is composed of source UUID and transaction tag.
Definition: tsid.h:46
static void start(mysql_harness::PluginFuncEnv *env)
Definition: http_auth_backend_plugin.cc:176
static int interval
Definition: mysqladmin.cc:69
Definition: global.h:34
Gtid_format
Gtid binary format indicator.
Definition: gtid_format.h:37
std::int64_t gno_t
Definition: global.h:36
#define NODISCARD
The function attribute [[NODISCARD]] is a replacement for [[nodiscard]] to workaround a gcc bug.
Definition: nodiscard.h:46
mysql::gtid::Tsid Tsid
Definition: rpl_gtid_state.cc:55
Uuid is a trivial and of standard layout The structure contains the following components.
Definition: uuid.h:63