MySQL 8.3.0
Source Code Documentation
tag.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#ifndef MYSQL_GTID_TAG_H
24#define MYSQL_GTID_TAG_H
25
26#include <array>
27#include <cstring>
28#include <memory>
29#include <string>
30
35
36/// @addtogroup GroupLibsMysqlGtid
37/// @{
38
39namespace mysql::gtid {
40
41struct Tag_plain;
42
43/// @class Tag
44/// @brief Representation of the GTID tag
45/// @details Tag format: [a-z_]{a-z0-9_}{0,31}
46/// Tag may be created from a given text. Text may contain leading and
47/// trailing spaces which will be omitted during Tag creation. Text may also
48/// contain uppercase characters. Acceptable format for text is as follows:
49/// [:space:][a-zA-Z_][a-zA-Z0-9_]{0,31}[:space:]
50class Tag {
51 public:
52 using Tag_data = std::string;
53
54 /// @brief Constructs an empty, valid tag
55 Tag() = default;
56
57 /// @brief Construct from Tag_plain object
58 /// @param tag pattern
59 explicit Tag(const Tag_plain &tag);
60
61 /// @brief Constructs tag from a given text. If passed text is not a valid
62 /// tag representation, object remains empty (empty tag)
63 /// @param[in] text Textual representation of a tag
64 /// @see from_cstring
65 Tag(const std::string &text);
66
67 /// @brief Obtains textual representation of internal tag
68 /// @returns tag string
69 std::string to_string() const;
70
71 /// @brief Obtains textual representation of internal tag and writes it to out
72 /// @param [out] out Output string
73 /// @returns Number of characters written to out
74 std::size_t to_string(char *out) const;
75
76 /// @brief Creates Tag object from a given text. If passed text is not a valid
77 /// tag representation, object remains empty (empty tag). Text must end
78 /// with a null character or a gtid separator
79 /// @param[in] text Textual representation of a tag
80 /// @returns Number of characters read, 0 means that either tag is empty or
81 /// invalid
82 [[NODISCARD]] std::size_t from_string(const std::string &text);
83
84 /// @brief Creates Tag object from a given text. If passed text is not a valid
85 /// tag representation, object remains empty (empty tag)
86 /// Since length of text is unknown, it is expected to be null terminated
87 /// @param[in] text Textual representation of a tag
88 /// @returns Number of characters read, 0 means that either tag is empty or
89 /// invalid
90 [[NODISCARD]] std::size_t from_cstring(const char *text);
91
92 /// @brief Indicates whether transaction tag is empty
93 /// @returns Answer to question: is tag empty?
94 bool is_empty() const { return m_data.empty(); }
95
96 /// @brief Indicates whether transaction tag is defined (is not empty)
97 /// @returns Answer to question: is tag defined?
98 bool is_defined() const { return !is_empty(); }
99
100 /// @brief Operator ==
101 /// @param other pattern to compare against
102 /// @return Result of comparison ==
103 bool operator==(const Tag &other) const;
104
105 /// @brief Operator !=
106 /// @param other pattern to compare against
107 /// @return Result of comparison !=
108 bool operator!=(const Tag &other) const;
109
110 /// @brief Compares this tag with other, <
111 /// @retval true This tag is before other (alphabetical order)
112 /// @retval false Other tag is before this (alphabetical order)
113 bool operator<(const Tag &other) const {
114 return m_data.compare(other.m_data) < 0;
115 }
116
117 /// @brief stores Tag in buffer
118 /// @param buf Buffer to store bytes, must contain at least
119 /// get_encoded_length() bytes
120 /// @param gtid_format Format of encoded GTID. If tag is not defined for this
121 /// GTID and tagged format is used, 0 will be encoded as length of the string.
122 /// In case "untagged" format is requested, function won't encode additional
123 /// tag information for untagged GTIDs. When using
124 /// untagged, tag is required to be empty.
125 /// @return the number of bytes written into the buf
126 [[NODISCARD]] std::size_t encode_tag(unsigned char *buf,
127 const Gtid_format &gtid_format) const;
128
129 /// @brief returns length of encoded tag, based on defined format
130 /// @param gtid_format Format of encoded GTID. If tag is not defined for this
131 /// GTID and tagged format is used, 0 will be encoded as length of the string.
132 /// In case "untagged" format is requested, function won't encode additional
133 /// tag information for untagged GTIDs. When using
134 /// untagged, tag is required to be empty.
135 /// @return length of encoded tag in bytes
136 /// @details Note that in case encoded format is "tagged" and tag is empty,
137 /// we still to encode tag length (1 byte for length equal to 0).
138 std::size_t get_encoded_length(const Gtid_format &gtid_format) const;
139
140 /// @brief returns length of tag
141 /// @return tag length
142 std::size_t get_length() const;
143
144 /// @brief Obtains maximum length of encoded tag (compile time)
145 /// @return Maximum length of encoded tag in bytes
146 static constexpr std::size_t get_max_encoded_length() {
147 // we fix maximum size encoding to 1, since maximum tag length is 32
148 return 1 + tag_max_length;
149 }
150
151 /// @brief Reads Tag data from the buffer
152 /// @param buf Buffer to read tag from
153 /// @param buf_len Number of bytes in the buffer
154 /// @param gtid_format Gtid format read from stream, if untagged, tag
155 /// information is assumed to be empty. If tagged, gtid tag length will be
156 /// read from the stream both for untagged and tagged GTIDs
157 /// @return The number of bytes read or 0. For Gtid_format::untagged,
158 /// function will read bytes. For Gtid_format::tagged, 0 means
159 /// that an error occurred (e.g. not enough bytes in the buffer to read the
160 /// tag - corrupted bytes in the buffer).
161 [[NODISCARD]] std::size_t decode_tag(const unsigned char *buf,
162 std::size_t buf_len,
163 const Gtid_format &gtid_format);
164
165 /// @brief Structure to compute hash function of a given Tag object
166 struct Hash {
167 /// @brief Computes hash of a given Tag object
168 /// @param arg Object handle for which hash will be calculated
169 size_t operator()(const Tag &arg) const;
170 };
171
172 /// @brief Internal data accessor
173 /// @return Const reference to internal tag data
174 const Tag_data &get_data() const { return m_data; }
175
176 /// @brief Internal data accessor, non const (serialization)
177 /// @return Reference to internal tag data
178 Tag_data &get_data() { return m_data; }
179
180 protected:
181 /// @brief Checks whether current character is a valid ending of a Tag string
182 /// @param[in] character A character under test
183 /// @returns Answer to question: is character a valid tag ending?
184 static bool is_valid_end_char(const char &character);
185
186 /// @brief Checks whether current character is a valid Tag character
187 /// @param[in] character A character under test
188 /// @param[in] pos Position within a tag
189 /// @returns Answer to question: is character a valid tag character?
190 static bool is_character_valid(const char &character, std::size_t pos);
191
192 /// @brief Replaces internal tag data with a given text, includes text
193 /// normalization
194 /// @param[in] text Pattern to copy from, valid tag string
195 /// @param[in] len Number of characters to copy
196 void replace(const char *text, std::size_t len);
197
198 Tag_data m_data = ""; ///< internal tag representation
199};
200
201} // namespace mysql::gtid
202
203/// @}
204
205#endif // MYSQL_GTID_TAG_H
Representation of the GTID tag.
Definition: tag.h:50
bool operator!=(const Tag &other) const
Operator !=.
Definition: tag.cpp:141
const Tag_data & get_data() const
Internal data accessor.
Definition: tag.h:174
static bool is_character_valid(const char &character, std::size_t pos)
Checks whether current character is a valid Tag character.
Definition: tag.cpp:111
std::size_t encode_tag(unsigned char *buf, const Gtid_format &gtid_format) const
stores Tag in buffer
Definition: tag.cpp:64
bool is_defined() const
Indicates whether transaction tag is defined (is not empty)
Definition: tag.h:98
bool is_empty() const
Indicates whether transaction tag is empty.
Definition: tag.h:94
bool operator<(const Tag &other) const
Compares this tag with other, <.
Definition: tag.h:113
std::size_t get_encoded_length(const Gtid_format &gtid_format) const
returns length of encoded tag, based on defined format
Definition: tag.cpp:91
Tag_data m_data
internal tag representation
Definition: tag.h:198
static constexpr std::size_t get_max_encoded_length()
Obtains maximum length of encoded tag (compile time)
Definition: tag.h:146
void replace(const char *text, std::size_t len)
Replaces internal tag data with a given text, includes text normalization.
Definition: tag.cpp:43
bool operator==(const Tag &other) const
Operator ==.
Definition: tag.cpp:139
Tag_data & get_data()
Internal data accessor, non const (serialization)
Definition: tag.h:178
std::size_t from_string(const std::string &text)
Creates Tag object from a given text.
Definition: tag.cpp:107
std::string Tag_data
Definition: tag.h:52
Tag()=default
Constructs an empty, valid tag.
static bool is_valid_end_char(const char &character)
Checks whether current character is a valid ending of a Tag string.
Definition: tag.cpp:102
std::size_t get_length() const
returns length of tag
Definition: tag.cpp:100
std::size_t from_cstring(const char *text)
Creates Tag object from a given text.
Definition: tag.cpp:116
std::string to_string() const
Obtains textual representation of internal tag.
Definition: tag.cpp:53
std::size_t decode_tag(const unsigned char *buf, std::size_t buf_len, const Gtid_format &gtid_format)
Reads Tag data from the buffer.
Definition: tag.cpp:74
Definition: buf0block_hint.cc:29
Definition: global.h:34
Gtid_format
Gtid binary format indicator.
Definition: gtid_format.h:37
constexpr std::size_t tag_max_length
Maximal number of characters in a tag.
Definition: gtid_constants.h:43
#define NODISCARD
The function attribute [[NODISCARD]] is a replacement for [[nodiscard]] to workaround a gcc bug.
Definition: nodiscard.h:46
Structure to compute hash function of a given Tag object.
Definition: tag.h:166
size_t operator()(const Tag &arg) const
Computes hash of a given Tag object.
Definition: tag.cpp:150
Tag representation so that:
Definition: tag_plain.h:47