MySQL 8.1.0
Source Code Documentation
gcs_internal_message.h
Go to the documentation of this file.
1/* Copyright (c) 2016, 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 GCS_MSG_H
24#define GCS_MSG_H
25
26#include <cassert>
27#include <cstdlib>
28#include <memory>
29#include <sstream>
30#include <unordered_set>
31#include <vector>
34
36
38
39/**
40 Deleter for objects managed by a std::unique_ptr that were allocated using
41 the malloc family of functions instead of the new operator.
42 */
44 void operator()(unsigned char *buffer) const { std::free(buffer); }
45};
46
47/**
48 This class is an abstraction for the packet concept. It is used to manipulate
49 the contents of a buffer that is to be sent to the network in an optimal way.
50
51 The on-the-wire layout looks like this:
52
53 +--------------+-----------------+----------------+-----------+
54 | fixed header | dynamic headers | stage metadata | payload |
55 +--------------+-----------------+----------------+-----------+
56 */
58 public:
59 using buffer_ptr = std::unique_ptr<unsigned char, Gcs_packet_buffer_deleter>;
60
61 private:
62 /**
63 Fixed header which is common regardless whether the packet has been
64 changed by a stage or not.
65 */
67
68 /**
69 List of dynamic headers created by the stages by which the packet has
70 passed through and changed it.
71 */
72 std::vector<Gcs_dynamic_header> m_dynamic_headers;
73
74 /**
75 List of stage metadata created by the stages by which the packet has passed
76 through.
77 This list always has the same length as m_dynamic_headers, and the
78 following holds:
79
80 For every i, m_stage_metadata[i] and m_dynamic_headers[i] correspond to
81 the same stage.
82 */
83 std::vector<std::unique_ptr<Gcs_stage_metadata>> m_stage_metadata;
84
85 /**
86 Index of the next stage to apply/revert in both m_dynamic_headers and
87 m_stage_metadata.
88 */
89 std::size_t m_next_stage_index{0};
90
91 /**
92 The buffer containing all serialized data for this packet.
93 */
95
96 /**
97 The capacity of the serialization buffer.
98 */
99 unsigned long long m_serialized_packet_size{0};
100
101 /**
102 The offset in m_serialized_packet where the application payload starts.
103 */
105
106 /**
107 The size of the serialized application payload in m_serialized_packet.
108 */
109 unsigned long long m_serialized_payload_size{0};
110
111 /**
112 The size of the serialized m_stage_metadata in m_serialized_packet.
113 */
114 unsigned long long m_serialized_stage_metadata_size{0};
115
116 /**
117 The XCom synode in which this packet was delivered.
118 */
120
121 /**
122 The XCom synode in which this packet was delivered.
123 */
125
126 public:
127 /**
128 This factory method is to be used when sending a packet.
129
130 @param cargo The message type
131 @param current_version The pipeline version
132 @param dynamic_headers The dynamic headers of the stages the packet will go
133 through
134 @param stage_metadata The stage metadata of the stages the packet will go
135 through
136 @param payload_size The payload size
137 @retval {true, Gcs_packet} If packet is created successfully
138 @retval {false, _} If memory could not be allocated
139 */
140 static std::pair<bool, Gcs_packet> make_outgoing_packet(
141 Cargo_type const &cargo, Gcs_protocol_version const &current_version,
142 std::vector<Gcs_dynamic_header> &&dynamic_headers,
143 std::vector<std::unique_ptr<Gcs_stage_metadata>> &&stage_metadata,
144 unsigned long long const &payload_size);
145
146 /**
147 This factory method is to be used when modifying a packet. This builds a
148 packet with all the same headers, metadata, and state of @c original_packet.
149
150 It is used, for example, by:
151 - The compression stage of the pipeline, to derive the compressed packet from
152 the original, uncompressed packet.
153 - The fragmentation stage of the pipeline, to derive the fragments from the
154 original packet.
155
156 @param original_packet The packet to "clone"
157 @param new_payload_size The payload size of this packet
158 @retval {true, Gcs_packet} If packet is created successfully
159 @retval {false, _} If memory could not be allocated
160 */
161 static std::pair<bool, Gcs_packet> make_from_existing_packet(
162 Gcs_packet const &original_packet,
163 unsigned long long const &new_payload_size);
164
165 /**
166 This factory method is to be used when receiving a packet from the network.
167
168 @param buffer Buffer with a serialized packet
169 @param buffer_size Size of the buffer
170 @param delivery_synode The XCom synode where the packet was decided on
171 @param origin_synode The XCom synode that identifies the origin of the packet
172 @param pipeline The message pipeline
173 @returns A packet initialized from the buffer
174 */
176 unsigned long long buffer_size,
177 synode_no const &delivery_synode,
178 synode_no const &origin_synode,
179 Gcs_message_pipeline const &pipeline);
180
181 Gcs_packet() noexcept;
182
183 /**
184 These constructors are to be used when move semantics may be needed.
185 */
186 Gcs_packet(Gcs_packet &&packet) noexcept;
187 Gcs_packet &operator=(Gcs_packet &&packet) noexcept;
188
189 Gcs_packet(const Gcs_packet &packet) = delete;
190 Gcs_packet &operator=(const Gcs_packet &packet) = delete;
191
192 /**
193 Retrieve this packet's header.
194 @returns The packet's header
195 */
197
198 /**
199 Retrieve this packet's dynamic headers.
200 @returns The packet's dynamic headers
201 */
203
204 /**
205 Retrieve this packet's stage metadata.
206 @returns The packet's stage metadata
207 */
209 const;
210
211 std::size_t const &get_next_stage_index() const;
212
215
217
219
220 unsigned char *get_payload_pointer();
221
222 void set_payload_length(unsigned long long const &new_length);
223
224 /**
225 Return the value of the maximum supported version.
226 */
228
229 /**
230 Return the value of the version in use.
231 */
233
234 /**
235 Return the cargo type.
236 */
238
239 /**
240 Return the total length.
241 */
242 unsigned long long get_total_length() const;
243
244 /**
245 Return the payload length.
246 */
247 unsigned long long const &get_payload_length() const;
248
249 /**
250 Encode the packet content into its serialization buffer, and release
251 ownership of the serialization buffer.
252
253 This method must only be called on a valid packet, i.e. a packet for which
254 @c allocate_serialization_buffer was called and returned true.
255
256 @retval {buffer, buffer_size} The buffer with the serialized packet, and
257 its size
258 */
259 std::pair<buffer_ptr, unsigned long long> serialize();
260
261 /**
262 Create a string representation of the packet to be logged.
263
264 @param output Reference to the output stream where the string will be
265 created.
266 */
267 void dump(std::ostringstream &output) const;
268
270
271 Gcs_xcom_synode const &get_origin_synode() const;
272
273 private:
274 /**
275 Constructor called by @c make_to_send.
276
277 @param cargo The message type
278 @param current_version The pipeline version
279 @param dynamic_headers The dynamic headers of the stages the packet will go
280 through
281 @param stage_metadata The stage metadata of the stages the packet will go
282 through
283 @param payload_size The payload size
284 */
285 explicit Gcs_packet(
286 Cargo_type const &cargo, Gcs_protocol_version const &current_version,
287 std::vector<Gcs_dynamic_header> &&dynamic_headers,
288 std::vector<std::unique_ptr<Gcs_stage_metadata>> &&stage_metadata,
289 unsigned long long const &payload_size);
290
291 /**
292 Constructor called by @c make_from_existing_packet.
293
294 @param original_packet The packet to "clone"
295 @param new_payload_size The payload size of this packet
296 */
297 explicit Gcs_packet(Gcs_packet const &original_packet,
298 unsigned long long const &new_payload_size);
299
300 /**
301 Constructor called by @c make_from_serialized_buffer.
302
303 @param delivery_synode The XCom synode where the packet was decided on
304 @param origin_synode The XCom synode that identifieis the origin of this
305 packet
306 */
307 explicit Gcs_packet(synode_no const &delivery_synode,
308 synode_no const &origin_synode);
309
310 /**
311 Allocates the underlying buffer where the packet will be serialized to using
312 @c serialize.
313
314 @returns true if the required buffer could not be allocated, false otherwise
315 */
317
318 /**
319 Decode the packet content from the given buffer containing a serialized
320 packet.
321
322 @param buffer Buffer containing a serialized packet
323 @param buffer_size Size of the buffer
324 @param pipeline The message pipeline
325 */
326 void deserialize(buffer_ptr &&buffer, unsigned long long buffer_size,
327 Gcs_message_pipeline const &pipeline);
328};
329
330#endif // GCS_MSG_H
This is a default header created per stage and contains information to decode it.
Definition: gcs_internal_message_headers.h:426
This header is internal to the MySQL GCS library and contains metadata information about the message ...
Definition: gcs_internal_message_headers.h:178
This is the pipeline that an outgoing or incoming message has to go through when being sent to or rec...
Definition: gcs_message_stages.h:364
This class is an abstraction for the packet concept.
Definition: gcs_internal_message.h:57
static std::pair< bool, Gcs_packet > make_from_existing_packet(Gcs_packet const &original_packet, unsigned long long const &new_payload_size)
This factory method is to be used when modifying a packet.
Definition: gcs_internal_message.cc:98
void set_payload_length(unsigned long long const &new_length)
Definition: gcs_internal_message.cc:247
Gcs_internal_message_header m_fixed_header
Fixed header which is common regardless whether the packet has been changed by a stage or not.
Definition: gcs_internal_message.h:66
buffer_ptr m_serialized_packet
The buffer containing all serialized data for this packet.
Definition: gcs_internal_message.h:94
std::vector< Gcs_dynamic_header > m_dynamic_headers
List of dynamic headers created by the stages by which the packet has passed through and changed it.
Definition: gcs_internal_message.h:72
Gcs_protocol_version get_used_version() const
Return the value of the version in use.
Definition: gcs_internal_message.cc:257
std::size_t m_serialized_payload_offset
The offset in m_serialized_packet where the application payload starts.
Definition: gcs_internal_message.h:104
std::vector< Gcs_dynamic_header > const & get_dynamic_headers() const
Retrieve this packet's dynamic headers.
Definition: gcs_internal_message.cc:217
void prepare_for_next_outgoing_stage()
Definition: gcs_internal_message.cc:231
static std::pair< bool, Gcs_packet > make_outgoing_packet(Cargo_type const &cargo, Gcs_protocol_version const &current_version, std::vector< Gcs_dynamic_header > &&dynamic_headers, std::vector< std::unique_ptr< Gcs_stage_metadata > > &&stage_metadata, unsigned long long const &payload_size)
This factory method is to be used when sending a packet.
Definition: gcs_internal_message.cc:42
void dump(std::ostringstream &output) const
Create a string representation of the packet to be logged.
Definition: gcs_internal_message.cc:374
std::size_t m_next_stage_index
Index of the next stage to apply/revert in both m_dynamic_headers and m_stage_metadata.
Definition: gcs_internal_message.h:89
Gcs_xcom_synode m_delivery_synode
The XCom synode in which this packet was delivered.
Definition: gcs_internal_message.h:119
unsigned long long const & get_payload_length() const
Return the payload length.
Definition: gcs_internal_message.cc:269
Gcs_xcom_synode const & get_origin_synode() const
Definition: gcs_internal_message.cc:390
Gcs_xcom_synode const & get_delivery_synode() const
Definition: gcs_internal_message.cc:386
Gcs_packet() noexcept
Definition: gcs_internal_message.cc:29
static Gcs_packet make_incoming_packet(buffer_ptr &&buffer, unsigned long long buffer_size, synode_no const &delivery_synode, synode_no const &origin_synode, Gcs_message_pipeline const &pipeline)
This factory method is to be used when receiving a packet from the network.
Definition: gcs_internal_message.cc:142
Gcs_xcom_synode m_origin_synode
The XCom synode in which this packet was delivered.
Definition: gcs_internal_message.h:124
Gcs_stage_metadata & get_current_stage_header()
Definition: gcs_internal_message.cc:239
std::vector< std::unique_ptr< Gcs_stage_metadata > > const & get_stage_metadata() const
Retrieve this packet's stage metadata.
Definition: gcs_internal_message.cc:223
void deserialize(buffer_ptr &&buffer, unsigned long long buffer_size, Gcs_message_pipeline const &pipeline)
Decode the packet content from the given buffer containing a serialized packet.
Definition: gcs_internal_message.cc:323
unsigned long long m_serialized_payload_size
The size of the serialized application payload in m_serialized_packet.
Definition: gcs_internal_message.h:109
std::vector< std::unique_ptr< Gcs_stage_metadata > > m_stage_metadata
List of stage metadata created by the stages by which the packet has passed through.
Definition: gcs_internal_message.h:83
unsigned long long m_serialized_stage_metadata_size
The size of the serialized m_stage_metadata in m_serialized_packet.
Definition: gcs_internal_message.h:114
std::unique_ptr< unsigned char, Gcs_packet_buffer_deleter > buffer_ptr
Definition: gcs_internal_message.h:59
void prepare_for_next_incoming_stage()
Definition: gcs_internal_message.cc:233
Gcs_internal_message_header const & get_fixed_header() const
Retrieve this packet's header.
Definition: gcs_internal_message.cc:213
unsigned long long get_total_length() const
Return the total length.
Definition: gcs_internal_message.cc:265
Cargo_type get_cargo_type() const
Return the cargo type.
Definition: gcs_internal_message.cc:261
unsigned long long m_serialized_packet_size
The capacity of the serialization buffer.
Definition: gcs_internal_message.h:99
bool allocate_serialization_buffer()
Allocates the underlying buffer where the packet will be serialized to using serialize.
Definition: gcs_internal_message.cc:273
unsigned char * get_payload_pointer()
Definition: gcs_internal_message.cc:243
Gcs_protocol_version get_maximum_version() const
Return the value of the maximum supported version.
Definition: gcs_internal_message.cc:253
std::pair< buffer_ptr, unsigned long long > serialize()
Encode the packet content into its serialization buffer, and release ownership of the serialization b...
Definition: gcs_internal_message.cc:292
Gcs_dynamic_header & get_current_dynamic_header()
Definition: gcs_internal_message.cc:235
std::size_t const & get_next_stage_index() const
Definition: gcs_internal_message.cc:227
Abstract class that defines specific metadata associated to a stage if it decides to extend it.
Definition: gcs_internal_message_headers.h:561
Defines a message identifier so that joining members can fetch the associated packet from a remote no...
Definition: gcs_xcom_synode.h:38
Cargo_type
The different cargo type codes.
Definition: gcs_internal_message_headers.h:114
Gcs_protocol_version
The GCS protocol versions.
Definition: gcs_types.h:127
#define free(A)
Definition: lexyy.cc:915
mutable_buffer buffer(void *p, size_t n) noexcept
Definition: buffer.h:419
size_t buffer_size(const ConstBufferSequence &buffers) noexcept
Definition: buffer.h:314
Definition: varlen_sort.h:183
std::basic_ostringstream< char, std::char_traits< char >, ut::allocator< char > > ostringstream
Specialization of basic_ostringstream which uses ut::allocator.
Definition: ut0new.h:2869
std::vector< T, ut::allocator< T > > vector
Specialization of vector which uses allocator.
Definition: ut0new.h:2873
std::conditional_t< !std::is_array< T >::value, std::unique_ptr< T, detail::Deleter< T > >, std::conditional_t< detail::is_unbounded_array_v< T >, std::unique_ptr< T, detail::Array_deleter< std::remove_extent_t< T > > >, void > > unique_ptr
The following is a common type that is returned by all the ut::make_unique (non-aligned) specializati...
Definition: ut0new.h:2437
Deleter for objects managed by a std::unique_ptr that were allocated using the malloc family of funct...
Definition: gcs_internal_message.h:43
void operator()(unsigned char *buffer) const
Definition: gcs_internal_message.h:44