Gcs_control_interface Class Reference

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:

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_view *	get_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);

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_listener

a 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

true	if 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

pointer	to 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.
NULL	if 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

reference	to a valid Gcs_member_identifier instance
NULL	in 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_OK

in 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_OK

in 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_handle

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

size

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

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