MySQL  8.0.18
Source Code Documentation
gcs_operations.h
Go to the documentation of this file.
1 /* Copyright (c) 2016, 2019, Oracle and/or its affiliates. All rights reserved.
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_OPERATIONS_INCLUDE
24 #define GCS_OPERATIONS_INCLUDE
25 
27 #include <future>
28 #include <string>
29 #include <utility>
30 
36 
37 /**
38  @class Gcs_operations
39  Coordinates all operations to GCS interface.
40 */
42  public:
43  /**
44  @enum enum_leave_state
45 
46  This enumeration describes the return values when a process tries to leave
47  a group.
48  */
50  /* The request was accepted, the member should now be leaving. */
52  /* The member is already leaving, no point in retrying */
54  /* The member already left */
56  /* There was an error when trying to leave */
58  };
59 
60  /**
61  Default constructor.
62  */
64 
65  /**
66  Destructor.
67  */
68  virtual ~Gcs_operations();
69 
70  /**
71  Initialize the GCS interface.
72 
73  @return the operation status
74  @retval 0 OK
75  @retval !=0 Error
76  */
77  int initialize();
78 
79  /**
80  Finalize the GCS interface.
81  */
82  void finalize();
83 
84  /**
85  Get the group current view.
86 
87  @return a copy of the group current view.
88  NULL if member does not belong to a group..
89  The return value must deallocated by the caller.
90  */
92 
93  /**
94  Configure the GCS interface.
95 
96  @param[in] parameters The configuration parameters
97 
98  @return the operation status
99  @retval 0 OK
100  @retval !=0 Error
101  */
102  enum enum_gcs_error configure(const Gcs_interface_parameters &parameters);
103 
104  /**
105  Reconfigure the GCS interface, i.e. update its configuration parameters.
106 
107  @param[in] parameters The configuration parameters
108 
109  @return the operation status
110  @retval 0 OK
111  @retval !=0 Error
112  */
113  enum enum_gcs_error reconfigure(const Gcs_interface_parameters &parameters);
114 
115  /**
116  Configure the debug options that shall be used by GCS.
117 
118  @param debug_options Set of debug options separated by comma
119 
120  @return the operation status
121  @retval 0 OK
122  @retval !=0 Error
123  */
124  enum enum_gcs_error set_debug_options(std::string &debug_options) const;
125 
126  /**
127  Request server to join the group.
128 
129  @param[in] communication_event_listener The communication event listener
130  @param[in] control_event_listener The control event listener
131  @param[in] view_notifier A view change notifier to know the response
132 
133 
134  @return the operation status
135  @retval 0 OK
136  @retval !=0 Error
137  */
138  enum enum_gcs_error join(
139  const Gcs_communication_event_listener &communication_event_listener,
140  const Gcs_control_event_listener &control_event_listener,
142 
143  /**
144  Returns true if this server belongs to the group.
145  */
146  bool belongs_to_group();
147 
148  /**
149  Request GCS interface to leave the group.
150 
151  @param[in] view_notifier A view change notifier to know the response.
152  Pass a null pointer if you don't want to wait
153 
154  Note: This method only asks to leave, it does not know if request was
155  successful
156 
157  @return the operation status
158  @retval NOW_LEAVING Request accepted, the member is leaving
159  @retval ALREADY_LEAVING The member is already leaving
160  @retval ALREADY_LEFT The member already left
161  @retval ERROR_WHEN_LEAVING An error happened when trying to leave
162  */
164 
165  /**
166  Notify all listeners that a view changed.
167  */
169 
170  /**
171  Notify all listeners that a view was canceled.
172 
173  @param[in] errnr The error associated to this view
174  */
177 
178  /**
179  Checks if the view modification is a injected one.
180 
181  @return
182  @retval true if the current view modification is a injected one
183  @retval false otherwise
184  */
186 
187  /**
188  Removes the notifier from the list
189  */
190  void remove_view_notifer(
192 
193  /**
194  Declare the member as being already out of the group.
195  */
197 
198  /**
199  Get the local member identifier.
200 
201  @param[out] identifier The local member identifier when the
202  method is successful
203 
204  @return Operation status
205  @retval 0 OK
206  @retval !=0 Error
207  */
208  int get_local_member_identifier(std::string &identifier);
209 
210  /**
211  Send a message to the group.
212 
213  @param[in] message The message to send
214  @param[in] skip_if_not_initialized If true, the message will not be sent
215  and no errors will returned when the
216  GCS interface is not initialized
217 
218  @return the operation status
219  @retval 0 OK
220  @retval !=0 Error
221  */
222  enum enum_gcs_error send_message(const Plugin_gcs_message &message,
223  bool skip_if_not_initialized = false);
224 
225  /**
226  Forces a new group membership, on which the excluded members
227  will not receive a new view and will be blocked.
228 
229  @param members The list of members, comma
230  separated. E.g., host1:port1,host2:port2
231 
232  @return Operation status
233  @retval 0 OK
234  @retval !=0 Error
235  */
236  int force_members(const char *members);
237 
238  /**
239  Retrieves the minimum supported "write concurrency" value.
240  */
241  uint32_t get_minimum_write_concurrency() const;
242 
243  /**
244  Retrieves the maximum supported "write concurrency" value.
245  */
246  uint32_t get_maximum_write_concurrency() const;
247 
248  /**
249  Retrieves the group's "write concurrency" value.
250 
251  @param[out] write_concurrency A reference to where the group's "write
252  concurrency" will be written to
253 
254  @retval GCS_OK if successful
255  @retval GCS_NOK if unsuccessful
256  */
257  enum enum_gcs_error get_write_concurrency(uint32_t &write_concurrency);
258 
259  /**
260  Reconfigures the group's "write concurrency" value.
261 
262  The caller should ensure that the supplied value is between @c
263  minimum_write_concurrency and @c maximum_write_concurrency.
264 
265  The method is non-blocking, meaning that it shall only send the
266  request to an underlying GCS. The final result can be polled via @c
267  get_write_concurrency.
268 
269  @param new_write_concurrency The desired "write concurrency" value.
270 
271  @retval GCS_OK if successful
272  @retval GCS_NOK if unsuccessful
273  */
274  enum enum_gcs_error set_write_concurrency(uint32_t new_write_concurrency);
275 
276  /**
277  Retrieves the group's "group communication protocol" value.
278 
279  @retval the protocol version
280  */
282 
283  /**
284  Modifies the GCS protocol version in use.
285 
286  The method is non-blocking. It returns a future on which the caller can
287  wait for the action to finish.
288 
289  @param gcs_protocol The desired GCS protocol version
290 
291  @retval {true, future} If successful
292  @retval {false, _} If unsuccessful because @c new_version is unsupported
293  */
294  std::pair<bool, std::future<void>> set_protocol_version(
295  Gcs_protocol_version gcs_protocol);
296 
297  /**
298  Get the maximum protocol version currently supported by the group.
299 
300  @returns the maximum protocol version currently supported by the group
301  */
303 
304  /**
305  Requests GCS to change the maximum size of the XCom cache.
306 
307  @param new_size The new maximum size of the XCom cache.
308 
309  @retval GCS_OK if request successfully scheduled
310  @retval GCS_NOK if GCS is unable to schedule the request
311  */
312  enum enum_gcs_error set_xcom_cache_size(uint64_t new_size);
313 
314  /**
315  * @return the communication engine being used
316  */
317  static const std::string &get_gcs_engine();
318 
319  /**
320  Returns a flag indicating whether or not the component is initialized.
321 
322  @retval true if the component is initialized.
323  @retval false otherwise.
324  */
325  bool is_initialized();
326 
327  private:
328  /**
329  Internal function that configures the debug options that shall be used by
330  GCS.
331  */
332  enum enum_gcs_error do_set_debug_options(std::string &debug_options) const;
335 
336  static const std::string gcs_engine;
339 
340  /** Was this view change injected */
342  /** Is the member leaving*/
344  /** Did the member already left*/
346  /** Is finalize ongoing*/
348 
349  /** List of associated view change notifiers waiting */
350  std::list<Plugin_gcs_view_modification_notifier *> view_change_notifier_list;
351 
353  /** Lock for the list of waiters on a view change */
356 };
357 
358 #endif /* GCS_OPERATIONS_INCLUDE */
std::list< Plugin_gcs_view_modification_notifier * > view_change_notifier_list
List of associated view change notifiers waiting.
Definition: gcs_operations.h:350
enum enum_gcs_error do_set_debug_options(std::string &debug_options) const
Internal function that configures the debug options that shall be used by GCS.
Definition: gcs_operations.cc:138
void finalize()
Finalize the GCS interface.
Definition: gcs_operations.cc:97
This interface must be implemented by all specific binding implementations as its entry point...
Definition: gcs_interface.h:81
This class is to be used to provide parameters to bindings in a transparent and generic way...
Definition: gcs_types.h:58
enum enum_gcs_error set_debug_options(std::string &debug_options) const
Configure the debug options that shall be used by GCS.
Definition: gcs_operations.cc:162
uint32_t get_maximum_write_concurrency() const
Retrieves the maximum supported "write concurrency" value.
Definition: gcs_operations.cc:588
Definition: gcs_operations.h:51
Definition: gcs_logger.h:35
enum enum_gcs_error join(const Gcs_communication_event_listener &communication_event_listener, const Gcs_control_event_listener &control_event_listener, Plugin_gcs_view_modification_notifier *view_notifier)
Request server to join the group.
Definition: gcs_operations.cc:175
enum enum_gcs_error configure(const Gcs_interface_parameters &parameters)
Configure the GCS interface.
Definition: gcs_operations.cc:114
int initialize()
Initialize the GCS interface.
Definition: gcs_operations.cc:63
enum_leave_state
This enumeration describes the return values when a process tries to leave a group.
Definition: gcs_operations.h:49
Coordinates all operations to GCS interface.
Definition: gcs_operations.h:41
This is the base GCS plugin message.
Definition: gcs_plugin_messages.h:63
Checkable_rwlock * view_observers_lock
Lock for the list of waiters on a view change.
Definition: gcs_operations.h:354
enum enum_gcs_error set_write_concurrency(uint32_t new_write_concurrency)
Reconfigures the group&#39;s "write concurrency" value.
Definition: gcs_operations.cc:563
enum_gcs_error
This enumeration describes errors which can occur during group communication operations.
Definition: gcs_types.h:40
static const std::string gcs_engine
Definition: gcs_operations.h:336
void notify_of_view_change_cancellation(int errnr=GROUP_REPLICATION_CONFIGURATION_ERROR)
Notify all listeners that a view was canceled.
Definition: gcs_operations.cc:305
virtual ~Gcs_operations()
Destructor.
Definition: gcs_operations.cc:57
Gcs_protocol_version
The GCS protocol versions.
Definition: gcs_types.h:127
bool injected_view_modification
Was this view change injected.
Definition: gcs_operations.h:341
bool is_initialized()
Returns a flag indicating whether or not the component is initialized.
Definition: gcs_operations.cc:689
This interface is implemented by those who wish to receive messages.
Definition: gcs_communication_event_listener.h:35
enum enum_gcs_error send_message(const Plugin_gcs_message &message, bool skip_if_not_initialized=false)
Send a message to the group.
Definition: gcs_operations.cc:398
bool finalize_ongoing
Is finalize ongoing.
Definition: gcs_operations.h:347
Gcs_interface * gcs_interface
Definition: gcs_operations.h:338
This interface is implemented by those who wish to receive Control Interface notifications.
Definition: gcs_control_event_listener.h:51
Gcs_protocol_version get_maximum_protocol_version()
Get the maximum protocol version currently supported by the group.
Definition: gcs_operations.cc:641
void leave_coordination_member_left()
Declare the member as being already out of the group.
Definition: gcs_operations.cc:330
Gcs_group_management_interface * get_gcs_group_manager() const
Definition: gcs_operations.cc:522
std::pair< bool, std::future< void > > set_protocol_version(Gcs_protocol_version gcs_protocol)
Modifies the GCS protocol version in use.
Definition: gcs_operations.cc:653
Definition: gcs_operations.h:53
uint32_t get_minimum_write_concurrency() const
Retrieves the minimum supported "write concurrency" value.
Definition: gcs_operations.cc:576
int get_local_member_identifier(std::string &identifier)
Get the local member identifier.
Definition: gcs_operations.cc:376
Gcs_gr_logger_impl gcs_logger
Definition: gcs_operations.h:337
This interface represents all the communication facilities that a binding implementation should provi...
Definition: gcs_communication_interface.h:87
This represents the membership view that a member has from a group.
Definition: gcs_view.h:54
static const std::string & get_gcs_engine()
Definition: gcs_operations.cc:687
void remove_view_notifer(Plugin_gcs_view_modification_notifier *view_notifier)
Removes the notifier from the list.
Definition: gcs_operations.cc:321
enum enum_gcs_error set_xcom_cache_size(uint64_t new_size)
Requests GCS to change the maximum size of the XCom cache.
Definition: gcs_operations.cc:670
bool is_injected_view_modification()
Checks if the view modification is a injected one.
Definition: gcs_operations.cc:314
Definition: gcs_operations.h:57
Gcs_communication_interface * get_gcs_communication() const
Definition: gcs_operations.cc:600
Definition: gcs_operations.h:55
int force_members(const char *members)
Forces a new group membership, on which the excluded members will not receive a new view and will be ...
Definition: gcs_operations.cc:442
Gcs_view * get_current_view()
Get the group current view.
Definition: gcs_operations.cc:357
enum_leave_state leave(Plugin_gcs_view_modification_notifier *view_notifier)
Request GCS interface to leave the group.
Definition: gcs_operations.cc:246
Checkable_rwlock * gcs_operations_lock
Definition: gcs_operations.h:352
enum enum_gcs_error get_write_concurrency(uint32_t &write_concurrency)
Retrieves the group&#39;s "write concurrency" value.
Definition: gcs_operations.cc:550
Definition: gcs_view_modification_notifier.h:35
void notify_of_view_change_end()
Notify all listeners that a view changed.
Definition: gcs_operations.cc:296
bool belongs_to_group()
Returns true if this server belongs to the group.
Definition: gcs_operations.cc:228
#define GROUP_REPLICATION_CONFIGURATION_ERROR
Definition: plugin_constants.h:36
enum enum_gcs_error reconfigure(const Gcs_interface_parameters &parameters)
Reconfigure the GCS interface, i.e.
Definition: gcs_operations.cc:126
Gcs_protocol_version get_protocol_version()
Retrieves the group&#39;s "group communication protocol" value.
Definition: gcs_operations.cc:629
Definition: gcs_group_management_interface.h:28
This has the functionality of mysql_rwlock_t, with two differences:
Definition: rpl_gtid.h:429
Checkable_rwlock * finalize_ongoing_lock
Definition: gcs_operations.h:355
bool leave_coordination_left
Did the member already left.
Definition: gcs_operations.h:345
Gcs_operations()
Default constructor.
Definition: gcs_operations.cc:34
bool leave_coordination_leaving
Is the member leaving.
Definition: gcs_operations.h:343