MySQL  8.0.20
Source Code Documentation
gcs_operations.h
Go to the documentation of this file.
1 /* Copyright (c) 2016, 2020, 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  @retval true if the current view modification is a injected one
182  @retval false otherwise
183  */
185 
186  /**
187  Removes the notifier from the list
188  */
189  void remove_view_notifer(
191 
192  /**
193  Declare the member as being already out of the group.
194  */
196 
197  /**
198  Get the local member identifier.
199 
200  @param[out] identifier The local member identifier when the
201  method is successful
202 
203  @return Operation status
204  @retval 0 OK
205  @retval !=0 Error
206  */
207  int get_local_member_identifier(std::string &identifier);
208 
209  /**
210  Send a message to the group.
211 
212  @param[in] message The message to send
213  @param[in] skip_if_not_initialized If true, the message will not be sent
214  and no errors will returned when the
215  GCS interface is not initialized
216 
217  @return the operation status
218  @retval 0 OK
219  @retval !=0 Error
220  */
221  enum enum_gcs_error send_message(const Plugin_gcs_message &message,
222  bool skip_if_not_initialized = false);
223 
224  /**
225  Forces a new group membership, on which the excluded members
226  will not receive a new view and will be blocked.
227 
228  @param members The list of members, comma
229  separated. E.g., host1:port1,host2:port2
230 
231  @return Operation status
232  @retval 0 OK
233  @retval !=0 Error
234  */
235  int force_members(const char *members);
236 
237  /**
238  Retrieves the minimum supported "write concurrency" value.
239  */
240  uint32_t get_minimum_write_concurrency() const;
241 
242  /**
243  Retrieves the maximum supported "write concurrency" value.
244  */
245  uint32_t get_maximum_write_concurrency() const;
246 
247  /**
248  Retrieves the group's "write concurrency" value.
249 
250  @param[out] write_concurrency A reference to where the group's "write
251  concurrency" will be written to
252 
253  @retval GCS_OK if successful
254  @retval GCS_NOK if unsuccessful
255  */
256  enum enum_gcs_error get_write_concurrency(uint32_t &write_concurrency);
257 
258  /**
259  Reconfigures the group's "write concurrency" value.
260 
261  The caller should ensure that the supplied value is between @c
262  minimum_write_concurrency and @c maximum_write_concurrency.
263 
264  The method is non-blocking, meaning that it shall only send the
265  request to an underlying GCS. The final result can be polled via @c
266  get_write_concurrency.
267 
268  @param new_write_concurrency The desired "write concurrency" value.
269 
270  @retval GCS_OK if successful
271  @retval GCS_NOK if unsuccessful
272  */
273  enum enum_gcs_error set_write_concurrency(uint32_t new_write_concurrency);
274 
275  /**
276  Retrieves the group's "group communication protocol" value.
277 
278  @retval the protocol version
279  */
281 
282  /**
283  Modifies the GCS protocol version in use.
284 
285  The method is non-blocking. It returns a future on which the caller can
286  wait for the action to finish.
287 
288  @param gcs_protocol The desired GCS protocol version
289 
290  @retval {true, future} If successful
291  @retval {false, _} If unsuccessful because @c new_version is unsupported
292  */
293  std::pair<bool, std::future<void>> set_protocol_version(
294  Gcs_protocol_version gcs_protocol);
295 
296  /**
297  Get the maximum protocol version currently supported by the group.
298 
299  @returns the maximum protocol version currently supported by the group
300  */
302 
303  /**
304  Requests GCS to change the maximum size of the XCom cache.
305 
306  @param new_size The new maximum size of the XCom cache.
307 
308  @retval GCS_OK if request successfully scheduled
309  @retval GCS_NOK if GCS is unable to schedule the request
310  */
311  enum enum_gcs_error set_xcom_cache_size(uint64_t new_size);
312 
313  /**
314  * @return the communication engine being used
315  */
316  static const std::string &get_gcs_engine();
317 
318  /**
319  Returns a flag indicating whether or not the component is initialized.
320 
321  @retval true if the component is initialized.
322  @retval false otherwise.
323  */
324  bool is_initialized();
325 
326  private:
327  /**
328  Internal function that configures the debug options that shall be used by
329  GCS.
330  */
331  enum enum_gcs_error do_set_debug_options(std::string &debug_options) const;
334 
335  static const std::string gcs_engine;
338 
339  /** Was this view change injected */
341  /** Is the member leaving*/
343  /** Did the member already left*/
345  /** Is finalize ongoing*/
347 
348  /** List of associated view change notifiers waiting */
349  std::list<Plugin_gcs_view_modification_notifier *> view_change_notifier_list;
350 
352  /** Lock for the list of waiters on a view change */
355 };
356 
357 #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:349
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
Group Replication implementation of Logger_interface.
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:353
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:335
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:340
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:346
Gcs_interface * gcs_interface
Definition: gcs_operations.h:337
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:336
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:351
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:431
Checkable_rwlock * finalize_ongoing_lock
Definition: gcs_operations.h:354
bool leave_coordination_left
Did the member already left.
Definition: gcs_operations.h:344
Gcs_operations()
Default constructor.
Definition: gcs_operations.cc:34
bool leave_coordination_leaving
Is the member leaving.
Definition: gcs_operations.h:342