MySQL 9.0.0
Source Code Documentation
tsid.h
Go to the documentation of this file.
1// Copyright (c) 2023, 2024, 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 designed to work 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 either included with
13// the program or referenced in the documentation.
14//
15// This program is distributed in the hope that it will be useful,
16// but WITHOUT ANY WARRANTY; without even the implied warranty of
17// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18// GNU General Public License, version 2.0, for more details.
19//
20// You should have received a copy of the GNU General Public License
21// along with this program; if not, write to the Free Software
22// Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
23
24#ifndef MYSQL_GTID_TSID_H
25#define MYSQL_GTID_TSID_H
26
29#include "mysql/gtid/tag.h"
31#include "mysql/gtid/uuid.h"
32
33/// @addtogroup GroupLibsMysqlGtid
34/// @{
35
36namespace mysql::gtid {
37
38class Tsid;
39
40/// @brief Maximum TSID text length (without null character)
41inline constexpr auto tsid_max_length = Uuid::TEXT_LENGTH + 1 + tag_max_length;
42
43struct Tsid_plain;
44
45/// @brief Represents Transaction Source Identifier which is composed of source
46/// UUID and transaction tag. Transaction tag may be empty.
47class Tsid {
48 public:
49 /// @brief Constructs TSID from a given uuid and a tag
50 /// @param[in] uuid UUID component
51 /// @param[in] tag Tag component
52 Tsid(const Uuid &uuid, const Tag &tag);
53
54 /// @brief Constructs TSID from a given uuid, tag is empty
55 /// @param[in] uuid UUID component
56 Tsid(const Uuid &uuid);
57
58 /// @brief Construct from Tsid_plain object
59 /// @param arg Source to copy from
60 explicit Tsid(const Tsid_plain &arg);
61
62 /// @brief Constructs empty TSID
63 Tsid() = default;
64 Tsid(Tsid const &) = default;
65 Tsid(Tsid &&) = default;
66 Tsid &operator=(Tsid const &) = default;
67 Tsid &operator=(Tsid &&) = default;
68
69 /// @brief Returns textual representation of Transaction Source Identifier
70 std::string to_string() const;
71
72 /// @brief Obtains textual representation of TSID and writes it to out
73 /// @param [out] out Output string
74 /// @returns Number of characters written to out
75 std::size_t to_string(char *out) const;
76
77 /// @brief Obtains textual representation of TSID and writes it to out
78 /// @details version with a custom tag-sid separator
79 /// @param [out] out Output string
80 /// @param [in] tag_sid_separator Tag-sid separator
81 /// @returns Number of characters written to out
82 std::size_t to_string(char *out, const char *tag_sid_separator) const;
83
84 /// @brief Fills Tsid with data from text
85 /// @param[in] text Encoded TSID representation terminated with null sign,
86 /// GTID separator or UUID set separator if part of the GTID set encoding
87 /// @return The number of bytes read, or 0 on error
88 [[NODISCARD]] std::size_t from_cstring(const char *text);
89
90 /// @brief Default TSID separator
91 static constexpr auto tsid_separator = ":";
92
93 /// @brief Operator ==
94 /// @param other pattern to compare against
95 /// @return Result of comparison ==
96 bool operator==(const Tsid &other) const;
97
98 /// @brief Operator !=
99 /// @param other pattern to compare against
100 /// @return Result of comparison !=
101 bool operator!=(const Tsid &other) const;
102
103 /// @brief Operator <
104 /// @details Compares uuid first. If uuids are equal, compares tags
105 /// @param other pattern to compare against
106 /// @return Result of comparison this < other
107 bool operator<(const Tsid &other) const;
108
109 /// @brief Tag accessor
110 /// @return Const reference to Tag object
111 const Tag &get_tag() const { return m_tag; }
112
113 /// @brief Tag accessor, non const (serialization)
114 /// @return Non-const Reference to Tag object
115 Tag &get_tag_ref() { return m_tag; }
116
117 /// @brief Sets internal tag to a given tag object
118 /// @param tag Source to copy from
119 void set_tag(const Tag &tag) { m_tag = tag; }
120
121 /// @brief UUID accessor
122 /// @return Const reference to UUID component of TSID
123 const Uuid &get_uuid() const { return m_uuid; }
124
125 /// @brief Non const getter is needed in some functions (copy data)
126 /// @returns Reference to internal UUID
127 Uuid &get_uuid() { return m_uuid; }
128
129 /// @brief Checks whether this TSID contains tag
130 /// @retval true This TSID contains tag
131 /// @retval false This TSID contains empty tag
132 bool is_tagged() const { return m_tag.is_defined(); }
133
134 /// @brief Structure to compute hash function of a given Tag object
135 struct Hash {
136 /// @brief Computes hash of a given Tsid object
137 /// @param arg Object handle for which hash will be calculated
138 size_t operator()(const Tsid &arg) const {
139 return Uuid_hash{}(arg.m_uuid) ^ Tag::Hash{}(arg.m_tag);
140 }
141 };
142 friend struct Hash;
143
144 /// @brief Clears data - uuid and tag
145 void clear();
146
147 /// @brief Obtains maximum length of encoded TSID (compile time)
148 /// @return Maximum length of encoded tag in bytes
149 static constexpr std::size_t get_max_encoded_length() {
151 }
152
153 /// @brief stores TSID in buffer
154 /// @param buf Buffer to store bytes
155 /// @return the number of bytes written into the buf
156 /// @param gtid_format Format of encoded GTID. If tag is not defined for this
157 /// GTID and tagged format is used, 0 will be encoded as length of the string.
158 /// In case "untagged" format is requested, function won't encode additional
159 /// tag information for untagged GTIDs. When using
160 /// untagged, tag is required to be empty.
161 std::size_t encode_tsid(unsigned char *buf,
162 const Gtid_format &gtid_format) const;
163
164 /// @brief reads TSID from the buffer
165 /// @param stream Stream to read tsid from
166 /// @param stream_len Length of the stream
167 /// @param gtid_format Gtid format expected in the stream
168 /// @return The number of bytes read or 0. 0 means that an error occurred
169 /// (e.g. not enough bytes in the buffer to read the
170 /// tsid - corrupted bytes in the buffer).
171 [[NODISCARD]] std::size_t decode_tsid(const unsigned char *stream,
172 std::size_t stream_len,
173 const Gtid_format &gtid_format);
174
175 private:
176 Uuid m_uuid = {0}; ///< GTID UUID
177 Tag m_tag; ///< GTID Tag
178};
179
180} // namespace mysql::gtid
181
182/// @}
183
184#endif // MYSQL_GTID_TSID_H
Representation of the GTID tag.
Definition: tag.h:51
bool is_defined() const
Indicates whether transaction tag is defined (is not empty)
Definition: tag.h:99
static constexpr std::size_t get_max_encoded_length()
Obtains maximum length of encoded tag (compile time)
Definition: tag.h:147
Represents Transaction Source Identifier which is composed of source UUID and transaction tag.
Definition: tsid.h:47
const Tag & get_tag() const
Tag accessor.
Definition: tsid.h:111
bool is_tagged() const
Checks whether this TSID contains tag.
Definition: tsid.h:132
Tsid(Tsid const &)=default
std::string to_string() const
Returns textual representation of Transaction Source Identifier.
Definition: tsid.cpp:34
static constexpr std::size_t get_max_encoded_length()
Obtains maximum length of encoded TSID (compile time)
Definition: tsid.h:149
Uuid m_uuid
GTID UUID.
Definition: tsid.h:176
bool operator!=(const Tsid &other) const
Operator !=.
Definition: tsid.cpp:62
Tsid & operator=(Tsid &&)=default
void clear()
Clears data - uuid and tag.
Definition: tsid.cpp:127
bool operator==(const Tsid &other) const
Operator ==.
Definition: tsid.cpp:58
Tag & get_tag_ref()
Tag accessor, non const (serialization)
Definition: tsid.h:115
Tsid & operator=(Tsid const &)=default
Uuid & get_uuid()
Non const getter is needed in some functions (copy data)
Definition: tsid.h:127
std::size_t encode_tsid(unsigned char *buf, const Gtid_format &gtid_format) const
stores TSID in buffer
Definition: tsid.cpp:97
Tsid()=default
Constructs empty TSID.
const Uuid & get_uuid() const
UUID accessor.
Definition: tsid.h:123
std::size_t from_cstring(const char *text)
Fills Tsid with data from text.
Definition: tsid.cpp:69
void set_tag(const Tag &tag)
Sets internal tag to a given tag object.
Definition: tsid.h:119
Tsid(Tsid &&)=default
Tag m_tag
GTID Tag.
Definition: tsid.h:177
std::size_t decode_tsid(const unsigned char *stream, std::size_t stream_len, const Gtid_format &gtid_format)
reads TSID from the buffer
Definition: tsid.cpp:105
bool operator<(const Tsid &other) const
Operator <.
Definition: tsid.cpp:64
static constexpr auto tsid_separator
Default TSID separator.
Definition: tsid.h:91
Definition: buf0block_hint.cc:30
Definition: global.h:35
constexpr auto tsid_max_length
Maximum TSID text length (without null character)
Definition: tsid.h:41
Gtid_format
Gtid binary format indicator.
Definition: gtid_format.h:38
constexpr std::size_t tag_max_length
Maximal number of characters in a tag.
Definition: gtid_constants.h:44
#define NODISCARD
The function attribute [[NODISCARD]] is a replacement for [[nodiscard]] to workaround a gcc bug.
Definition: nodiscard.h:47
Structure to compute hash function of a given Tag object.
Definition: tag.h:167
Structure to compute hash function of a given Tag object.
Definition: tsid.h:135
size_t operator()(const Tsid &arg) const
Computes hash of a given Tsid object.
Definition: tsid.h:138
TSID representation so that:
Definition: tsid_plain.h:41
Definition: uuid.h:195
Uuid is a trivial and of standard layout The structure contains the following components.
Definition: uuid.h:64
static const size_t TEXT_LENGTH
The number of bytes in the textual representation of a Uuid.
Definition: uuid.h:168
static constexpr std::size_t BYTE_LENGTH
The number of bytes in the data of a Uuid.
Definition: uuid.h:143