Gcs_communication_interface Class Reference

This interface represents all the communication facilities that a binding implementation should provide. More...

#include <gcs_communication_interface.h>

Inheritance diagram for Gcs_communication_interface:

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 void	set_communication_protocol (enum_transport_protocol protocol)=0
	Sets the communication protocol to use. More...
virtual enum_transport_protocol	get_incoming_connections_protocol ()=0
	Get the incoming connections protocol which is currently active. More...
virtual	~Gcs_communication_interface ()=default

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
 
Gcs_communication_event_listener listener_instance;
 
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 ( )

virtualdefault

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_listener

a 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_incoming_connections_protocol()

virtual enum_transport_protocol Gcs_communication_interface::get_incoming_connections_protocol ( )

pure virtual

Get the incoming connections protocol which is currently active.

Returns

GcsRunningProtocol

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_handle

the 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_send

the Gcs_message object to send

Returns

A gcs_error value

Return values

GCS_OK	When message is transmitted successfully
GCS_ERROR	When error occurred while transmitting message
GCS_MESSAGE_TOO_BIG	When message is bigger than the GCS can handle

Implemented in Gcs_xcom_communication.

set_communication_protocol()

virtual void Gcs_communication_interface::set_communication_protocol ( enum_transport_protocol  protocol )

pure virtual

Sets the communication protocol to use.

Parameters

protocol

the protocol to use

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_version

The 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:

• plugin/group_replication/libmysqlgcs/include/mysql/gcs/gcs_communication_interface.h