MySQL 8.3.0
Source Code Documentation
gcs_control_interface.h
Go to the documentation of this file.
1/* Copyright (c) 2014, 2023, 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_CONTROL_INTERFACE_INCLUDED
24#define GCS_CONTROL_INTERFACE_INCLUDED
25
26#include <vector>
27
31
32/**
33 @class Gcs_control_interface
34
35 This interface represents all the control functionalities that a binding
36 implementation must 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_control_session.
39
40 It contains methods for:
41 - View Membership;
42 - Control Events;
43 - Generic Data Exchange.
44
45 View Membership contain operations that will conduct one to:
46 - Belong to a group: join() and leave();
47 - Information about its status: belongs_to_group() and
48 get_current_view() that shall return the active Gcs_view.
49
50 Due to the asynchronous nature of this interface, the results of
51 join() and leave() operations, in local or remote members, shall come
52 via an event. Those events shall be delivered in form of callbacks
53 defined in Gcs_control_event_listener, that should be implemented by a
54 client of this interface interested in receiving those notifications.
55
56 Regarding Generic Data Exchange, it is a functionality that was created
57 to allow exchange of arbitrary data among members when one joins.
58 This generic data is retrieved via the callback get_exchangeable_data() each
59 time a View Change (VC) occurs. It states the data that one would like to
60 offer in exchange whenever a VC happens.
61
62 What must happen under the hood is that, when one receives a VC from
63 the underlying GCS, the binding implementation should start a round
64 of message exchange, in which members (one or all depending of the algorithm)
65 send the Exchangeable Data to the joining node.
66
67 That data is delivered when Gcs_control_event_listener::on_view_changed is
68 called, which hands-out all exchanged data in one point in time.
69
70 A typical usage for that interface would be:
71
72 @code{.cpp}
73 class my_Gcs_control_event_listener: Gcs_control_event_listener
74 {
75 void on_view_changed(const Gcs_view *new_view,
76 const Exchanged_data &exchanged_data)
77 {
78 // D something when view arrives...
79 // It will also deliver all data that nodes decided to offer at join()
80 // time
81 }
82
83 Gcs_message_data &get_exchangeable_data()
84 {
85 // Return whatever data we want to provide to a joining node
86 }
87 }
88
89 // Meanwhile in your client code...
90 Gcs_control_interface *gcs_control_interface_instance; // obtained
91 // previously
92
93 Gcs_control_event_listener *listener_instance=
94 new my_Gcs_control_event_listener();
95
96 int ref_handler=
97 gcs_control_interface_instance->add_event_listener(listener_instance);
98
99 // Normal program flow... join(), send_message(), leave()...
100
101 gcs_control_interface_instance->join();
102
103 gcs_control_interface_instance->leave();
104
105 // In the end...
106 gcs_control_interface_instance->remove_event_listener(ref_handler);
107
108 @endcode
109*/
111 public:
112 /**
113 Method that causes one to join the group that this
114 interface pertains.
115
116 The method is non-blocking, meaning that it shall only send the
117 request to an underlying GCS. The final result shall come via a
118 View Change event delivered through Gcs_control_event_listener.
119
120 @retval GCS_OK in case of everything goes well. Any other value of
121 gcs_error in case of error.
122 */
123
124 virtual enum_gcs_error join() = 0;
125
126 /**
127 Method that causes one to leave the group that this
128 interface pertains.
129
130 The method is non-blocking, meaning that it shall only send the
131 request to an underlying GCS. The final result shall come via a
132 View Change event delivered through Gcs_control_event_listener.
133
134 @retval GCS_OK in case of everything goes well. Any other value of
135 gcs_error in case of error
136 */
137
138 virtual enum_gcs_error leave() = 0;
139
140 /**
141 Reports if one has joined and belongs to a group.
142
143 @retval true if belonging to a group
144 */
145
146 virtual bool belongs_to_group() = 0;
147
148 /**
149 Returns the currently installed view.
150
151 @retval pointer to a Gcs_view object.
152 If one has left a group, this shall be the last
153 installed view. That view can be considered a best-effort
154 view since, in some GCSs, the one that leaves might not
155 have access to the exchanged information.
156 @retval NULL if one never joined a group.
157 */
158
160
161 /**
162 Retrieves the local identifier of this member on a group.
163
164 @retval reference to a valid Gcs_member_identifier instance
165 @retval NULL in case of error
166 */
167
169
170 /**
171 Registers an implementation of a Gcs_control_event_listener that will
172 receive Control Events. See the class header for more details on
173 implementations and usage.
174
175 Note that a binding implementation shall not offer the possibility of
176 changing listeners while the system is up and running. In that sense,
177 listeners must be added to it only when booting up the system.
178
179 @param[in] event_listener a class that implements Gcs_control_event_listener
180 @return an handle representing the registration of this object to
181 be used in remove_event_listener
182 */
183
185 const Gcs_control_event_listener &event_listener) = 0;
186
187 /**
188 Removes a previously registered event listener.
189
190 Note that a binding implementation shall not offer the possibility of
191 changing listeners while the system is up and running. In that sense
192 listeners must be removed from it only when shutting down the system.
193
194 @param[in] event_listener_handle the handle returned when the listener was
195 registered
196 */
197
198 virtual void remove_event_listener(int event_listener_handle) = 0;
199
200 /**
201 Sets a new value for the maximum size of the XCom cache.
202
203 @param[in] size the new maximum size of the XCom cache
204 @retval - GCS_OK if request was successfully scheduled in XCom,
205 GCS_NOK otherwise.
206 */
207 virtual enum_gcs_error set_xcom_cache_size(uint64_t size) = 0;
208
209 virtual ~Gcs_control_interface() = default;
210};
211
212#endif // GCS_CONTROL_INTERFACE_INCLUDED
This interface is implemented by those who wish to receive Control Interface notifications.
Definition: gcs_control_event_listener.h:51
This interface represents all the control functionalities that a binding implementation must provide.
Definition: gcs_control_interface.h:110
virtual enum_gcs_error leave()=0
Method that causes one to leave the group that this interface pertains.
virtual ~Gcs_control_interface()=default
virtual Gcs_view * get_current_view()=0
Returns the currently installed view.
virtual int add_event_listener(const Gcs_control_event_listener &event_listener)=0
Registers an implementation of a Gcs_control_event_listener that will receive Control Events.
virtual bool belongs_to_group()=0
Reports if one has joined and belongs to a group.
virtual const Gcs_member_identifier get_local_member_identifier() const =0
Retrieves the local identifier of this member on a group.
virtual void remove_event_listener(int event_listener_handle)=0
Removes a previously registered event listener.
virtual enum_gcs_error join()=0
Method that causes one to join the group that this interface pertains.
virtual enum_gcs_error set_xcom_cache_size(uint64_t size)=0
Sets a new value for the maximum size of the XCom cache.
It represents the identity of a group member within a certain group.
Definition: gcs_member_identifier.h:39
This represents the membership view that a member has from a group.
Definition: gcs_view.h:54
enum_gcs_error
This enumeration describes errors which can occur during group communication operations.
Definition: gcs_types.h:40