MySQL 8.0.32
Source Code Documentation
gcs_xcom_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_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
49
50/**
51 * Keep track of the most recent XCom configuration the node will deliver
52 * upwards.
53 */
55 public:
57 /**
58 * Resets the object to its initial state.
59 */
60 void reset();
61 /**
62 * Updates this configuration's information.
63 *
64 * @param config_id the synod of the configuration
65 * @param xcom_nodes the XCom configuration's membership
66 * @param event_horizon the XCom configuration's event horizon
67 */
68 void update(synode_no config_id, Gcs_xcom_nodes const &xcom_nodes,
69 xcom_event_horizon event_horizon);
70 /**
71 * Checks whether this configuration pertains to a received XCom view, i.e.
72 * the configuration object is not in its initial state.
73 *
74 * @returns true if the configuration pertains to a received XCom view, false
75 * otherwise
76 */
77 bool has_view() const;
78 /**
79 * Checks whether this configuration's synod matches the the given synod.
80 *
81 * @param config_id the synod to compare against
82 * @returns true if the synods are the same, false otherwise
83 */
84 bool same_view(synode_no config_id) const;
85 /**
86 * Checks whether this configuration's membership matches the given
87 * membership.
88 *
89 * @param xcom_nodes the membership to compare against
90 * @returns true if the memberships are the same, false otherwise
91 */
92 bool same_xcom_nodes(Gcs_xcom_nodes const &xcom_nodes) const;
93 /**
94 * Checks whether this configuration's event horizon matches the given event
95 * horizon.
96 *
97 * @param event_horizon the event horizon to compare against
98 * @returns true if the event horizons are the same, false otherwise
99 */
100 bool same_event_horizon(xcom_event_horizon const &event_horizon) const;
101 /**
102 * Checks whether this configuration's membership matches the given
103 * membership.
104 *
105 * @param xcom_nodes the membership to compare against
106 * @returns true if the memberships are the same, false otherwise
107 */
108 bool same_xcom_nodes_v3(Gcs_xcom_nodes const &xcom_nodes) const;
109 /*
110 * This class will have a singleton object, so we delete the {copy,move}
111 * {constructor,assignment}. This way the compiler slaps us on the wrist if we
112 * attempt to copy or move the singleton.
113 */
118
119 private:
120 synode_no config_id_;
122 xcom_event_horizon event_horizon_;
123};
124
126
127/**
128 Struct that holds instances of this binding interface implementations.
129*/
130typedef struct xcom_group_interfaces {
135
136 /*
137 Additional storage of group interface auxiliary structures for later
138 deletion.
139 */
142
144
145/**
146 Implementation of the Gcs_interface for the XCom binding.
147*/
149 private:
150 // XCom single instance
152
153 /**
154 XCom binding private constructor.
155 */
156 explicit Gcs_xcom_interface();
157
158 public:
159 /**
160 Since one wants that a single instance exists, the interface implementation
161 shall be retrieved via a Singleton pattern.
162
163 This is the public method that allows the retrieving of the single
164 instance.
165
166 @return a reference to the Singleton instance
167 */
168
170
171 /**
172 Public method that finalizes and cleans the singleton.
173 */
174
175 static void cleanup();
176
177 /**
178 Public method that cleans thread-local resources related to communication.
179 Required when SSL is provided by OpenSSL.
180 */
181
182 static void cleanup_thread_ssl_resources();
183
185
186 /**
187 This block implements the virtual methods defined in Gcs_interface.
188 */
189
191 const Gcs_interface_parameters &interface_params) override;
192
194 const Gcs_interface_parameters &interface_params) override;
195
196 bool is_initialized() override;
197
198 enum_gcs_error finalize() override;
199
201 const Gcs_group_identifier &group_identifier) override;
202
204 const Gcs_group_identifier &group_identifier) override;
205
207 const Gcs_group_identifier &group_identifier) override;
208
210 const Gcs_group_identifier &group_identifier) override;
211
213
216
218
219 void set_xcom_group_information(const std::string &group_id);
220
222
224
225 void set_node_address(std::string const &address);
226
227 /**
228 * @see Gcs_interface#setup_runtime_resources
229 */
232
233 /**
234 * @see Gcs_interface#cleanup_runtime_resources
235 */
238
239 /**
240 This member function shall return the set of parameters that configure
241 the interface at the time its initialization was done. The parameters
242 returned already contain default values set as well as values that may
243 have been fixed.
244
245 @return The parameters configured at the time the interface was initialized.
246 */
249 }
250
251 /**
252 Must return the allowlist.
253
254 @return the list of allowlisted IP addresses and subnet masks.
255 */
257
258 /*
259 Notify all controllers that XCOM's thread has finished.
260 */
261
263
264 /**
265 Contains all the code needed to stop the xcom daemon if it was not
266 already stopped as it should have been done.
267 */
268
269 void finalize_xcom();
270
271 /**
272 Makes GCS leave the group when an error has caused XCom to terminate
273 unexpectedly.
274 */
276
277 /**
278 Used to initialize SSL assuming that the necessary parameters have already
279 been read.
280 */
281 void initialize_ssl();
282
283 /**
284 Used to initialize the unique identifier of the XCom instance.
285
286 @param node_information Information about the XCom node
287 @param xcom_proxy XCom proxy
288 @retval true if there was an error initialising the XCom identity
289 @retval false if operation was successful
290 */
291 bool set_xcom_identity(Gcs_xcom_node_information const &node_information,
292 Gcs_xcom_proxy &xcom_proxy);
293
294 private:
295 /**
296 Method to initialize the logging and debugging systems. If something
297 bad happens, an error is returned.
298
299
300 @param[in] debug_file File where the debug information on GCS will
301 be stored to
302 @param[in] debug_path Default path where the debug information on GCS
303 will be stored to
304 */
305
306 enum_gcs_error initialize_logging(const std::string *debug_file,
307 const std::string *debug_path);
308
309 /**
310 Method to finalize the logging and debugging systems. If something
311 bad happens, an error is returned.
312 */
313
315
316 /**
317 Internal helper method that retrieves all group interfaces for a certain
318 group.
319
320 @note Since the group interfaces work as a singleton, meaning that a group
321 has a single set of interfaces built, this method will also implement the
322 behavior to build and initialize the interfaces implementation.
323
324 @param[in] group_identifier the group in which one wants to instantiate the
325 interface implementation
326
327 @return a reference to a struct gcs_xcom_group_interfaces
328 */
329
331 const Gcs_group_identifier &group_identifier);
332
333 /**
334 Contains all the code needed to initialize a connection to the xcom
335 daemon.
336
337 @return true in case of error
338 */
339
340 bool initialize_xcom(const Gcs_interface_parameters &interface_params);
341
342 /**
343 Internal helper method to delete all previously created group interfaces.
344 */
345
347
348 /**
349 Internal helper method to delete all previously created group references.
350 */
351
353
354 /**
355 Helper used to parse the peer_nodes parameter and to initialize XCom peer
356 nodes.
357
358 @param[in] peer_nodes received parameter with the addresses of all peer
359 nodes
360 */
361
362 void initialize_peer_nodes(const std::string *peer_nodes);
363
364 /**
365 Helper used to delete the existing XCom peer nodes in m_xcom_peers and to
366 clear that vector.
367 */
368
369 void clear_peer_nodes();
370
371 /**
372 * @brief Announces that a finalize was called to all group instances that
373 * use a Gcs_xcom_view_change_control_interface. The purpose of this
374 * is to end any ongoing tasks, like pending joins.
375 */
377
378 // Holder to the created group interfaces, in which the key is the group
379 std::map<std::string, gcs_xcom_group_interfaces *> m_group_interfaces;
380
381 std::map<u_long, Gcs_group_identifier *> m_xcom_configured_groups;
382
383 /*
384 The address associated with the current node.
385 */
387
388 /*
389 The addresses associated with current node's peers.
390 */
391 std::vector<Gcs_xcom_node_address *> m_xcom_peers;
392
393 // States if this interface is initialized
395
396 bool m_boot;
397
399
400 /**
401 The C++ interface to setup and configure xcom properties
402 from GCS. Under the hood, this changes the C structure that
403 holds the configuration for XCom.
404
405 (As XCom moves into C++, we can replace XCom's internal
406 structure with a similar object and remove it from this
407 place.)
408 */
410
411 /**
412 The initialization parameters provided through the initialize member
413 function.
414 */
416
417 // Store pointer to default sink
419
420 // Store pointer to default logger
422
423 // Store pointer to default debugger
425
426 /**
427 The IP allowlist.
428 */
430
431 /**
432 Indicates whether SSL has been initialized and if that initialization was
433 successful.
434 */
436
437 /// protects the m_ssl_init_state thread shared variable
440
441 /**
442 Network namespace service provider
443 */
445
446 private:
447 /*
448 Disabling the copy constructor and assignment operator.
449 */
452};
453
454int cb_xcom_match_port(xcom_port if_port);
455
456#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:32
This class stores all node suspicions, as well as the timeout and period parameters used by the threa...
Definition: gcs_xcom_control_interface.h:68
A Gcs_xcom_interface needs to have an instance of this class initialized before engaging XCom.
Definition: gcs_xcom_proxy.h:1044
Keep track of the most recent XCom configuration the node will deliver upwards.
Definition: gcs_xcom_interface.h:54
synode_no config_id_
Definition: gcs_xcom_interface.h:120
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:122
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:121
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:148
Gcs_async_buffer * m_default_sink
Definition: gcs_xcom_interface.h:418
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:736
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:432
Gcs_default_debugger * m_default_debugger
Definition: gcs_xcom_interface.h:424
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:721
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:312
enum_gcs_error setup_runtime_resources(Gcs_interface_runtime_requirements &reqs) override
Definition: gcs_xcom_interface.cc:819
static Gcs_interface * interface_reference_singleton
Definition: gcs_xcom_interface.h:151
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:706
bool m_is_initialized
Definition: gcs_xcom_interface.h:394
Network_namespace_manager * m_netns_manager
Network namespace service provider.
Definition: gcs_xcom_interface.h:444
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:650
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:861
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:713
Gcs_group_identifier * get_xcom_group_information(const u_long group_id)
Definition: gcs_xcom_interface.cc:1177
Gcs_ip_allowlist & get_ip_allowlist()
Must return the allowlist.
Definition: gcs_xcom_interface.cc:1333
enum_gcs_error cleanup_runtime_resources(Gcs_interface_runtime_requirements &reqs) override
Definition: gcs_xcom_interface.cc:832
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:885
~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:1135
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:904
enum_gcs_error finalize() override
Method used by a binding implementation in order to implement any internal shutdown procedure.
Definition: gcs_xcom_interface.cc:656
Gcs_xcom_node_address * m_node_address
Definition: gcs_xcom_interface.h:386
Gcs_ip_allowlist m_ip_allowlist
The IP allowlist.
Definition: gcs_xcom_interface.h:429
bool m_boot
Definition: gcs_xcom_interface.h:396
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:612
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:633
My_xp_mutex_impl m_wait_for_ssl_init_mutex
Definition: gcs_xcom_interface.h:439
bool is_initialized() override
Method used to report if the binding interface has already been initialized.
Definition: gcs_xcom_interface.cc:704
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:815
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:237
std::map< u_long, Gcs_group_identifier * > m_xcom_configured_groups
Definition: gcs_xcom_interface.h:381
std::vector< Gcs_xcom_node_address * > m_xcom_peers
Definition: gcs_xcom_interface.h:391
My_xp_cond_impl m_wait_for_ssl_init_cond
protects the m_ssl_init_state thread shared variable
Definition: gcs_xcom_interface.h:438
void set_node_address(std::string const &address)
Definition: gcs_xcom_interface.cc:1202
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:421
Gcs_xcom_node_address * get_node_address()
Definition: gcs_xcom_interface.cc:1197
int m_ssl_init_state
Indicates whether SSL has been initialized and if that initialization was successful.
Definition: gcs_xcom_interface.h:435
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:729
Gcs_xcom_interface()
XCom binding private constructor.
Definition: gcs_xcom_interface.cc:213
enum_gcs_error finalize_logging()
Method to finalize the logging and debugging systems.
Definition: gcs_xcom_interface.cc:284
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:409
Gcs_interface_parameters m_initialization_parameters
The initialization parameters provided through the initialize member function.
Definition: gcs_xcom_interface.h:415
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:247
void clean_group_interfaces()
Internal helper method to delete all previously created group interfaces.
Definition: gcs_xcom_interface.cc:843
void set_xcom_group_information(const std::string &group_id)
Definition: gcs_xcom_interface.cc:1158
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:1151
My_xp_socket_util * m_socket_util
Definition: gcs_xcom_interface.h:398
enum_gcs_error configure_message_stages(const Gcs_group_identifier &gid)
Definition: gcs_xcom_interface.cc:1208
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:1288
std::map< std::string, gcs_xcom_group_interfaces * > m_group_interfaces
Definition: gcs_xcom_interface.h:379
void initialize_ssl()
Used to initialize SSL assuming that the necessary parameters have already been read.
Definition: gcs_xcom_interface.cc:878
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:51
Definition: gcs_xcom_state_exchange.h:369
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:213
const char * p
Definition: ctype-mb.cc:1236
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:1712
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:130
Gcs_statistics_interface * statistics_interface
Definition: gcs_xcom_interface.h:133
Gcs_group_management_interface * management_interface
Definition: gcs_xcom_interface.h:134
Gcs_xcom_state_exchange_interface * se
Definition: gcs_xcom_interface.h:141
Gcs_control_interface * control_interface
Definition: gcs_xcom_interface.h:131
Gcs_xcom_view_change_control_interface * vce
Definition: gcs_xcom_interface.h:140
Gcs_communication_interface * communication_interface
Definition: gcs_xcom_interface.h:132
__u_long u_long
Definition: types.h:73
unsigned short xcom_port
Definition: xcom_common.h:45