MySQL 9.1.0
Source Code Documentation
gcs_interface.h
Go to the documentation of this file.
1/* Copyright (c) 2014, 2024, 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 designed to work 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 either included with
13 the program or referenced in the documentation.
14
15 This program is distributed in the hope that it will be useful,
16 but WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 GNU General Public License, version 2.0, for more details.
19
20 You should have received a copy of the GNU General Public License
21 along with this program; if not, write to the Free Software
22 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
23
24#ifndef GCS_INTERFACE_INCLUDED
25#define GCS_INTERFACE_INCLUDED
26
27#include <string>
28
35
36/**
37 * @brief Runtime external resources that should be provided to an instance of
38 * Gcs_interface
39 *
40 */
42 /**
43 * @brief External network provider, if needed.
44 *
45 */
46 std::shared_ptr<Network_provider> provider;
47
48 /**
49 * @brief Provider of Network Namespace services
50 *
51 */
53};
54
55/**
56 @class Gcs_interface
57
58 This interface must be implemented by all specific binding implementations
59 as its entry point.
60
61 It should afterwards be distributed via a Factory, in order to allow
62 its transparent instantiation.
63
64 All of the interfaces are group-oriented, meaning that all methods that
65 allow the retrieval of sub-interfaces (control, communication,
66 statistics) are oriented to serve all operations to a single group.
67
68 It provides two main functionalities:
69 - Binding startup and finish;
70 - Allow access to the control, communication and statistics interface.
71
72 A typical usage of this interface shall be:
73
74 @code{.cpp}
75 Gcs_interface *group_if= new My_GCS_Gcs_interface();
76
77 Gcs_interface_parameters params;
78 params.add_parameter("name1", "value2");
79 if (!group_if->is_initialized())
80 {
81 group_if->initialize(params);
82 }
83
84 // Inject a logger if wanted
85 Logger_interface *logger= new My_GCS_Logger_interface();
86 group_if->set_logger(logger);
87
88 Gcs_group_identifier *group_id= new Gcs_group_identifier("my_group");
89
90 Gcs_control_interface *ctrl_if= group_if->get_control_session(group_id);
91
92 ctrl_if->join(); // notice here that group id is not used anymore...
93
94 // Do some operations here, retrieve other interfaces...
95
96 ctrl_if->leave();
97
98 group_if->finalize();
99 @endcode
100*/
102 public:
103 /**
104 Method used by a binding implementation in order to implement any
105 internal startup procedure.
106
107 @retval GCS_OK in case of everything goes well. Any other value of
108 gcs_error in case of error.
109 */
110
112 const Gcs_interface_parameters &interface_params) = 0;
113
114 /**
115 Method used to report if the binding interface has already been
116 initialized.
117
118 @retval true if already initialized
119 */
120
121 virtual bool is_initialized() = 0;
122
123 /**
124 Method used by a binding implementation in order to implement any type of
125 necessary dynamic reconfiguration.
126
127 An example of this could be an underlying GCS that needs to adjust itself
128 to changes in a group. Note, however, that the method must be only used
129 when the system is not running in order to avoid possible concurrency
130 issues. Using cached information by the caller, after this member function
131 has been called, results in undefined behavior.
132
133 @retval GCS_OK in case of everything goes well. Any other value of
134 gcs_error in case of error.
135 */
136
138 const Gcs_interface_parameters &interface_params) = 0;
139
140 /**
141 Method used by a binding implementation in order to implement any
142 internal shutdown procedure.
143
144 @retval GCS_OK in case of everything goes well. Any other value of
145 gcs_error in case of error
146 */
147
149
150 /**
151 Method that retrieves the binding implementation of the Control Session
152 interface.
153
154 @param[in] group_identifier the group in which this implementation pertains
155
156 @return A valid reference to a gcs_control_interface implementation, NULL,
157 in case of error.
158 */
159
161 const Gcs_group_identifier &group_identifier) = 0;
162
163 /**
164 Method that retrieves the binding implementation of the Communication
165 Session interface.
166
167 @param[in] group_identifier the group in which this implementation pertains
168
169 @return A valid reference to a gcs_communication_interface implementation.
170 NULL, in case of error.
171 */
172
174 const Gcs_group_identifier &group_identifier) = 0;
175
176 /**
177 Method that retrieves the binding implementation of the Statistics
178 interface.
179
180 @param[in] group_identifier the group in which this implementation pertains
181
182 @return A valid reference to a gcs_statistics_interface implementation.
183 NULL, in case of error.
184 */
185
187 const Gcs_group_identifier &group_identifier) = 0;
188
189 /**
190 Method that retrieves the binding implementation of the Group
191 Management Session interface.
192
193 @param[in] group_identifier the group in which this implementation pertains
194
195 @return A valid reference to a Gcs_group_management_interface
196 implementation, NULL, in case of error.
197 */
199 const Gcs_group_identifier &group_identifier) = 0;
200
201 /**
202 Method that retrieves the binding implementation of the Group
203 Management Session interface.
204
205 @param[in] logger the logger implementation for GCS to use
206
207 @retval GCS_OK in case of everything goes well. Any other value of
208 gcs_error in case of error
209 */
211
212 /**
213 * @brief Set the up runtime resources
214 *
215 * @param reqs a Gcs_interface_runtime_requirements filled with all the
216 * requirements
217 */
220
221 /**
222 * @brief Does the necessary cleanup for runtime resources
223 *
224 * @param reqs a Gcs_interface_runtime_requirements filled with all the
225 * requirements and their references
226 */
229
230 virtual ~Gcs_interface() = default;
231};
232
233/**
234 Enum that lists all implementations of Gcs_interface available to be
235 returned
236*/
238 /* XCom binding implementation */
240 NONE
242
243/**
244 @class Gcs_interface_factory
245
246 @brief This class shall be used by an API user as an aggregator utility to
247 retrieve implementations of Gcs_interface.
248*/
250 public:
251 /**
252 Static method that allows retrieval of an instantiated implementation
253 of a binding implementation.
254
255 @param[in] binding an enum value of the binding implementation to retrieve.
256
257 @return An instantiated object of a binding implementation.NULL in case of
258 error.
259 */
260
263
264 /**
265 Static method that allows retrieval of an instantiated implementation
266 of a binding implementation.
267
268 @param[in] binding a string matching the enum available_interfaces value of
269 the binding implementation to retrieve.
270
271 @return An instantiated object of a binding implementation. NULL in case of
272 error.
273 */
274
276 const std::string &binding);
277
278 /**
279 Static method that allows the cleanup of the Gcs_interface singleton
280 instance according to the binding parameter.
281
282 @param[in] binding an enum value of the binding implementation to retrieve.
283 */
284
285 static void cleanup(enum_available_interfaces binding);
286
287 /**
288 Static method that allows the cleanup of the Gcs_interface singleton
289 instance according to the binding parameter.
290
291 @param[in] binding a string matching the enum available_interfaces value of
292 the binding implementation to retrieve.
293 */
294
295 static void cleanup(const std::string &binding);
296
297 /**
298 Static method that cleans up thread-local communication resources in the
299 Gcs_interface singleton instance according to the binding parameter.
300 This is required by the XCom backend when SSL is provided by OpenSSL.
301
302 @param[in] binding an enum value of the binding implementation to retrieve.
303 */
304
307
308 /**
309 Static method that cleans up thread-local communication resources in the
310 Gcs_interface singleton instance according to the binding parameter.
311 This is required by the XCom backend when SSL is provided by OpenSSL.
312
313 @param[in] binding a string matching the enum available_interfaces value of
314 the binding implementation to retrieve.
315 */
316
318 const std::string &binding);
319
320 private:
321 static enum_available_interfaces from_string(const std::string &binding);
322};
323
324#endif // gcs_interface_INCLUDED
This interface represents all the communication facilities that a binding implementation should provi...
Definition: gcs_communication_interface.h:90
This interface represents all the control functionalities that a binding implementation must provide.
Definition: gcs_control_interface.h:111
This represents the unique identification of a group.
Definition: gcs_group_identifier.h:35
Definition: gcs_group_management_interface.h:32
This class shall be used by an API user as an aggregator utility to retrieve implementations of Gcs_i...
Definition: gcs_interface.h:249
static void cleanup_thread_communication_resources(enum_available_interfaces binding)
Static method that cleans up thread-local communication resources in the Gcs_interface singleton inst...
Definition: gcs_interface_factory.cc:83
static void cleanup(enum_available_interfaces binding)
Static method that allows the cleanup of the Gcs_interface singleton instance according to the bindin...
Definition: gcs_interface_factory.cc:64
static enum_available_interfaces from_string(const std::string &binding)
Definition: gcs_interface_factory.cc:94
static Gcs_interface * get_interface_implementation(enum_available_interfaces binding)
Static method that allows retrieval of an instantiated implementation of a binding implementation.
Definition: gcs_interface_factory.cc:34
This class is to be used to provide parameters to bindings in a transparent and generic way.
Definition: gcs_types.h:59
This interface must be implemented by all specific binding implementations as its entry point.
Definition: gcs_interface.h:101
virtual Gcs_group_management_interface * get_management_session(const Gcs_group_identifier &group_identifier)=0
Method that retrieves the binding implementation of the Group Management Session interface.
virtual Gcs_communication_interface * get_communication_session(const Gcs_group_identifier &group_identifier)=0
Method that retrieves the binding implementation of the Communication Session interface.
virtual enum_gcs_error finalize()=0
Method used by a binding implementation in order to implement any internal shutdown procedure.
virtual enum_gcs_error set_logger(Logger_interface *logger)=0
Method that retrieves the binding implementation of the Group Management Session interface.
virtual enum_gcs_error cleanup_runtime_resources(Gcs_interface_runtime_requirements &reqs)=0
Does the necessary cleanup for runtime resources.
virtual enum_gcs_error setup_runtime_resources(Gcs_interface_runtime_requirements &reqs)=0
Set the up runtime resources.
virtual bool is_initialized()=0
Method used to report if the binding interface has already been initialized.
virtual Gcs_control_interface * get_control_session(const Gcs_group_identifier &group_identifier)=0
Method that retrieves the binding implementation of the Control Session interface.
virtual ~Gcs_interface()=default
virtual enum_gcs_error initialize(const Gcs_interface_parameters &interface_params)=0
Method used by a binding implementation in order to implement any internal startup procedure.
virtual enum_gcs_error configure(const Gcs_interface_parameters &interface_params)=0
Method used by a binding implementation in order to implement any type of necessary dynamic reconfigu...
virtual Gcs_statistics_interface * get_statistics(const Gcs_group_identifier &group_identifier)=0
Method that retrieves the binding implementation of the Statistics interface.
This interface represents all statistics that a binding implementation should provide.
Definition: gcs_statistics_interface.h:49
Logger interface that must be used to define a logger object.
Definition: gcs_logging.h:125
Class that provides Network Namespace services.
Definition: network_provider.h:242
enum_available_interfaces
Enum that lists all implementations of Gcs_interface available to be returned.
Definition: gcs_interface.h:237
@ XCOM
Definition: gcs_interface.h:239
@ NONE
Definition: gcs_interface.h:240
enum_gcs_error
This enumeration describes errors which can occur during group communication operations.
Definition: gcs_types.h:41
static Logger logger
The "top-level" logger used when no connection context is given.
Definition: test_trace_plugin.cc:296
Runtime external resources that should be provided to an instance of Gcs_interface.
Definition: gcs_interface.h:41
std::shared_ptr< Network_provider > provider
External network provider, if needed.
Definition: gcs_interface.h:46
Network_namespace_manager * namespace_manager
Provider of Network Namespace services.
Definition: gcs_interface.h:52