MySQL 8.0.32
Source Code Documentation
gcs_xcom_communication_interface.h
Go to the documentation of this file.
1/* Copyright (c) 2015, 2022, 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_XCOM_COMMUNICATION_INTERFACE_INCLUDED
24#define GCS_XCOM_COMMUNICATION_INTERFACE_INCLUDED
25
26#include <cstdlib>
27#include <map> // std::map
28#include <utility> // std::pair
29#include <vector> // std::vector
30
42
44
45/**
46 @class Gcs_xcom_communication_interface
47
48 Abstraction layer that adds XCom specific methods to the generic
49 communication interface.
50
51 This adds the following functionalities to the generic
52 Gcs_communication_interface:
53 - Ability to send messages without view safety and stats counter. This method
54 shall be used by the State Exchange algorithm when the high-level view
55 change is still occurring.
56 - Delegation method that will contain all the business logic related with
57 messages delivery to registered clients.
58*/
60 public:
61 /**
62 Sends a message that is internal to the binding implementation.
63 This message will not be subject to the same restrictions of send_message.
64 As such, it will not observe view safety nor will count for the statistics
65 of messages sent.
66
67 @param[in] message_to_send the message to send
68 @param[out] message_length the length of message which was send if GCS_OK,
69 unspecified otherwise
70 @param[in] cargo internal message header cargo type
71 @return the xcom broadcast message error
72 @retval GCS_OK message is transmitted successfully
73 @retval GCS_NOK error occurred while transmitting message
74 @retval GCS_MESSAGE_TOO_BIG message is bigger then xcom can handle
75
76 */
77
78 virtual enum_gcs_error do_send_message(const Gcs_message &message_to_send,
79 unsigned long long *message_length,
80 Cargo_type cargo) = 0;
81
83
84 /**
85 Buffer packets when a view is not installed yet and the state
86 exchange phase is being executed.
87
88 Note that this method must be executed by the same thread that
89 processes global view messages and data message in order to
90 avoid any concurrency issue.
91
92 @param packet Packet to buffer.
93 @param xcom_nodes Membership at the time the packet was received
94 */
95
97 Gcs_packet &&packet, std::unique_ptr<Gcs_xcom_nodes> &&xcom_nodes) = 0;
98
99 /**
100 The state exchange phase has been executed and the view has been
101 installed so this is used to send any buffered packet to upper
102 layers.
103
104 Note that this method must be executed by the same thread that
105 processes global view messages and data message in order to
106 avoid any concurrency issue.
107 */
108
109 virtual void deliver_buffered_packets() = 0;
110
111 /*
112 Clean up possible buffered packets that were not delivered to
113 upper layers because the state exchange has not finished and a
114 new global view message was received triggering a new state
115 exchange phase.
116
117 Note that this method must be executed by the same thread that
118 processes global view messages and data message in order to
119 avoid any concurrency issue.
120 */
121
122 virtual void cleanup_buffered_packets() = 0;
123
124 /**
125 Return the number of buffered packets.
126
127 Note that this method must be executed by the same thread that
128 processes global view messages and data message in order to
129 avoid any concurrency issue.
130 */
131
132 virtual size_t number_buffered_packets() = 0;
133
134 /**
135 Notify the pipeline about the new XCom membership when a state exchange
136 begins.
137
138 Note that this method must be executed by the same thread that processes
139 global view messages and data message in order to avoid any concurrency
140 issue.
141
142 @param me The identifier of this server
143 @param members The XCom membership
144 */
146 const Gcs_xcom_nodes &members) = 0;
147
148 /**
149 Attempts to recover the missing packets that are required for a node to
150 join the group successfully.
151 For example, the missing packets may be some fragments of a message that
152 have already been delivered by XCom to the existing members of the group.
153 The joining node needs those fragments in order to be able to deliver the
154 reassembled message when the final fragments are delivered by XCom.
155
156 Note that this method must be executed by the same thread that processes
157 global view messages and data message in order to avoid any concurrency
158 issue.
159
160 @param synodes The synodes where the required packets were decided
161 @returns true If successful, false otherwise
162 */
163 virtual bool recover_packets(Gcs_xcom_synode_set const &synodes) = 0;
164
165 /**
166 Converts the packet into a message that can be delivered to the upper
167 layer.
168
169 @param packet The packet to convert
170 @param xcom_nodes The membership at the time the packet was delivered
171 @retval Gcs_message* if successful
172 @retval nullptr if unsuccessful
173 */
175 Gcs_packet &&packet, std::unique_ptr<Gcs_xcom_nodes> &&xcom_nodes) = 0;
176
177 /**
178 The purpose of this method is to be called when in Gcs_xcom_interface
179 callback method xcom_receive_data is invoked.
180
181 This allows, in terms of software architecture, to concentrate all the
182 message delivery logic and processing in a single place.
183
184 The deliver_message callback that is registered in XCom
185 (in gcs_xcom_interface.h) and that actually receives the low-level
186 messages, is implemented as a delegator to this method.
187
188 Note that the method will be responsible for deleting the message
189 passed as parameter and must be executed by the same thread that
190 processes global view messages and data message in order to avoid
191 any concurrency issue.
192 */
193
195 Gcs_packet &&packet, std::unique_ptr<Gcs_xcom_nodes> &&xcom_nodes) = 0;
196
198};
199
200/**
201 @class Gcs_xcom_communication_interface
202
203 Implementation of the Gcs_communication_interface for xcom.
204*/
206 public:
207 /**
208 Gcs_xcom_communication_interface constructor.
209
210 @param[in] stats a reference to the statistics interface
211 @param[in] proxy a reference to an implementation of
212 Gcs_xcom_communication_proxy
213 @param[in] view_control a reference to a
214 gcs_xcom_view_change_control_interface implementation
215 @param[in] gcs_engine Pointer to gcs engine
216 @param[in] group_id reference to the group identifier
217 @param[in] comms_mgmt an unique_ptr to a
218 Network_provider_management_interface
219 */
220
221 explicit Gcs_xcom_communication(
225 std::unique_ptr<Network_provider_management_interface> comms_mgmt);
226
228
229 // Implementation of the Gcs_communication_interface
230
231 /**
232 Implementation of the public send_message method defined in
233 Gcs_xcom_communication.
234 Besides sending a message to the group, this method does two extra things:
235 - Guarantees view safety, in which no messages can be sent when a view
236 change is occurring.
237 - Registers in the statistics interface that a message was sent.
238
239 @param[in] message_to_send the message to send
240 @return the xcom broadcast message error
241 @retval GCS_OK when message is transmitted successfully
242 @retval GCS_NOK when error occurred while transmitting message
243 @retval GCS_MESSAGE_TOO_BIG when message is bigger then
244 xcom can handle
245 */
246
247 enum_gcs_error send_message(const Gcs_message &message_to_send) override;
248
250 const Gcs_communication_event_listener &event_listener) override;
251
252 void remove_event_listener(int event_listener_handle) override;
253
254 // Implementation of the Gcs_xcom_communication_interface
255 enum_gcs_error do_send_message(const Gcs_message &message_to_send,
256 unsigned long long *message_length,
257 Cargo_type cargo) override;
258
259 // For unit testing purposes
260 std::map<int, const Gcs_communication_event_listener &>
262
264
266 Gcs_packet &&packet,
267 std::unique_ptr<Gcs_xcom_nodes> &&xcom_nodes) override;
268
269 void deliver_buffered_packets() override;
270
271 void cleanup_buffered_packets() override;
272
273 size_t number_buffered_packets() override;
274
276 const Gcs_xcom_nodes &members) override;
277
278 bool recover_packets(Gcs_xcom_synode_set const &synodes) override;
279
281 Gcs_packet &&packet,
282 std::unique_ptr<Gcs_xcom_nodes> &&xcom_nodes) override;
283
285 Gcs_packet &&packet,
286 std::unique_ptr<Gcs_xcom_nodes> &&xcom_nodes) override;
287
289
290 std::pair<bool, std::future<void>> set_protocol_version(
291 Gcs_protocol_version new_version) override;
292
294
296
298
300
301 private:
302 // Registered event listeners
303 std::map<int, const Gcs_communication_event_listener &> event_listeners;
304
305 // Reference to the stats updater interface
307
308 // Reference to the xcom proxy interface
310
311 // Reference to the view change control object
313
314 /**
315 The pipeline of stages a message has to go through before it is delivered
316 to the application or sent to the network.
317 */
319
320 /**
321 Buffer that is used to store packets while the node is about to install
322 a view and is running the state exchange phase.
323 */
324 std::vector<std::pair<Gcs_packet, std::unique_ptr<Gcs_xcom_nodes>>>
326
327 /** Most recent XCom membership known. */
329
330 /** Hash of the group. */
331 unsigned int m_gid_hash;
332
333 /** Protocol changer. */
335
336 /***/
337 std::unique_ptr<Network_provider_management_interface> m_comms_mgmt_interface;
338
339 /** Notify upper layers that a message has been received. */
340 void notify_received_message(std::unique_ptr<Gcs_message> &&message);
341
342 /** Delivers the packet to the upper layer. */
344 std::unique_ptr<Gcs_xcom_nodes> &&xcom_nodes);
345
346 /**
347 @returns the list of possible donors from which to recover the missing
348 packets this server requires to successfully join the group.
349 */
350 std::vector<Gcs_xcom_node_information> possible_packet_recovery_donors()
351 const;
352
353 /**
354 Error code for the packet recovery proceess.
355 */
357 OK,
359 NO_MEMORY,
363 ERROR
364 };
365
366 /**
367 Attempts to recover the packets delivered in @c synodes from @c donor.
368
369 @c recovered_data is an out parameter.
370 */
372 Gcs_xcom_node_information const &donor,
373 Gcs_xcom_synode_set const &synodes,
374 synode_app_data_array &recovered_data);
375
376 /**
377 Processes all the recovered packets.
378 */
380 synode_app_data_array const &recovered_data);
381
382 /**
383 Processes a single recovered packet.
384 */
386 synode_app_data const &recovered_data);
387
388 /**
389 Logs the packet recovery failure.
390 */
392 packet_recovery_result const &error_code,
393 Gcs_xcom_node_information const &donor) const;
394
395 /*
396 Disabling the copy constructor and assignment operator.
397 */
400};
401
402#endif /* GCS_XCOM_COMMUNICATION_INTERFACE_INCLUDED */
This interface is implemented by those who wish to receive messages.
Definition: gcs_communication_event_listener.h:35
This interface represents all the communication facilities that a binding implementation should provi...
Definition: gcs_communication_interface.h:89
This represents the unique identification of a group.
Definition: gcs_group_identifier.h:34
It represents the identity of a group member within a certain group.
Definition: gcs_member_identifier.h:39
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
Class that represents the data that is exchanged within a group.
Definition: gcs_message.h:356
This class is an abstraction for the packet concept.
Definition: gcs_internal_message.h:57
Abstraction layer that adds XCom specific methods to the generic communication interface.
Definition: gcs_xcom_communication_interface.h:59
virtual void process_user_data_packet(Gcs_packet &&packet, std::unique_ptr< Gcs_xcom_nodes > &&xcom_nodes)=0
The purpose of this method is to be called when in Gcs_xcom_interface callback method xcom_receive_da...
virtual bool recover_packets(Gcs_xcom_synode_set const &synodes)=0
Attempts to recover the missing packets that are required for a node to join the group successfully.
virtual Gcs_message * convert_packet_to_message(Gcs_packet &&packet, std::unique_ptr< Gcs_xcom_nodes > &&xcom_nodes)=0
Converts the packet into a message that can be delivered to the upper layer.
virtual void buffer_incoming_packet(Gcs_packet &&packet, std::unique_ptr< Gcs_xcom_nodes > &&xcom_nodes)=0
Buffer packets when a view is not installed yet and the state exchange phase is being executed.
virtual void cleanup_buffered_packets()=0
~Gcs_xcom_communication_interface() override=default
virtual size_t number_buffered_packets()=0
Return the number of buffered packets.
virtual enum_gcs_error do_send_message(const Gcs_message &message_to_send, unsigned long long *message_length, Cargo_type cargo)=0
Sends a message that is internal to the binding implementation.
virtual Gcs_message_pipeline & get_msg_pipeline()=0
virtual void deliver_buffered_packets()=0
The state exchange phase has been executed and the view has been installed so this is used to send an...
virtual void update_members_information(const Gcs_member_identifier &me, const Gcs_xcom_nodes &members)=0
Notify the pipeline about the new XCom membership when a state exchange begins.
Implements the communication protocol change logic.
Definition: gcs_xcom_communication_protocol_changer.h:216
Definition: gcs_xcom_communication_interface.h:205
std::map< int, const Gcs_communication_event_listener & > event_listeners
Definition: gcs_xcom_communication_interface.h:303
Gcs_message_pipeline m_msg_pipeline
The pipeline of stages a message has to go through before it is delivered to the application or sent ...
Definition: gcs_xcom_communication_interface.h:318
size_t number_buffered_packets() override
Return the number of buffered packets.
Definition: gcs_xcom_communication_interface.cc:249
bool recover_packets(Gcs_xcom_synode_set const &synodes) override
Attempts to recover the missing packets that are required for a node to join the group successfully.
Definition: gcs_xcom_communication_interface.cc:446
Gcs_message_pipeline & get_msg_pipeline() override
Definition: gcs_xcom_communication_interface.h:263
Gcs_message * convert_packet_to_message(Gcs_packet &&packet, std::unique_ptr< Gcs_xcom_nodes > &&xcom_nodes) override
Converts the packet into a message that can be delivered to the upper layer.
Definition: gcs_xcom_communication_interface.cc:489
packet_recovery_result process_recovered_packets(synode_app_data_array const &recovered_data)
Processes all the recovered packets.
Definition: gcs_xcom_communication_interface.cc:355
void notify_received_message(std::unique_ptr< Gcs_message > &&message)
Notify upper layers that a message has been received.
Definition: gcs_xcom_communication_interface.cc:201
void set_communication_protocol(enum_transport_protocol protocol) override
Sets the communication protocol to use.
Definition: gcs_xcom_communication_interface.cc:639
void deliver_user_data_packet(Gcs_packet &&packet, std::unique_ptr< Gcs_xcom_nodes > &&xcom_nodes)
Delivers the packet to the upper layer.
Definition: gcs_xcom_communication_interface.cc:601
packet_recovery_result recover_packets_from_donor(Gcs_xcom_node_information const &donor, Gcs_xcom_synode_set const &synodes, synode_app_data_array &recovered_data)
Attempts to recover the packets delivered in synodes from donor.
Definition: gcs_xcom_communication_interface.cc:376
std::unique_ptr< Network_provider_management_interface > m_comms_mgmt_interface
Definition: gcs_xcom_communication_interface.h:337
Gcs_xcom_communication(Gcs_xcom_statistics_updater *stats, Gcs_xcom_proxy *proxy, Gcs_xcom_view_change_control_interface *view_control, Gcs_xcom_engine *gcs_engine, Gcs_group_identifier const &group_id, std::unique_ptr< Network_provider_management_interface > comms_mgmt)
Gcs_xcom_communication_interface constructor.
Definition: gcs_xcom_communication_interface.cc:58
void deliver_buffered_packets() override
The state exchange phase has been executed and the view has been installed so this is used to send an...
Definition: gcs_xcom_communication_interface.cc:231
Gcs_protocol_version get_protocol_version() const override
Retrieves the current GCS protocol version in use.
Definition: gcs_xcom_communication_interface.cc:620
void buffer_incoming_packet(Gcs_packet &&packet, std::unique_ptr< Gcs_xcom_nodes > &&xcom_nodes) override
Buffer packets when a view is not installed yet and the state exchange phase is being executed.
Definition: gcs_xcom_communication_interface.cc:221
Gcs_protocol_version get_maximum_supported_protocol_version() const override
Get the maximum protocol version currently supported by the group.
Definition: gcs_xcom_communication_interface.cc:630
Gcs_xcom_proxy * m_xcom_proxy
Definition: gcs_xcom_communication_interface.h:309
void set_maximum_supported_protocol_version(Gcs_protocol_version version)
Definition: gcs_xcom_communication_interface.cc:634
enum_gcs_error send_message(const Gcs_message &message_to_send) override
Implementation of the public send_message method defined in Gcs_xcom_communication.
Definition: gcs_xcom_communication_interface.cc:85
~Gcs_xcom_communication() override
std::vector< Gcs_xcom_node_information > possible_packet_recovery_donors() const
Definition: gcs_xcom_communication_interface.cc:260
void remove_event_listener(int event_listener_handle) override
Removes a previously registered event listener.
Definition: gcs_xcom_communication_interface.cc:197
Gcs_xcom_nodes m_xcom_nodes
Most recent XCom membership known.
Definition: gcs_xcom_communication_interface.h:328
Gcs_xcom_communication & operator=(const Gcs_xcom_communication &)
enum_gcs_error do_send_message(const Gcs_message &message_to_send, unsigned long long *message_length, Cargo_type cargo) override
Sends a message that is internal to the binding implementation.
Definition: gcs_xcom_communication_interface.cc:115
Gcs_xcom_statistics_updater * stats
Definition: gcs_xcom_communication_interface.h:306
void update_members_information(const Gcs_member_identifier &me, const Gcs_xcom_nodes &members) override
Notify the pipeline about the new XCom membership when a state exchange begins.
Definition: gcs_xcom_communication_interface.cc:253
packet_recovery_result process_recovered_packet(synode_app_data const &recovered_data)
Processes a single recovered packet.
Definition: gcs_xcom_communication_interface.cc:285
void log_packet_recovery_failure(packet_recovery_result const &error_code, Gcs_xcom_node_information const &donor) const
Logs the packet recovery failure.
Definition: gcs_xcom_communication_interface.cc:403
Gcs_xcom_communication(const Gcs_xcom_communication &)
enum_transport_protocol get_incoming_connections_protocol() override
Get the incoming connections protocol which is currently active.
Definition: gcs_xcom_communication_interface.cc:645
void process_user_data_packet(Gcs_packet &&packet, std::unique_ptr< Gcs_xcom_nodes > &&xcom_nodes) override
The purpose of this method is to be called when in Gcs_xcom_interface callback method xcom_receive_da...
Definition: gcs_xcom_communication_interface.cc:546
std::map< int, const Gcs_communication_event_listener & > * get_event_listeners()
Definition: gcs_xcom_communication_interface.cc:81
Gcs_xcom_communication_protocol_changer m_protocol_changer
Protocol changer.
Definition: gcs_xcom_communication_interface.h:334
packet_recovery_result
Error code for the packet recovery proceess.
Definition: gcs_xcom_communication_interface.h:356
void cleanup_buffered_packets() override
Definition: gcs_xcom_communication_interface.cc:245
unsigned int m_gid_hash
Hash of the group.
Definition: gcs_xcom_communication_interface.h:331
std::pair< bool, std::future< void > > set_protocol_version(Gcs_protocol_version new_version) override
Modifies the GCS protocol version in use.
Definition: gcs_xcom_communication_interface.cc:624
int add_event_listener(const Gcs_communication_event_listener &event_listener) override
Registers an implementation of a Gcs_communication_event_listener that will receive Communication Eve...
Definition: gcs_xcom_communication_interface.cc:184
std::vector< std::pair< Gcs_packet, std::unique_ptr< Gcs_xcom_nodes > > > m_buffered_packets
Buffer that is used to store packets while the node is about to install a view and is running the sta...
Definition: gcs_xcom_communication_interface.h:325
Gcs_xcom_view_change_control_interface * m_view_control
Definition: gcs_xcom_communication_interface.h:312
Definition: gcs_xcom_notification.h:93
It represents a node within a group and is identified by the member identifier, unique identifier and...
Definition: gcs_xcom_group_member_information.h:192
This class contains information on the configuration, i.e set of nodes or simply site definition.
Definition: gcs_xcom_group_member_information.h:390
Definition: gcs_xcom_proxy.h:51
This interface contains the public methods that the implementation of the Gcs_statistics_interface wi...
Definition: gcs_xcom_statistics_interface.h:38
Definition: gcs_xcom_state_exchange.h:715
Cargo_type
The different cargo type codes.
Definition: gcs_internal_message_headers.h:114
enum_gcs_error
This enumeration describes errors which can occur during group communication operations.
Definition: gcs_types.h:40
Gcs_protocol_version
The GCS protocol versions.
Definition: gcs_types.h:127
static Gcs_xcom_engine * gcs_engine
Definition: gcs_xcom_interface.cc:143
std::unordered_set< Gcs_xcom_synode > Gcs_xcom_synode_set
Definition: gcs_xcom_synode.h:83
enum_transport_protocol
Enum that describes the available XCom Communication Stacks.
Definition: network_provider.h:42
required uint64 version
Definition: replication_group_member_actions.proto:40
Definition: mysqlslap.cc:237