MySQL  8.0.23
Source Code Documentation
Gcs_communication_interface Class Referenceabstract

#include <gcs_communication_interface.h>

Inheritance diagram for Gcs_communication_interface:
Gcs_xcom_communication_interface Gcs_xcom_communication

Public Member Functions

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. More...
 
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 Events. More...
 
virtual void remove_event_listener (int event_listener_handle)=0
 Removes a previously registered event listener. More...
 
virtual Gcs_protocol_version get_protocol_version () const =0
 Retrieves the current GCS protocol version in use. More...
 
virtual std::pair< bool, std::future< void > > set_protocol_version (Gcs_protocol_version new_version)=0
 Modifies the GCS protocol version in use. More...
 
virtual Gcs_protocol_version get_maximum_supported_protocol_version () const =0
 Get the maximum protocol version currently supported by the group. More...
 
virtual ~Gcs_communication_interface ()
 

Detailed Description

This interface represents all the communication facilities that a binding implementation should 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_communication_session.

It has two major subsections:

  • Message sending: represented by the method send_message, it will broadcast a message to the group in which this interface is bound. All message data is encapsulated in the Gcs_message object that contains more detail about the information to be sent. Guarantees are bound to the binding implementation. This means that the implementation shall send message of this message and shall not be maintained between different groups.
  • Message receiving: Due to the asynchronous nature of this interface, message reception is done via an event. They shall be delivered in form of callbacks defined in Gcs_communication_event_listener class, that should be implemented by a client of this interface interested in receiving those notifications.

A typical usage for this interface would be:

class my_Gcs_communication_event_listener: Gcs_communication_event_listener
{
void on_message_received(const Gcs_message &message)
{
//Do something when message arrives...
}
}
//meanwhile in your client code...
Gcs_communication_interface *gcs_comm_interface_instance; // obtained
// previously
int ref_handler=
gcs_comm_interface_instance->add_event_listener(listener_instance);
Gcs_message *msg= new Gcs_message(<message_params>);
gcs_comm_interface_instance->send_message(msg);
//Normal program flow...
//In the end...
gcs_comm_interface_instance->remove_event_listener(ref_handler);

Constructor & Destructor Documentation

◆ ~Gcs_communication_interface()

virtual Gcs_communication_interface::~Gcs_communication_interface ( )
inlinevirtual

Member Function Documentation

◆ add_event_listener()

virtual int Gcs_communication_interface::add_event_listener ( const Gcs_communication_event_listener event_listener)
pure virtual

Registers an implementation of a Gcs_communication_event_listener that will receive Communication Events.

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_communication_event_listener
Returns
an handle representing the registration of this object to be used in remove_event_listener

Implemented in Gcs_xcom_communication.

◆ get_maximum_supported_protocol_version()

virtual Gcs_protocol_version Gcs_communication_interface::get_maximum_supported_protocol_version ( ) const
pure virtual

Get the maximum protocol version currently supported by the group.

Returns
the maximum protocol version currently supported by the group

Implemented in Gcs_xcom_communication.

◆ get_protocol_version()

virtual Gcs_protocol_version Gcs_communication_interface::get_protocol_version ( ) const
pure virtual

Retrieves the current GCS protocol version in use.

Implemented in Gcs_xcom_communication.

◆ remove_event_listener()

virtual void Gcs_communication_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_communication.

◆ send_message()

virtual enum_gcs_error Gcs_communication_interface::send_message ( const Gcs_message message_to_send)
pure virtual

Method used to broadcast a message to a group in which this interface pertains.

Note that one must belong to an active group to send messages.

Parameters
[in]message_to_sendthe Gcs_message object to send
Returns
A gcs_error value
Return values
GCS_OKWhen message is transmitted successfully
GCS_ERRORWhen error occurred while transmitting message
GCS_MESSAGE_TOO_BIGWhen message is bigger than the GCS can handle

Implemented in Gcs_xcom_communication.

◆ set_protocol_version()

virtual std::pair<bool, std::future<void> > Gcs_communication_interface::set_protocol_version ( Gcs_protocol_version  new_version)
pure virtual

Modifies the GCS protocol version in use.

The method is non-blocking. It returns a future on which the caller can wait for the action to finish.

This method has the following requirements:

  • It must be called by all group members at the same logical instant, i.e. it is part of the replicated state machine.
  • It must not be called concurrently, i.e. a new protocol change may only begin after the previous one has finished.

A GCS client must ensure the requirements are met. In the case of Group Replication, these requirements are ensured by initiating a GCS protocol change as part of a GR group action.

Parameters
new_versionThe desired GCS protocol version
Return values
{true,future}If successful
{false,_}If unsuccessful because new_version is unsupported

Implemented in Gcs_xcom_communication.


The documentation for this class was generated from the following file:
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
Definition: gcs_communication_interface.h:87
Gcs_message
Definition: gcs_message.h:338
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
Definition: gcs_communication_event_listener.h:35
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.