MySQL 8.3.0
Source Code Documentation
gcs_xcom_interface.h
Go to the documentation of this file.
1/* Copyright (c) 2015, 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_XCOM_INTERFACE_INCLUDED
24#define GCS_XCOM_INTERFACE_INCLUDED
25
26/*
27 This file is the main entry point for the gcs_interface implementation for
28 the XCom Group communication library.
29*/
30
31#include <cstdlib>
32#include <ctime>
33#include <map>
34#include <string>
35
51
52/**
53 * Keep track of the most recent XCom configuration the node will deliver
54 * upwards.
55 */
57 public:
59 /**
60 * Resets the object to its initial state.
61 */
62 void reset();
63 /**
64 * Updates this configuration's information.
65 *
66 * @param config_id the synod of the configuration
67 * @param xcom_nodes the XCom configuration's membership
68 * @param event_horizon the XCom configuration's event horizon
69 */
70 void update(synode_no config_id, Gcs_xcom_nodes const &xcom_nodes,
71 xcom_event_horizon event_horizon);
72 /**
73 * Checks whether this configuration pertains to a received XCom view, i.e.
74 * the configuration object is not in its initial state.
75 *
76 * @returns true if the configuration pertains to a received XCom view, false
77 * otherwise
78 */
79 bool has_view() const;
80 /**
81 * Checks whether this configuration's synod matches the the given synod.
82 *
83 * @param config_id the synod to compare against
84 * @returns true if the synods are the same, false otherwise
85 */
86 bool same_view(synode_no config_id) const;
87 /**
88 * Checks whether this configuration's membership matches the given
89 * membership.
90 *
91 * @param xcom_nodes the membership to compare against
92 * @returns true if the memberships are the same, false otherwise
93 */
94 bool same_xcom_nodes(Gcs_xcom_nodes const &xcom_nodes) const;
95 /**
96 * Checks whether this configuration's event horizon matches the given event
97 * horizon.
98 *
99 * @param event_horizon the event horizon to compare against
100 * @returns true if the event horizons are the same, false otherwise
101 */
102 bool same_event_horizon(xcom_event_horizon const &event_horizon) const;
103 /**
104 * Checks whether this configuration's membership matches the given
105 * membership.
106 *
107 * @param xcom_nodes the membership to compare against
108 * @returns true if the memberships are the same, false otherwise
109 */
110 bool same_xcom_nodes_v3(Gcs_xcom_nodes const &xcom_nodes) const;
111 /*
112 * This class will have a singleton object, so we delete the {copy,move}
113 * {constructor,assignment}. This way the compiler slaps us on the wrist if we
114 * attempt to copy or move the singleton.
115 */
120
121 private:
122 synode_no config_id_;
124 xcom_event_horizon event_horizon_;
125};
126
128
129/**
130 Struct that holds instances of this binding interface implementations.
131*/
132typedef struct xcom_group_interfaces {
137
138 /*
139 Additional storage of group interface auxiliary structures for later
140 deletion.
141 */
144
146
147/**
148 Implementation of the Gcs_interface for the XCom binding.
149*/
151 private:
152 // XCom single instance
154
155 /**
156 XCom binding private constructor.
157 */
158 explicit Gcs_xcom_interface();
159
160 public:
161 /**
162 Since one wants that a single instance exists, the interface implementation
163 shall be retrieved via a Singleton pattern.
164
165 This is the public method that allows the retrieving of the single
166 instance.
167
168 @return a reference to the Singleton instance
169 */
170
172
173 /**
174 Public method that finalizes and cleans the singleton.
175 */
176
177 static void cleanup();
178
179 /**
180 Public method that cleans thread-local resources related to communication.
181 Required when SSL is provided by OpenSSL.
182 */
183
184 static void cleanup_thread_ssl_resources();
185
187
188 /**
189 This block implements the virtual methods defined in Gcs_interface.
190 */
191
193 const Gcs_interface_parameters &interface_params) override;
194
196 const Gcs_interface_parameters &interface_params) override;
197
198 bool is_initialized() override;
199
200 enum_gcs_error finalize() override;
201
203 const Gcs_group_identifier &group_identifier) override;
204
206 const Gcs_group_identifier &group_identifier) override;
207
209 const Gcs_group_identifier &group_identifier) override;
210
212 const Gcs_group_identifier &group_identifier) override;
213
215
218
220
221 void set_xcom_group_information(const std::string &group_id);
222
224
226
227 void set_node_address(std::string const &address);
228
229 /**
230 * @see Gcs_interface#setup_runtime_resources
231 */
234
235 /**
236 * @see Gcs_interface#cleanup_runtime_resources
237 */
240
241 /**
242 This member function shall return the set of parameters that configure
243 the interface at the time its initialization was done. The parameters
244 returned already contain default values set as well as values that may
245 have been fixed.
246
247 @return The parameters configured at the time the interface was initialized.
248 */
251 }
252
253 /**
254 Must return the allowlist.
255
256 @return the list of allowlisted IP addresses and subnet masks.
257 */
259
260 /*
261 Notify all controllers that XCOM's thread has finished.
262 */
263
265
266 /**
267 Contains all the code needed to stop the xcom daemon if it was not
268 already stopped as it should have been done.
269 */
270
271 void finalize_xcom();
272
273 /**
274 Makes GCS leave the group when an error has caused XCom to terminate
275 unexpectedly.
276 */
278
279 /**
280 Used to initialize SSL assuming that the necessary parameters have already
281 been read.
282 */
283 void initialize_ssl();
284
285 /**
286 Used to initialize the unique identifier of the XCom instance.
287
288 @param node_information Information about the XCom node
289 @param xcom_proxy XCom proxy
290 @retval true if there was an error initialising the XCom identity
291 @retval false if operation was successful
292 */
293 bool set_xcom_identity(Gcs_xcom_node_information const &node_information,
294 Gcs_xcom_proxy &xcom_proxy);
295
296 private:
297 /**
298 Method to initialize the logging and debugging systems. If something
299 bad happens, an error is returned.
300
301
302 @param[in] debug_file File where the debug information on GCS will
303 be stored to
304 @param[in] debug_path Default path where the debug information on GCS
305 will be stored to
306 */
307
308 enum_gcs_error initialize_logging(const std::string *debug_file,
309 const std::string *debug_path);
310
311 /**
312 Method to finalize the logging and debugging systems. If something
313 bad happens, an error is returned.
314 */
315
317
318 /**
319 Internal helper method that retrieves all group interfaces for a certain
320 group.
321
322 @note Since the group interfaces work as a singleton, meaning that a group
323 has a single set of interfaces built, this method will also implement the
324 behavior to build and initialize the interfaces implementation.
325
326 @param[in] group_identifier the group in which one wants to instantiate the
327 interface implementation
328
329 @return a reference to a struct gcs_xcom_group_interfaces
330 */
331
333 const Gcs_group_identifier &group_identifier);
334
335 /**
336 Contains all the code needed to initialize a connection to the xcom
337 daemon.
338
339 @return true in case of error
340 */
341
342 bool initialize_xcom(const Gcs_interface_parameters &interface_params);
343
344 /**
345 Internal helper method to delete all previously created group interfaces.
346 */
347
349
350 /**
351 Internal helper method to delete all previously created group references.
352 */
353
355
356 /**
357 Helper used to parse the peer_nodes parameter and to initialize XCom peer
358 nodes.
359
360 @param[in] peer_nodes received parameter with the addresses of all peer
361 nodes
362 */
363
364 void initialize_peer_nodes(const std::string *peer_nodes);
365
366 /**
367 Helper used to delete the existing XCom peer nodes in m_xcom_peers and to
368 clear that vector.
369 */
370
371 void clear_peer_nodes();
372
373 /**
374 * @brief Announces that a finalize was called to all group instances that
375 * use a Gcs_xcom_view_change_control_interface. The purpose of this
376 * is to end any ongoing tasks, like pending joins.
377 */
379
380 // Holder to the created group interfaces, in which the key is the group
381 std::map<std::string, gcs_xcom_group_interfaces *> m_group_interfaces;
382
383 std::map<u_long, Gcs_group_identifier *> m_xcom_configured_groups;
384
385 /*
386 The address associated with the current node.
387 */
389
390 /*
391 The addresses associated with current node's peers.
392 */
393 std::vector<Gcs_xcom_node_address *> m_xcom_peers;
394
395 // States if this interface is initialized
397
398 bool m_boot;
399
401
402 /**
403 The C++ interface to setup and configure xcom properties
404 from GCS. Under the hood, this changes the C structure that
405 holds the configuration for XCom.
406
407 (As XCom moves into C++, we can replace XCom's internal
408 structure with a similar object and remove it from this
409 place.)
410 */
412
413 /**
414 The initialization parameters provided through the initialize member
415 function.
416 */
418
419 // Store pointer to default sink
421
422 // Store pointer to default logger
424
425 // Store pointer to default debugger
427
428 /**
429 The IP allowlist.
430 */
432
433 /**
434 Indicates whether SSL has been initialized and if that initialization was
435 successful.
436 */
438
439 /// protects the m_ssl_init_state thread shared variable
442
443 /**
444 Network namespace service provider
445 */
447
448 /**
449 Interface for statistic storage
450 */
452
453 /**
454 Interface for XCom statistic storage
455 */
457
458 private:
459 /*
460 Disabling the copy constructor and assignment operator.
461 */
464};
465
466int cb_xcom_match_port(xcom_port if_port);
467
468#endif /* GCS_XCOM_INTERFACE_INCLUDED */
Circular buffer that can be used to asynchronously feed a sink.
Definition: gcs_logging_system.h:190
This interface represents all the communication facilities that a binding implementation should provi...
Definition: gcs_communication_interface.h:89
This interface represents all the control functionalities that a binding implementation must provide.
Definition: gcs_control_interface.h:110
Default debugger which is used only by GCS and XCOM.
Definition: gcs_logging_system.h:509
This represents the unique identification of a group.
Definition: gcs_group_identifier.h:34
Definition: gcs_group_management_interface.h:31
This class is to be used to provide parameters to bindings in a transparent and generic way.
Definition: gcs_types.h:58
This interface must be implemented by all specific binding implementations as its entry point.
Definition: gcs_interface.h:100
Definition: gcs_xcom_networking.h:254
This interface represents all statistics that a binding implementation should provide.
Definition: gcs_statistics_interface.h:48
This class stores all node suspicions, as well as the timeout and period parameters used by the threa...
Definition: gcs_xcom_control_interface.h:69
A Gcs_xcom_interface needs to have an instance of this class initialized before engaging XCom.
Definition: gcs_xcom_proxy.h:1045
Keep track of the most recent XCom configuration the node will deliver upwards.
Definition: gcs_xcom_interface.h:56
synode_no config_id_
Definition: gcs_xcom_interface.h:122
bool same_xcom_nodes(Gcs_xcom_nodes const &xcom_nodes) const
Checks whether this configuration's membership matches the given membership.
Definition: gcs_xcom_interface.cc:82
Gcs_xcom_config & operator=(Gcs_xcom_config const &)=delete
xcom_event_horizon event_horizon_
Definition: gcs_xcom_interface.h:124
Gcs_xcom_config(Gcs_xcom_config &&)=delete
bool same_event_horizon(xcom_event_horizon const &event_horizon) const
Checks whether this configuration's event horizon matches the given event horizon.
Definition: gcs_xcom_interface.cc:96
Gcs_xcom_config()
Definition: gcs_xcom_interface.cc:59
Gcs_xcom_nodes xcom_nodes_
Definition: gcs_xcom_interface.h:123
Gcs_xcom_config(Gcs_xcom_config const &)=delete
bool same_xcom_nodes_v3(Gcs_xcom_nodes const &xcom_nodes) const
Checks whether this configuration's membership matches the given membership.
Definition: gcs_xcom_interface.cc:101
void reset()
Resets the object to its initial state.
Definition: gcs_xcom_interface.cc:62
bool same_view(synode_no config_id) const
Checks whether this configuration's synod matches the the given synod.
Definition: gcs_xcom_interface.cc:78
void update(synode_no config_id, Gcs_xcom_nodes const &xcom_nodes, xcom_event_horizon event_horizon)
Updates this configuration's information.
Definition: gcs_xcom_interface.cc:68
Gcs_xcom_config & operator=(Gcs_xcom_config &&)=delete
bool has_view() const
Checks whether this configuration pertains to a received XCom view, i.e.
Definition: gcs_xcom_interface.cc:76
Implementation of the Gcs_interface for the XCom binding.
Definition: gcs_xcom_interface.h:150
Gcs_async_buffer * m_default_sink
Definition: gcs_xcom_interface.h:420
gcs_xcom_group_interfaces * get_group_interfaces(const Gcs_group_identifier &group_identifier)
Internal helper method that retrieves all group interfaces for a certain group.
Definition: gcs_xcom_interface.cc:747
Gcs_xcom_interface & operator=(Gcs_xcom_interface const &)
enum_gcs_error configure(const Gcs_interface_parameters &interface_params) override
Method used by a binding implementation in order to implement any type of necessary dynamic reconfigu...
Definition: gcs_xcom_interface.cc:437
Gcs_default_debugger * m_default_debugger
Definition: gcs_xcom_interface.h:426
Gcs_statistics_interface * get_statistics(const Gcs_group_identifier &group_identifier) override
Method that retrieves the binding implementation of the Statistics interface.
Definition: gcs_xcom_interface.cc:732
enum_gcs_error initialize(const Gcs_interface_parameters &interface_params) override
This block implements the virtual methods defined in Gcs_interface.
Definition: gcs_xcom_interface.cc:313
enum_gcs_error setup_runtime_resources(Gcs_interface_runtime_requirements &reqs) override
Definition: gcs_xcom_interface.cc:830
static Gcs_interface * interface_reference_singleton
Definition: gcs_xcom_interface.h:153
Gcs_control_interface * get_control_session(const Gcs_group_identifier &group_identifier) override
Method that retrieves the binding implementation of the Control Session interface.
Definition: gcs_xcom_interface.cc:717
Gcs_xcom_statistics_manager_interface * m_stats_mgr
Interface for statistic storage.
Definition: gcs_xcom_interface.h:451
bool m_is_initialized
Definition: gcs_xcom_interface.h:396
Network_namespace_manager * m_netns_manager
Network namespace service provider.
Definition: gcs_xcom_interface.h:446
void announce_finalize_to_view_control()
Announces that a finalize was called to all group instances that use a Gcs_xcom_view_change_control_i...
Definition: gcs_xcom_interface.cc:655
static Gcs_interface * get_interface()
Since one wants that a single instance exists, the interface implementation shall be retrieved via a ...
Definition: gcs_xcom_interface.cc:183
void clean_group_references()
Internal helper method to delete all previously created group references.
Definition: gcs_xcom_interface.cc:872
Gcs_communication_interface * get_communication_session(const Gcs_group_identifier &group_identifier) override
Method that retrieves the binding implementation of the Communication Session interface.
Definition: gcs_xcom_interface.cc:724
Gcs_group_identifier * get_xcom_group_information(const u_long group_id)
Definition: gcs_xcom_interface.cc:1188
Gcs_ip_allowlist & get_ip_allowlist()
Must return the allowlist.
Definition: gcs_xcom_interface.cc:1344
enum_gcs_error cleanup_runtime_resources(Gcs_interface_runtime_requirements &reqs) override
Definition: gcs_xcom_interface.cc:843
bool set_xcom_identity(Gcs_xcom_node_information const &node_information, Gcs_xcom_proxy &xcom_proxy)
Used to initialize the unique identifier of the XCom instance.
Definition: gcs_xcom_interface.cc:896
~Gcs_xcom_interface() override
void initialize_peer_nodes(const std::string *peer_nodes)
Helper used to parse the peer_nodes parameter and to initialize XCom peer nodes.
Definition: gcs_xcom_interface.cc:1146
bool initialize_xcom(const Gcs_interface_parameters &interface_params)
Contains all the code needed to initialize a connection to the xcom daemon.
Definition: gcs_xcom_interface.cc:915
enum_gcs_error finalize() override
Method used by a binding implementation in order to implement any internal shutdown procedure.
Definition: gcs_xcom_interface.cc:661
Gcs_xcom_node_address * m_node_address
Definition: gcs_xcom_interface.h:388
Gcs_ip_allowlist m_ip_allowlist
The IP allowlist.
Definition: gcs_xcom_interface.h:431
bool m_boot
Definition: gcs_xcom_interface.h:398
void finalize_xcom()
Contains all the code needed to stop the xcom daemon if it was not already stopped as it should have ...
Definition: gcs_xcom_interface.cc:617
void make_gcs_leave_group_on_error()
Makes GCS leave the group when an error has caused XCom to terminate unexpectedly.
Definition: gcs_xcom_interface.cc:638
My_xp_mutex_impl m_wait_for_ssl_init_mutex
Definition: gcs_xcom_interface.h:441
bool is_initialized() override
Method used to report if the binding interface has already been initialized.
Definition: gcs_xcom_interface.cc:715
enum_gcs_error set_logger(Logger_interface *logger) override
Method that retrieves the binding implementation of the Group Management Session interface.
Definition: gcs_xcom_interface.cc:826
enum_gcs_error initialize_logging(const std::string *debug_file, const std::string *debug_path)
Method to initialize the logging and debugging systems.
Definition: gcs_xcom_interface.cc:238
std::map< u_long, Gcs_group_identifier * > m_xcom_configured_groups
Definition: gcs_xcom_interface.h:383
std::vector< Gcs_xcom_node_address * > m_xcom_peers
Definition: gcs_xcom_interface.h:393
My_xp_cond_impl m_wait_for_ssl_init_cond
protects the m_ssl_init_state thread shared variable
Definition: gcs_xcom_interface.h:440
void set_node_address(std::string const &address)
Definition: gcs_xcom_interface.cc:1213
static void cleanup_thread_ssl_resources()
Public method that cleans thread-local resources related to communication.
Definition: gcs_xcom_interface.cc:209
Logger_interface * m_default_logger
Definition: gcs_xcom_interface.h:423
Gcs_xcom_statistics_storage_impl * m_xcom_stats_storage
Interface for XCom statistic storage.
Definition: gcs_xcom_interface.h:456
Gcs_xcom_node_address * get_node_address()
Definition: gcs_xcom_interface.cc:1208
int m_ssl_init_state
Indicates whether SSL has been initialized and if that initialization was successful.
Definition: gcs_xcom_interface.h:437
Gcs_group_management_interface * get_management_session(const Gcs_group_identifier &group_identifier) override
Method that retrieves the binding implementation of the Group Management Session interface.
Definition: gcs_xcom_interface.cc:740
Gcs_xcom_interface()
XCom binding private constructor.
Definition: gcs_xcom_interface.cc:214
enum_gcs_error finalize_logging()
Method to finalize the logging and debugging systems.
Definition: gcs_xcom_interface.cc:285
Gcs_xcom_app_cfg m_gcs_xcom_app_cfg
The C++ interface to setup and configure xcom properties from GCS.
Definition: gcs_xcom_interface.h:411
Gcs_interface_parameters m_initialization_parameters
The initialization parameters provided through the initialize member function.
Definition: gcs_xcom_interface.h:417
const Gcs_interface_parameters & get_initialization_parameters()
This member function shall return the set of parameters that configure the interface at the time its ...
Definition: gcs_xcom_interface.h:249
void clean_group_interfaces()
Internal helper method to delete all previously created group interfaces.
Definition: gcs_xcom_interface.cc:854
void set_xcom_group_information(const std::string &group_id)
Definition: gcs_xcom_interface.cc:1169
void clear_peer_nodes()
Helper used to delete the existing XCom peer nodes in m_xcom_peers and to clear that vector.
Definition: gcs_xcom_interface.cc:1162
My_xp_socket_util * m_socket_util
Definition: gcs_xcom_interface.h:400
enum_gcs_error configure_message_stages(const Gcs_group_identifier &gid)
Definition: gcs_xcom_interface.cc:1219
Gcs_xcom_interface(Gcs_xcom_interface const &)
static void cleanup()
Public method that finalizes and cleans the singleton.
Definition: gcs_xcom_interface.cc:199
enum_gcs_error configure_suspicions_mgr(Gcs_interface_parameters &p, Gcs_suspicions_manager *mgr)
Definition: gcs_xcom_interface.cc:1299
std::map< std::string, gcs_xcom_group_interfaces * > m_group_interfaces
Definition: gcs_xcom_interface.h:381
void initialize_ssl()
Used to initialize SSL assuming that the necessary parameters have already been read.
Definition: gcs_xcom_interface.cc:889
Stores connection information associated with a node.
Definition: gcs_xcom_group_member_information.h:50
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:52
Definition: gcs_xcom_state_exchange.h:369
This class is the storage and provider of all statistics coming from either XCom and GCS.
Definition: gcs_xcom_statistics_manager.h:64
GCS implementation of the statistics storage of XCom.
Definition: gcs_xcom_statistics_storage_impl.h:34
Definition: gcs_xcom_state_exchange.h:715
Logger interface that must be used to define a logger object.
Definition: gcs_logging.h:124
Definition: my_xp_cond.h:135
Definition: my_xp_mutex.h:122
Interface for socket utility methods.
Definition: my_xp_util.h:153
Class that provides Network Namespace services.
Definition: network_provider.h:215
const char * p
Definition: ctype-mb.cc:1234
enum_gcs_error
This enumeration describes errors which can occur during group communication operations.
Definition: gcs_types.h:40
int cb_xcom_match_port(xcom_port if_port)
Definition: gcs_xcom_interface.cc:1723
struct xcom_group_interfaces gcs_xcom_group_interfaces
Struct that holds instances of this binding interface implementations.
static Logger logger
The "top-level" logger used when no connection context is given.
Definition: test_trace_plugin.cc:295
Runtime external resources that should be provided to an instance of Gcs_interface.
Definition: gcs_interface.h:40
Struct that holds instances of this binding interface implementations.
Definition: gcs_xcom_interface.h:132
Gcs_statistics_interface * statistics_interface
Definition: gcs_xcom_interface.h:135
Gcs_group_management_interface * management_interface
Definition: gcs_xcom_interface.h:136
Gcs_xcom_state_exchange_interface * se
Definition: gcs_xcom_interface.h:143
Gcs_control_interface * control_interface
Definition: gcs_xcom_interface.h:133
Gcs_xcom_view_change_control_interface * vce
Definition: gcs_xcom_interface.h:142
Gcs_communication_interface * communication_interface
Definition: gcs_xcom_interface.h:134
__u_long u_long
Definition: types.h:73
unsigned short xcom_port
Definition: xcom_common.h:45