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