WL#7732: GCS Replication: GCS API

GOAL
----

This WL aims to improve the existing GCS API binding facility, towards a future 
MyGCS implementation.

References
-----------
WL#6829

1. Introduction
-------------------

In the first phase of the project, it was decided that one would need
an API for decoupling Group Communication Systems(GCS)
implementations from the plugin code, in order to ease
their interchangeability to the one that would suit better the project
goals. This was accomplished in WL#6829 and derivatives.

In this WL, one will design the second installment of this API towards
the future and having in mind an implementation of a MyGCS.

It will also comprise the implementation of the its first instance: a
bridge from the Corosync API.

2. Interface
------------------

A proposal for the interface can be found attached to this WL. Its
detailed description can be seen at the LLD section.

The principles guiding this interface were the ones of Lean and
simplicity, meaning that this is the minimum possible interface that
will serve the needs of the near future.

A remark that must be made that will help to interpret this design,
is the fact that this interface will allow the connection to multiple
groups from the same node, which was not allowed in the previous
version.

3. Binding implementation
---------------------------

The first installment of this model will be the implementation of the
Corosync binding.

Regarding the current implementation, one will reuse all the logic and
lessons learned involved in being a Corosync client. One shall also
reuse the State Exchange algorithm, after being isolated from the
current code. That will be accomplished in the scope of this task.

1. Introduction
-------------------

This section will describe the two major blocks of this implementation:
- Interface model description
- Binding implementation, emphasizing on the differences to this new
implementation.

2. Interface model
-------------------

The interface comprises two major areas: Interfaces and Data Transfer
Objects. They will be described in the following sections.

2.1 Data Transfer Objects
--------------------------

2.1.1 View/View Identifier
--------------------------
Represents the membership of a group in a certain moment in time. It
contains the reference to the group it belongs and it is identified
by a View Identifier.

This View Identifier is encapsulated in a class and it has a single
strong property which is: while the group exists and has members,
consecutive View Identifiers of consecutive Views must be increased
monotonically.

It also contains:
- The list of members
- The members that left form the last view
- The members that joined from the last view

2.1.1 Member Identifier
--------------------------

It identifies a member within a group. It is not forced by the model
to be an uuid, but it is advisable.

2.1.1 Group Identifier
--------------------------

It uniquely identifies a Group.

2.1.1 Message
--------------------------

Holder of the data to be exchanged within a group. Its fields comprise:
- An header and a payload: Everyone is free to read and write from
those fields
- An origin: Member that sent the message
- A destination: Group to which the message was sent

2.2 Interfaces
--------------------------

Any binding must implement a series of interfaces that will
provide control, communication and statistics to a client. 

2.2.1 GCS Interface
--------------------------

Umbrella interface with group oriented methods that will return any
of the interface implementations provided by a binding:
- Control interface
- Communication interface
- Statistics interface

This interface must be implemented by any binding provider. One could
think of an abstract implementation, but that could reveal itself as a
restrictive solution, since some versions might choose to provide
Singleton group interfaces and others might create objects every time
a method is called.

A factory might be provided to return available instances of the
available bindings.

2.2.2 GCS Control Interface
-----------------------------

The purpose of this interface is to provide all methods that
will control the communication channel. It is comprised of two major
sections:
- The methods upon one can make requests
- Callback interfaces that should be implemented by clients

On the request section of the interface, one should focus our attention
in the process of joining a group. First of all, it is not mandatory
to provide a callback when you join. It is your responsibility to set
a callback if one wants to receive the information returned
asynchronously by the GCS, such as View Changes. The callback to set
should be an instance of gcs_control_event_listener.

Another noticeable change is the fact that one can add information
to be exchanged between group members at joining time. This is done
using the method set_exchangeable_data and can be received by all
other members when they register a callback of type
gcs_control_data_exchange_event_listener

2.2.3 GCS Communication Interface
-----------------------------------

The purpose of this interface is to allow data to flow within a group.
It contains a single action method which is send_message.

To listen to messages coming from the group, one must register a
callback which is an instance of gcs_communication_event_listener.

2.2.4 GCS Statistics Interface
----------------------------------- 

The purpose of this interface is to provide typical statistics about
data flowing within a group.

3. Corosync Binding
---------------------

The first installment of this interface will be an implemented
over the Corosync GCS. Since an it already exists in the previous
version, one will take all the logic and knowledge from it with some
improvements.

Two of the two major improvements will be:
- Multi group usage, as such, Corosync callback implementation must
be able to direct to the correct interface all incoming messages and
view changes
- Instance methods used as callbacks instead of a static C-style method.
This can be achieved using a classical "extern C" directive approach,
in which that method is provided to Corosync but it is implemented as
a proxy to a C++ object.

Regarding the State Exchange algorithm designed and implemented in
WL#7332, it is not the goal of this WL to rewrite, but at least two
tasks must be accomplished:
- It must be isolated from the rest of the code in a class of its own
in order to be reused in this context.
- All data that does not pertain to view identification must be pushed
to the client via the new gcs_control_data_exchange_event_listener
interface in a first phase.

4. Testing
--------------

MTR has proven as a very useful testing tool in the context of MySQL
development process but, in the first phase of development of the GCS
project, the granularity of MTR is too high for testing and debugging
a GCS binding.

The recommendation for this WL is that one tests this using MySQL's
unit test platform: GTest, thus reducing development and debug time
and serving as an example within the GCS project.

One shall also use MTR with a dual purpose: System test, to see if
the integration of all components work, and as Regression test.