MySQL  8.0.19
Source Code Documentation
gcs_communication_interface.h
Go to the documentation of this file.
1 /* Copyright (c) 2014, 2018, 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_COMMUNICATION_INTERFACE_INCLUDED
24 #define GCS_COMMUNICATION_INTERFACE_INCLUDED
25 
26 #include <future>
27 #include <utility> // std::pair
31 
32 /**
33  @class Gcs_communication_interface
34 
35  This interface represents all the communication facilities that a binding
36  implementation should provide. Like all interfaces in this API, it is
37  group-oriented, meaning that a single instance shall exist per group,
38  as it was returned by the class Gcs_interface::get_communication_session.
39 
40  It has two major subsections:
41  - Message sending: represented by the method send_message, it will
42  broadcast a message to the group in which this interface is bound.
43  All message data is encapsulated in the Gcs_message object that
44  contains more detail about the information to be sent.
45  Guarantees are bound to the binding implementation. This means that the
46  implementation shall send message of this message and shall not be
47  maintained between different groups.
48 
49  - Message receiving: Due to the asynchronous nature of this interface,
50  message reception is done via an event. They shall be delivered in
51  form of callbacks defined in Gcs_communication_event_listener class,
52  that should be implemented by a client of this interface interested
53  in receiving those notifications.
54 
55  A typical usage for this interface would be:
56 
57  @code{.cpp}
58  class my_Gcs_communication_event_listener: Gcs_communication_event_listener
59  {
60  void on_message_received(const Gcs_message &message)
61  {
62  //Do something when message arrives...
63  }
64  }
65 
66  //meanwhile in your client code...
67  Gcs_communication_interface *gcs_comm_interface_instance; // obtained
68  // previously
69 
70  Gcs_communication_event_listener listener_instance;
71 
72  int ref_handler=
73  gcs_comm_interface_instance->add_event_listener(listener_instance);
74 
75  Gcs_message *msg= new Gcs_message(<message_params>);
76 
77  gcs_comm_interface_instance->send_message(msg);
78 
79  //Normal program flow...
80 
81  //In the end...
82  gcs_comm_interface_instance->remove_event_listener(ref_handler);
83 
84  @endcode
85 
86 */
88  public:
89  /**
90  Method used to broadcast a message to a group in which this interface
91  pertains.
92 
93  Note that one must belong to an active group to send messages.
94 
95  @param[in] message_to_send the Gcs_message object to send
96  @return A gcs_error value
97  @retval GCS_OK When message is transmitted successfully
98  @retval GCS_ERROR When error occurred while transmitting message
99  @retval GCS_MESSAGE_TOO_BIG When message is bigger than
100  the GCS can handle
101  */
102 
103  virtual enum_gcs_error send_message(const Gcs_message &message_to_send) = 0;
104 
105  /**
106  Registers an implementation of a Gcs_communication_event_listener that will
107  receive Communication Events.
108 
109  Note that a binding implementation shall not offer the possibility of
110  changing listeners while the system is up and running. In that sense,
111  listeners must be added to it only when booting up the system.
112 
113  @param[in] event_listener a class that implements
114  Gcs_communication_event_listener
115  @return an handle representing the registration of this object to
116  be used in remove_event_listener
117  */
118 
119  virtual int add_event_listener(
120  const Gcs_communication_event_listener &event_listener) = 0;
121 
122  /**
123  Removes a previously registered event listener.
124 
125  Note that a binding implementation shall not offer the possibility of
126  changing listeners while the system is up and running. In that sense
127  listeners must be removed from it only when shutting down the system.
128 
129  @param[in] event_listener_handle the handle returned when the listener was
130  registered
131  */
132 
133  virtual void remove_event_listener(int event_listener_handle) = 0;
134 
135  /**
136  Retrieves the current GCS protocol version in use.
137  */
138  virtual Gcs_protocol_version get_protocol_version() const = 0;
139 
140  /**
141  * Modifies the GCS protocol version in use.
142  *
143  * The method is non-blocking. It returns a future on which the caller can
144  * wait for the action to finish.
145  *
146  * This method has the following requirements:
147  * - It must be called by all group members at the same logical instant, i.e.
148  * it is part of the replicated state machine.
149  * - It must not be called concurrently, i.e. a new protocol change may only
150  * begin after the previous one has finished.
151  *
152  * A GCS client must ensure the requirements are met.
153  * In the case of Group Replication, these requirements are ensured by
154  * initiating a GCS protocol change as part of a GR group action.
155  *
156  * @param new_version The desired GCS protocol version
157  *
158  * @retval {true, future} If successful
159  * @retval {false, _} If unsuccessful because @c new_version is unsupported
160  */
161  virtual std::pair<bool, std::future<void>> set_protocol_version(
162  Gcs_protocol_version new_version) = 0;
163 
164  /**
165  * Get the maximum protocol version currently supported by the group.
166  *
167  * @returns the maximum protocol version currently supported by the group
168  */
170  const = 0;
171 
173 };
174 
175 #endif // GCS_COMMUNICATION_INTERFACE_H
Gcs_communication_interface::add_event_listener
virtual int add_event_listener(const Gcs_communication_event_listener &event_listener)=0
Registers an implementation of a Gcs_communication_event_listener that will receive Communication Eve...
Gcs_communication_interface::set_protocol_version
virtual std::pair< bool, std::future< void > > set_protocol_version(Gcs_protocol_version new_version)=0
Modifies the GCS protocol version in use.
Gcs_communication_interface
Definition: gcs_communication_interface.h:87
gcs_message.h
Gcs_message
Definition: gcs_message.h:338
Gcs_protocol_version
Gcs_protocol_version
The GCS protocol versions.
Definition: gcs_types.h:127
Gcs_communication_interface::remove_event_listener
virtual void remove_event_listener(int event_listener_handle)=0
Removes a previously registered event listener.
gcs_communication_event_listener.h
Gcs_communication_event_listener
Definition: gcs_communication_event_listener.h:35
Gcs_communication_interface::get_protocol_version
virtual Gcs_protocol_version get_protocol_version() const =0
Retrieves the current GCS protocol version in use.
gcs_types.h
Gcs_communication_interface::get_maximum_supported_protocol_version
virtual Gcs_protocol_version get_maximum_supported_protocol_version() const =0
Get the maximum protocol version currently supported by the group.
Gcs_communication_interface::~Gcs_communication_interface
virtual ~Gcs_communication_interface()
Definition: gcs_communication_interface.h:172
Gcs_communication_interface::send_message
virtual enum_gcs_error send_message(const Gcs_message &message_to_send)=0
Method used to broadcast a message to a group in which this interface pertains.
enum_gcs_error
enum_gcs_error
Definition: gcs_types.h:40