MySQL 8.3.0
Source Code Documentation
Gcs_control_interface Class Referenceabstract

This interface represents all the control functionalities that a binding implementation must provide. More...

#include <gcs_control_interface.h>

Inheritance diagram for Gcs_control_interface:
[legend]

Public Member Functions

virtual enum_gcs_error join ()=0
 Method that causes one to join the group that this interface pertains. More...
 
virtual enum_gcs_error leave ()=0
 Method that causes one to leave the group that this interface pertains. More...
 
virtual bool belongs_to_group ()=0
 Reports if one has joined and belongs to a group. More...
 
virtual Gcs_viewget_current_view ()=0
 Returns the currently installed view. More...
 
virtual const Gcs_member_identifier get_local_member_identifier () const =0
 Retrieves the local identifier of this member on a group. More...
 
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. More...
 
virtual void remove_event_listener (int event_listener_handle)=0
 Removes a previously registered event listener. More...
 
virtual enum_gcs_error set_xcom_cache_size (uint64_t size)=0
 Sets a new value for the maximum size of the XCom cache. More...
 
virtual ~Gcs_control_interface ()=default
 

Detailed Description

This interface represents all the control functionalities that a binding implementation must provide.

Like all interfaces in this API, it is group-oriented, meaning that a single instance shall exist per group, as it was returned by the class Gcs_interface::get_control_session.

It contains methods for:

  • View Membership;
  • Control Events;
  • Generic Data Exchange.

View Membership contain operations that will conduct one to:

  • Belong to a group: join() and leave();
  • Information about its status: belongs_to_group() and get_current_view() that shall return the active Gcs_view.

Due to the asynchronous nature of this interface, the results of join() and leave() operations, in local or remote members, shall come via an event. Those events shall be delivered in form of callbacks defined in Gcs_control_event_listener, that should be implemented by a client of this interface interested in receiving those notifications.

Regarding Generic Data Exchange, it is a functionality that was created to allow exchange of arbitrary data among members when one joins. This generic data is retrieved via the callback get_exchangeable_data() each time a View Change (VC) occurs. It states the data that one would like to offer in exchange whenever a VC happens.

What must happen under the hood is that, when one receives a VC from the underlying GCS, the binding implementation should start a round of message exchange, in which members (one or all depending of the algorithm) send the Exchangeable Data to the joining node.

That data is delivered when Gcs_control_event_listener::on_view_changed is called, which hands-out all exchanged data in one point in time.

A typical usage for that interface would be:

class my_Gcs_control_event_listener: Gcs_control_event_listener
{
void on_view_changed(const Gcs_view *new_view,
const Exchanged_data &exchanged_data)
{
// D something when view arrives...
// It will also deliver all data that nodes decided to offer at join()
// time
}
Gcs_message_data &get_exchangeable_data()
{
// Return whatever data we want to provide to a joining node
}
}
// Meanwhile in your client code...
Gcs_control_interface *gcs_control_interface_instance; // obtained
// previously
Gcs_control_event_listener *listener_instance=
new my_Gcs_control_event_listener();
int ref_handler=
gcs_control_interface_instance->add_event_listener(listener_instance);
// Normal program flow... join(), send_message(), leave()...
gcs_control_interface_instance->join();
gcs_control_interface_instance->leave();
// In the end...
gcs_control_interface_instance->remove_event_listener(ref_handler);
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 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 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.
This class serves as data container for information flowing in the GCS ecosystem.
Definition: gcs_message.h:47
This represents the membership view that a member has from a group.
Definition: gcs_view.h:54
std::vector< std::pair< Gcs_member_identifier *, Gcs_message_data * > > Exchanged_data
Alias for the Data exchanged and delivered from all nodes.
Definition: gcs_control_event_listener.h:39

Constructor & Destructor Documentation

◆ ~Gcs_control_interface()

virtual Gcs_control_interface::~Gcs_control_interface ( )
virtualdefault

Member Function Documentation

◆ add_event_listener()

virtual int Gcs_control_interface::add_event_listener ( const Gcs_control_event_listener event_listener)
pure virtual

Registers an implementation of a Gcs_control_event_listener that will receive Control Events.

See the class header for more details on implementations and usage.

Note that a binding implementation shall not offer the possibility of changing listeners while the system is up and running. In that sense, listeners must be added to it only when booting up the system.

Parameters
[in]event_listenera class that implements Gcs_control_event_listener
Returns
an handle representing the registration of this object to be used in remove_event_listener

Implemented in Gcs_xcom_control.

◆ belongs_to_group()

virtual bool Gcs_control_interface::belongs_to_group ( )
pure virtual

Reports if one has joined and belongs to a group.

Return values
trueif belonging to a group

Implemented in Gcs_xcom_control.

◆ get_current_view()

virtual Gcs_view * Gcs_control_interface::get_current_view ( )
pure virtual

Returns the currently installed view.

Return values
pointerto a Gcs_view object. If one has left a group, this shall be the last installed view. That view can be considered a best-effort view since, in some GCSs, the one that leaves might not have access to the exchanged information.
NULLif one never joined a group.

Implemented in Gcs_xcom_control.

◆ get_local_member_identifier()

virtual const Gcs_member_identifier Gcs_control_interface::get_local_member_identifier ( ) const
pure virtual

Retrieves the local identifier of this member on a group.

Return values
referenceto a valid Gcs_member_identifier instance
NULLin case of error

Implemented in Gcs_xcom_control.

◆ join()

virtual enum_gcs_error Gcs_control_interface::join ( )
pure virtual

Method that causes one to join the group that this interface pertains.

The method is non-blocking, meaning that it shall only send the request to an underlying GCS. The final result shall come via a View Change event delivered through Gcs_control_event_listener.

Return values
GCS_OKin case of everything goes well. Any other value of gcs_error in case of error.

Implemented in Gcs_xcom_control.

◆ leave()

virtual enum_gcs_error Gcs_control_interface::leave ( )
pure virtual

Method that causes one to leave the group that this interface pertains.

The method is non-blocking, meaning that it shall only send the request to an underlying GCS. The final result shall come via a View Change event delivered through Gcs_control_event_listener.

Return values
GCS_OKin case of everything goes well. Any other value of gcs_error in case of error

Implemented in Gcs_xcom_control.

◆ remove_event_listener()

virtual void Gcs_control_interface::remove_event_listener ( int  event_listener_handle)
pure virtual

Removes a previously registered event listener.

Note that a binding implementation shall not offer the possibility of changing listeners while the system is up and running. In that sense listeners must be removed from it only when shutting down the system.

Parameters
[in]event_listener_handlethe handle returned when the listener was registered

Implemented in Gcs_xcom_control.

◆ set_xcom_cache_size()

virtual enum_gcs_error Gcs_control_interface::set_xcom_cache_size ( uint64_t  size)
pure virtual

Sets a new value for the maximum size of the XCom cache.

Parameters
[in]sizethe new maximum size of the XCom cache
Return values
-GCS_OK if request was successfully scheduled in XCom, GCS_NOK otherwise.

Implemented in Gcs_xcom_control.


The documentation for this class was generated from the following file: