MySQL  8.0.19
Source Code Documentation
gcs_control_interface.h
Go to the documentation of this file.
1 /* Copyright (c) 2014, 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_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 - a valid 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 
159  virtual Gcs_view *get_current_view() = 0;
160 
161  /**
162  Retrieves the local identifier of this member on a group.
163 
164  @retval - a reference to a valid Gcs_member_identifier instance
165  @retval - NULL in case of error
166  */
167 
168  virtual const Gcs_member_identifier get_local_member_identifier() const = 0;
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 
184  virtual int add_event_listener(
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 
210 };
211 
212 #endif // GCS_CONTROL_INTERFACE_INCLUDED
gcs_view.h
Gcs_control_interface::leave
virtual enum_gcs_error leave()=0
Method that causes one to leave the group that this interface pertains.
Gcs_control_interface::set_xcom_cache_size
virtual enum_gcs_error set_xcom_cache_size(uint64_t size)=0
Sets a new value for the maximum size of the XCom cache.
Gcs_control_interface::add_event_listener
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.
Gcs_control_interface::belongs_to_group
virtual bool belongs_to_group()=0
Reports if one has joined and belongs to a group.
Gcs_member_identifier
Definition: gcs_member_identifier.h:39
Gcs_control_interface::get_current_view
virtual Gcs_view * get_current_view()=0
Returns the currently installed view.
gcs_control_event_listener.h
Gcs_control_interface
Definition: gcs_control_interface.h:110
Gcs_control_interface::get_local_member_identifier
virtual const Gcs_member_identifier get_local_member_identifier() const =0
Retrieves the local identifier of this member on a group.
Gcs_view
Definition: gcs_view.h:54
Gcs_control_interface::remove_event_listener
virtual void remove_event_listener(int event_listener_handle)=0
Removes a previously registered event listener.
Gcs_control_interface::join
virtual enum_gcs_error join()=0
Method that causes one to join the group that this interface pertains.
gcs_member_identifier.h
Gcs_control_interface::~Gcs_control_interface
virtual ~Gcs_control_interface()
Definition: gcs_control_interface.h:209
enum_gcs_error
enum_gcs_error
Definition: gcs_types.h:40
Gcs_control_event_listener
Definition: gcs_control_event_listener.h:51