tsid.h

Go to the documentation of this file.

// Copyright (c) 2023, 2025, Oracle and/or its affiliates.
//
// This program is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License, version 2.0,
// as published by the Free Software Foundation.
//
// This program is designed to work with certain software (including
// but not limited to OpenSSL) that is licensed under separate terms,
// as designated in a particular file or component or in included license
// documentation.  The authors of MySQL hereby grant you an additional
// permission to link the program and your derivative works with the
// separately licensed software that they have either included with
// the program or referenced in the documentation.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License, version 2.0, for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software
// Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA
 
#ifndef MYSQL_GTID_TSID_H
#define MYSQL_GTID_TSID_H
 
#include "mysql/gtid/gtid_constants.h"
#include "mysql/gtid/gtid_format.h"
#include "mysql/gtid/tag.h"
#include "mysql/gtid/uuid.h"
 
/// @addtogroup GroupLibsMysqlGtid
/// @{
 
namespace mysql::gtid {
 
/// @brief Maximum TSID text length (without null character)
inline constexpr auto tsid_max_length = Uuid::TEXT_LENGTH + 1 + tag_max_length;
 
struct Tsid_plain;
 
/// @brief Represents Transaction Source Identifier which is composed of source
/// UUID and transaction tag. Transaction tag may be empty.
class Tsid {
 public:
  /// @brief Constructs TSID from a given uuid and a tag
  /// @param[in] uuid UUID component
  /// @param[in] tag Tag component
  Tsid(const Uuid &uuid, const Tag &tag);
 
  /// @brief Constructs TSID from a given uuid, tag is empty
  /// @param[in] uuid UUID component
  Tsid(const Uuid &uuid);
 
  /// @brief Construct from Tsid_plain object
  /// @param arg Source to copy from
  explicit Tsid(const Tsid_plain &arg);
 
  /// @brief Constructs empty TSID
  Tsid() = default;
  Tsid(Tsid const &) = default;
  Tsid(Tsid &&) = default;
  Tsid &operator=(Tsid const &) = default;
  Tsid &operator=(Tsid &&) = default;
 
  /// @brief Returns textual representation of Transaction Source Identifier
  std::string to_string() const;
 
  /// @brief Obtains textual representation of TSID and writes it to out
  /// @param [out] out Output string
  /// @returns Number of characters written to out
  std::size_t to_string(char *out) const;
 
  /// @brief Obtains textual representation of TSID and writes it to out
  /// @details version with a custom tag-sid separator
  /// @param [out] out Output string
  /// @param [in] tag_sid_separator Tag-sid separator
  /// @returns Number of characters written to out
  std::size_t to_string(char *out, const char *tag_sid_separator) const;
 
  /// @brief Fills Tsid with data from text
  /// @param[in] text Encoded TSID representation terminated with null sign,
  /// GTID separator or UUID set separator if part of the GTID set encoding
  /// @return The number of bytes read, or 0 on error
  [[nodiscard]] std::size_t from_cstring(const char *text);
 
  /// @brief Default TSID separator
  static constexpr auto tsid_separator = ":";
 
  /// @brief Operator ==
  /// @param other pattern to compare against
  /// @return Result of comparison ==
  bool operator==(const Tsid &other) const;
 
  /// @brief Operator !=
  /// @param other pattern to compare against
  /// @return Result of comparison !=
  bool operator!=(const Tsid &other) const;
 
  /// @brief Operator <
  /// @details Compares uuid first. If uuids are equal, compares tags
  /// @param other pattern to compare against
  /// @return Result of comparison this < other
  bool operator<(const Tsid &other) const;
 
  /// @brief Tag accessor
  /// @return Const reference to Tag object
  const Tag &get_tag() const { return m_tag; }
 
  /// @brief Tag accessor, non const (serialization)
  /// @return Non-const Reference to Tag object
  Tag &get_tag_ref() { return m_tag; }
 
  /// @brief Sets internal tag to a given tag object
  /// @param tag Source to copy from
  void set_tag(const Tag &tag) { m_tag = tag; }
 
  /// @brief UUID accessor
  /// @return Const reference to UUID component of TSID
  const Uuid &get_uuid() const { return m_uuid; }
 
  /// @brief Non const getter is needed in some functions (copy data)
  /// @returns Reference to internal UUID
  Uuid &get_uuid() { return m_uuid; }
 
  /// @brief Checks whether this TSID contains tag
  /// @retval true This TSID contains tag
  /// @retval false This TSID contains empty tag
  bool is_tagged() const { return m_tag.is_defined(); }
 
  /// @brief Structure to compute hash function of a given Tag object
  struct Hash {
    /// @brief Computes hash of a given Tsid object
    /// @param arg Object handle for which hash will be calculated
    size_t operator()(const Tsid &arg) const {
      return Uuid_hash{}(arg.m_uuid) ^ Tag::Hash{}(arg.m_tag);
    }
  };
  friend struct Hash;
 
  /// @brief Clears data - uuid and tag
  void clear();
 
  /// @brief Obtains maximum length of encoded TSID (compile time)
  /// @return Maximum length of encoded tag in bytes
  static constexpr std::size_t get_max_encoded_length() {
    return Uuid::BYTE_LENGTH + Tag::get_max_encoded_length();
  }
 
  /// @brief stores TSID in buffer
  /// @param buf Buffer to store bytes
  /// @return the number of bytes written into the buf
  /// @param gtid_format Format of encoded GTID. If tag is not defined for this
  /// GTID and tagged format is used, 0 will be encoded as length of the string.
  /// In case "untagged" format is requested, function won't encode additional
  /// tag information for untagged GTIDs. When using
  /// untagged, tag is required to be empty.
  std::size_t encode_tsid(unsigned char *buf,
                          const Gtid_format &gtid_format) const;
 
  /// @brief reads TSID from the buffer
  /// @param stream Stream to read tsid from
  /// @param stream_len Length of the stream
  /// @param gtid_format Gtid format expected in the stream
  /// @return The number of bytes read or 0. 0 means that an error occurred
  /// (e.g. not enough bytes in the buffer to read the
  /// tsid - corrupted bytes in the buffer).
  [[nodiscard]] std::size_t decode_tsid(const unsigned char *stream,
                                        std::size_t stream_len,
                                        const Gtid_format &gtid_format);
 
 private:
  Uuid m_uuid = {0};  ///< GTID UUID
  Tag m_tag;          ///< GTID Tag
};
 
}  // namespace mysql::gtid
 
/// @}
 
#endif  // MYSQL_GTID_TSID_H