MySQL  8.0.22
Source Code Documentation
gcs_xcom_notification.h
Go to the documentation of this file.
1 /* Copyright (c) 2017, 2020, 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_NOTIFICATION_INCLUDED
24 #define GCS_XCOM_NOTIFICATION_INCLUDED
25 
26 #include <queue>
27 
36 #include "plugin/group_replication/libmysqlgcs/xdr_gen/xcom_vp.h"
37 
38 /**
39  Abstract class that defines a notification that will be sent from XCOM
40  to MySQL GCS or from an user thread to MySQL GCS.
41 
42  This is a very simple implementation that chooses simplicity over flexibility.
43  For example, it does not support notifications on member functions (i.e.
44  methods) and a new notification generates some duplicated code. Note that
45  these limitations could be eliminated with the use of generalized functors.
46  However, this solution would have increased code complexity as we cannot
47  use C++ 11.
48 
49  Note also that we have used the term functor here to designed the pointer
50  to the callback function.
51 
52  We will revisit this decision in the future if any of the choices become a
53  problem and when we start using C++ 11.
54 */
56  public:
57  /**
58  Constructor for Gcs_xcom_notification which an abstract class
59  that represents notifications sent from XCOM to MySQL GCS.
60 
61  Such notifications are read from a queue by a MySQL GCS' thread,
62  specifically by the Gcs_xcom_engine which is responsible for
63  executing them.
64 
65  The main loop in the GCS_xcom_engine is stopped when the
66  execution returns true.
67  */
68 
69  explicit Gcs_xcom_notification() {}
70 
71  /**
72  Task implemented by this notification which calls do_execute.
73  */
74 
75  virtual bool operator()() = 0;
76 
77  /**
78  Destructor for the Gcs_xcom_notification.
79  */
80 
82 
83  private:
84  /*
85  Disabling the copy constructor and assignment operator.
86  */
89 };
90 
91 typedef void(xcom_initialize_functor)();
92 typedef void(xcom_finalize_functor)();
94  public:
95  /**
96  Constructor for Gcs_xcom_engine.
97  */
98 
99  explicit Gcs_xcom_engine();
100 
101  /**
102  Destructor for Gcs_xcom_engine.
103  */
104 
105  ~Gcs_xcom_engine();
106 
107  /**
108  Start the notification processing by spwaning a thread that will be
109  responsible for reading all incoming notifications.
110  */
111 
112  void initialize(xcom_initialize_functor *functor);
113 
114  /**
115  Finalize the notification processing by stopping the thread that is
116  responsible for reading all incoming notifications. Optionally, a
117  callback function can be scheduled in order to do some clean up.
118 
119  When the finalize has been executed the engine will not accept any
120  new incoming notification, the processing thread will be stopped
121  and the optional callback will be the last one called if there is
122  any.
123 
124  @param functor Last callback function to be executed.
125  */
126 
127  void finalize(xcom_finalize_functor *functor);
128 
129  /**
130  Process notifications from the incoming queue until an empty
131  notifications comes in.
132  */
133 
134  void process();
135 
136  /**
137  Clean up the notification queue and also forbid any incoming
138  notitification to be added to the queue.
139  */
140 
141  void cleanup();
142 
143  /**
144  Push a notification to the queue.
145 
146 
147  @param notification Pointer to notification to be queued.
148 
149  @return If the request was successfully enqueued true is
150  returned, otherwise, false is returned.
151  */
152 
153  bool push(Gcs_xcom_notification *notification);
154 
155  private:
156  /*
157  Condition variable used to inform when there are new
158  notifications in the queue.
159  */
161 
162  /*
163  Mutex used to prevent concurrent access to the queue.
164  */
166 
167  /*
168  Queue that holds notifications from XCOM.
169  */
170  std::queue<Gcs_xcom_notification *> m_notification_queue;
171 
172  /*
173  Thread responsible for reading the queue and process
174  the notifications enqueued by XCOM.
175  */
177 
178  /*
179  Whether the engine is accepting new notifications or not.
180  */
182 
183  /*
184  Disabling the copy constructor and assignment operator.
185  */
188 };
189 
190 /**
191  Template that defines whether a notification shall make the
192  engine stop or not.
193 
194  class X_notification : public Paremetrized_notification<true>
195  {
196  public:
197  void do_execute()
198  {
199  // Do something.
200  }
201  }
202 */
203 template <bool stop>
205  public:
206  /**
207  Constructor for Parameterized_notification.
208  */
209 
211 
212  /**
213  Destructor for Parameterized_notification.
214  */
215 
217 
218  /**
219  Task implemented by this notification which calls do_execute.
220 
221  Return whether the notification should stop the engine or not.
222  */
223 
224  bool operator()() override {
225  do_execute();
226 
227  return stop;
228  }
229 
230  private:
231  /**
232  Method that must be implemented buy the different types of
233  notifications.
234  */
235 
236  virtual void do_execute() = 0;
237 
238  /*
239  Disabling the copy constructor and assignment operator.
240  */
243 };
244 
245 /**
246  Notification used to stop the Gcs_xcom_engine.
247 */
249  public:
250  /**
251  Constructor for Finalize_notification.
252 
253  @param gcs_engine Reference to the engine.
254  @param functor Pointer to a function that contains that actual
255  core of the execution.
256  */
257 
259  xcom_finalize_functor *functor);
260 
261  /**
262  Destructor for Finalize_notification.
263  */
264 
265  ~Finalize_notification() override;
266 
267  private:
268  /**
269  Task implemented by this notification.
270  */
271 
272  void do_execute() override;
273 
274  /**
275  Pointer to the MySQL GCS Engine.
276  */
278 
279  /*
280  Pointer to a function that contains that actual core of the
281  execution.
282  */
284 
285  /*
286  Disabling the copy constructor and assignment operator.
287  */
290 };
291 
293  public:
294  /**
295  Constructor for Initialize_notification.
296 
297  @param functor Pointer to a function that contains that actual
298  core of the execution.
299  */
300 
302 
303  /**
304  Destructor for Initialize_notification.
305  */
306 
307  ~Initialize_notification() override;
308 
309  private:
310  /**
311  Task implemented by this notification.
312  */
313 
314  void do_execute() override;
315 
316  /*
317  Pointer to a function that contains that actual core of the
318  execution.
319  */
321 
322  /*
323  Disabling the copy constructor and assignment operator.
324  */
327 };
328 
329 typedef void(xcom_receive_data_functor)(synode_no, Gcs_xcom_nodes *, synode_no,
330  u_int, char *);
331 /**
332  Notification used to inform that data has been totally ordered.
333 */
335  public:
336  /**
337  Constructor for Data_notification.
338 
339  @param functor Pointer to a function that contains that actual
340  core of the execution.
341  @param message_id Messaged Id.
342  @param xcom_nodes Set of nodes that participated in the consensus
343  to deliver the message.
344  @param size Size of the message's content.
345  @param last_removed The synode_no of the last message removed from the
346  XCom cache. Used to update the suspicions manager.
347  @param data This is the message's content.
348  */
349 
351  synode_no message_id, Gcs_xcom_nodes *xcom_nodes,
352  synode_no last_removed, u_int size, char *data);
353 
354  /**
355  Destructor for Data_notification
356  */
357 
358  ~Data_notification() override;
359 
360  private:
361  /**
362  Task implemented by this notification which calls the functor
363  with the parameters provided in the contructor.
364  */
365 
366  void do_execute() override;
367 
368  /*
369  Pointer to a function that contains that actual core of the
370  execution.
371  */
373 
374  /*
375  Messaged Id.
376  */
377  synode_no m_message_id;
378 
379  /*
380  Set of nodes that participated in the consensus to deliver the
381  message.
382  */
384 
385  /*
386  The synode_no of the last message removed from the XCom cache. Used to
387  update the suspicions manager, which needs this value to know if a
388  suspected node has gone too far behind the group.
389  */
390  synode_no m_last_removed;
391 
392  /*
393  Size of the message's content.
394  */
396 
397  /*
398  This is the message's content.
399  */
400  char *m_data;
401 
402  /*
403  Disabling the copy constructor and assignment operator.
404  */
407 };
408 
409 typedef void(xcom_status_functor)(int);
410 /**
411  Notification used to inform that has been a change in XCOM's state
412  machine such as it has started up or shut down.
413 */
415  public:
416  /**
417  Constructor for Status_notification.
418 
419  @param functor Pointer to a function that contains that actual
420  core of the execution.
421  @param status XCOM's status.
422  */
423 
424  explicit Status_notification(xcom_status_functor *functor, int status);
425 
426  /**
427  Destructor for Status_notification.
428  */
429 
430  ~Status_notification() override;
431 
432  private:
433  /**
434  Task implemented by this notification.
435  */
436 
437  void do_execute() override;
438 
439  /*
440  Pointer to a function that contains that actual core of the
441  execution.
442  */
444 
445  /*
446  XCOM's status.
447  */
448  int m_status;
449 
450  /*
451  Disabling the copy constructor and assignment operator.
452  */
455 };
456 
457 typedef void(xcom_global_view_functor)(synode_no, synode_no, Gcs_xcom_nodes *,
458  xcom_event_horizon, synode_no);
459 /**
460  Notification used to inform there have been change to the configuration,
461  i.e. nodes have been added, removed or considered dead/faulty.
462 */
464  public:
465  /**
466  Constructor for Global_view_notification.
467 
468  @param functor Pointer to a function that contains that actual
469  core of the execution.
470  @param config_id Message Id when the configuration, i.e. nodes,
471  was installed.
472  @param message_id Messaged Id.
473  @param xcom_nodes Set of nodes that participated in the consensus
474  to deliver the message.
475  @param event_horizon the XCom configuration's event horizon
476  @param max_synode XCom max synode
477  */
478 
480  synode_no config_id, synode_no message_id,
481  Gcs_xcom_nodes *xcom_nodes,
482  xcom_event_horizon event_horizon,
483  synode_no max_synode);
484 
485  /**
486  Destructor for Global_view_notification.
487  */
488 
489  ~Global_view_notification() override;
490 
491  private:
492  /**
493  Task implemented by this notification.
494  */
495 
496  void do_execute() override;
497 
498  /*
499  Pointer to a function that contains that actual core of the
500  execution.
501  */
503 
504  /*
505  Message Id when the configuration, i.e. nodes, was installed.
506  */
507  synode_no m_config_id;
508 
509  /*
510  Messaged Id.
511  */
512 
513  synode_no m_message_id;
514 
515  /*
516  Set of nodes that participated in the consensus to deliver
517  the message.
518  */
520 
521  /*
522  Event horizon of the configuration.
523  */
524  xcom_event_horizon m_event_horizon;
525 
526  /*
527  The highest synode_no seen by the group at the time the view is thrown.
528  Used by the suspicions manager to identify when suspected nodes have
529  lost messages that they need to recover.
530  */
531  synode_no m_max_synode;
532 
533  /*
534  Disabling the copy constructor and assignment operator.
535  */
538 };
539 
540 typedef void(xcom_local_view_functor)(synode_no, Gcs_xcom_nodes *, synode_no);
541 /**
542  Notification used to provide hints on nodes' availability.
543 */
545  public:
546  /**
547  Constructor for Local_view_notification.
548 
549  @param functor Pointer to a function that contains that actual
550  core of the execution.
551  @param config_id Configuration ID to which this view pertains to
552  @param xcom_nodes Set of nodes that were defined when the notification
553  happened.
554  @param max_synode XCom max synode
555  */
556 
558  synode_no config_id,
559  Gcs_xcom_nodes *xcom_nodes,
560  synode_no max_synode);
561 
562  /**
563  Destructor for Local_view_notification.
564  */
565  ~Local_view_notification() override;
566 
567  private:
568  /**
569  Task implemented by this notification.
570  */
571 
572  void do_execute() override;
573 
574  /*
575  Pointer to a function that contains that actual core of the
576  execution.
577  */
579 
580  /*
581  Configuration ID.
582  */
583  synode_no m_config_id;
584 
585  /*
586  Set of nodes that were defined when the notification happened.
587  */
589 
590  /*
591  The highest synode_no seen by the group at the time the view is thrown.
592  Used by the suspicions manager to identify when suspected nodes have
593  lost messages that they need to recover.
594  */
595  synode_no m_max_synode;
596 
597  /*
598  Disabling the copy constructor and assignment operator.
599  */
602 };
603 
605 /**
606  Notification used to make a node join or leave the cluster, provided
607  the system was already initialized.
608 */
610  public:
611  /**
612  Constructor for Control_notification.
613 
614  @param functor Pointer to a function that contains that actual
615  core of the execution.
616  @param control_if Reference to Control Interface.
617  */
618 
619  explicit Control_notification(xcom_control_functor *functor,
620  Gcs_control_interface *control_if);
621 
622  /**
623  Destructor for Control_notification.
624  */
625  ~Control_notification() override;
626 
627  private:
628  /**
629  Task implemented by this notification.
630  */
631 
632  void do_execute() override;
633 
634  /*
635  Pointer to a function that contains that actual core of the
636  execution.
637  */
639 
640  /*
641  Pointer to a function that contains that actual core of the
642  execution.
643  */
645 
646  /*
647  Disabling the copy constructor and assignment operator.
648  */
651 };
652 
653 typedef void(xcom_expel_functor)(void);
654 /**
655  Notification used to inform that the node has been expelled or is about
656  to be.
657 */
659  public:
660  /**
661  Constructor for Expel_notification.
662 
663  @param functor Pointer to a function that contains that actual
664  core of the execution.
665  */
666 
667  explicit Expel_notification(xcom_expel_functor *functor);
668 
669  /**
670  Destructor for Expel_notification.
671  */
672 
673  ~Expel_notification() override;
674 
675  private:
676  /**
677  Task implemented by this notification.
678  */
679 
680  void do_execute() override;
681 
682  /*
683  Pointer to a function that contains that actual core of the
684  execution.
685  */
687 
688  /*
689  Disabling the copy constructor and assignment operator.
690  */
693 };
694 
698 /**
699  Notification used to finish a protocol change.
700 */
702  public:
703  /**
704  Constructor for Protocol_change_notification.
705 
706  @param functor Pointer to a function that contains that actual
707  core of the execution.
708  @param protocol_changer communication protocol change logic
709  @param tag tag reference to the lock
710  */
711 
714  Gcs_xcom_communication_protocol_changer *protocol_changer,
715  Gcs_tagged_lock::Tag const tag);
716 
717  /**
718  Destructor for Protocol_change_notification.
719  */
720  ~Protocol_change_notification() override;
721 
722  private:
723  /**
724  Task implemented by this notification.
725  */
726 
727  void do_execute() override;
728 
729  /*
730  Pointer to a function that contains that actual core of the
731  execution.
732  */
734 
735  /*
736  Pointer to a function that contains that actual core of the
737  execution.
738  */
740 
742 
743  /*
744  Disabling the copy constructor and assignment operator.
745  */
748 };
749 
750 #endif // GCS_XCOM_NOTIFICATION_INCLUDED
Gcs_xcom_notification & operator=(Gcs_xcom_notification const &)
My_xp_thread_impl m_engine_thread
Definition: gcs_xcom_notification.h:176
bool m_schedule
Definition: gcs_xcom_notification.h:181
void() xcom_expel_functor(void)
Definition: gcs_xcom_notification.h:653
Gcs_tagged_lock::Tag const m_tag
Definition: gcs_xcom_notification.h:741
xcom_event_horizon m_event_horizon
Definition: gcs_xcom_notification.h:524
int m_status
Definition: gcs_xcom_notification.h:448
Notification used to stop the Gcs_xcom_engine.
Definition: gcs_xcom_notification.h:248
void() xcom_finalize_functor()
Definition: gcs_xcom_notification.h:92
Gcs_xcom_nodes * m_xcom_nodes
Definition: gcs_xcom_notification.h:588
Gcs_xcom_communication_protocol_changer * m_protocol_changer
Definition: gcs_xcom_notification.h:739
Definition: my_xp_cond.h:133
synode_no m_max_synode
Definition: gcs_xcom_notification.h:595
synode_no max_synode
Definition: xcom_base.cc:386
virtual bool operator()()=0
Task implemented by this notification which calls do_execute.
std::queue< Gcs_xcom_notification * > m_notification_queue
Definition: gcs_xcom_notification.h:170
synode_no m_config_id
Definition: gcs_xcom_notification.h:507
Gcs_xcom_notification()
Constructor for Gcs_xcom_notification which an abstract class that represents notifications sent from...
Definition: gcs_xcom_notification.h:69
xcom_finalize_functor * m_functor
Definition: gcs_xcom_notification.h:283
Implements the communication protocol change logic.
Definition: gcs_xcom_communication_protocol_changer.h:216
bool initialize(THD *thd)
Initialize the dictionary while starting the server for the first time.
Definition: bootstrapper.cc:877
static bool push(mem_root_deque< Item *> *items, qep_row::mem_root_str &s, Item_null *nil)
Definition: opt_explain_traditional.cc:93
virtual ~Gcs_xcom_notification()
Destructor for the Gcs_xcom_notification.
Definition: gcs_xcom_notification.h:81
xcom_protocol_change_functor * m_functor
Definition: gcs_xcom_notification.h:733
Template that defines whether a notification shall make the engine stop or not.
Definition: gcs_xcom_notification.h:204
My_xp_cond_impl m_wait_for_notification_cond
Definition: gcs_xcom_notification.h:160
Notification used to finish a protocol change.
Definition: gcs_xcom_notification.h:701
void() xcom_status_functor(int)
Definition: gcs_xcom_notification.h:409
My_xp_mutex_impl m_wait_for_notification_mutex
Definition: gcs_xcom_notification.h:165
synode_no m_last_removed
Definition: gcs_xcom_notification.h:390
Definition: gcs_xcom_notification.h:93
Notification used to inform that the node has been expelled or is about to be.
Definition: gcs_xcom_notification.h:658
Definition: my_xp_thread.h:136
Notification used to inform that data has been totally ordered.
Definition: gcs_xcom_notification.h:334
void() xcom_global_view_functor(synode_no, synode_no, Gcs_xcom_nodes *, xcom_event_horizon, synode_no)
Definition: gcs_xcom_notification.h:457
synode_no m_max_synode
Definition: gcs_xcom_notification.h:531
xcom_control_functor * m_functor
Definition: gcs_xcom_notification.h:638
~Parameterized_notification() override
Destructor for Parameterized_notification.
Definition: gcs_xcom_notification.h:216
xcom_receive_data_functor * m_functor
Definition: gcs_xcom_notification.h:372
synode_no m_config_id
Definition: gcs_xcom_notification.h:583
__u_int u_int
Definition: types.h:72
This class contains information on the configuration, i.e set of nodes or simply site definition...
Definition: gcs_xcom_group_member_information.h:390
std::uint64_t Tag
Definition: gcs_tagged_lock.h:85
Gcs_xcom_engine * m_gcs_engine
Pointer to the MySQL GCS Engine.
Definition: gcs_xcom_notification.h:277
synode_no m_message_id
Definition: gcs_xcom_notification.h:377
static void stop(mysql_harness::PluginFuncEnv *)
Definition: rest_mock_server.cc:276
Definition: gcs_xcom_notification.h:292
static Gcs_xcom_engine * gcs_engine
Definition: gcs_xcom_interface.cc:110
xcom_local_view_functor * m_functor
Definition: gcs_xcom_notification.h:578
Notification used to inform there have been change to the configuration, i.e.
Definition: gcs_xcom_notification.h:463
xcom_initialize_functor * m_functor
Definition: gcs_xcom_notification.h:320
char * m_data
Definition: gcs_xcom_notification.h:400
void() xcom_local_view_functor(synode_no, Gcs_xcom_nodes *, synode_no)
Definition: gcs_xcom_notification.h:540
Notification used to provide hints on nodes&#39; availability.
Definition: gcs_xcom_notification.h:544
Notification used to make a node join or leave the cluster, provided the system was already initializ...
Definition: gcs_xcom_notification.h:609
Definition: my_xp_mutex.h:120
void() xcom_receive_data_functor(synode_no, Gcs_xcom_nodes *, synode_no, u_int, char *)
Definition: gcs_xcom_notification.h:329
static STATUS status
Definition: mysql.cc:199
bool operator()() override
Task implemented by this notification which calls do_execute.
Definition: gcs_xcom_notification.h:224
xcom_status_functor * m_functor
Definition: gcs_xcom_notification.h:443
void() xcom_initialize_functor()
Definition: gcs_xcom_notification.h:91
Gcs_xcom_nodes * m_xcom_nodes
Definition: gcs_xcom_notification.h:519
u_int m_size
Definition: gcs_xcom_notification.h:395
This interface represents all the control functionalities that a binding implementation must provide...
Definition: gcs_control_interface.h:110
xcom_expel_functor * m_functor
Definition: gcs_xcom_notification.h:686
Gcs_control_interface * m_control_if
Definition: gcs_xcom_notification.h:644
void() xcom_protocol_change_functor(Gcs_xcom_communication_protocol_changer *, Gcs_tagged_lock::Tag const)
Definition: gcs_xcom_notification.h:696
Abstract class that defines a notification that will be sent from XCOM to MySQL GCS or from an user t...
Definition: gcs_xcom_notification.h:55
Gcs_xcom_nodes * m_xcom_nodes
Definition: gcs_xcom_notification.h:383
xcom_global_view_functor * m_functor
Definition: gcs_xcom_notification.h:502
Parameterized_notification()
Constructor for Parameterized_notification.
Definition: gcs_xcom_notification.h:210
void() xcom_control_functor(Gcs_control_interface *)
Definition: gcs_xcom_notification.h:604
Notification used to inform that has been a change in XCOM&#39;s state machine such as it has started up ...
Definition: gcs_xcom_notification.h:414
synode_no m_message_id
Definition: gcs_xcom_notification.h:513