Group Management Interface Documentation - FREEDM-DGI/FREEDM GitHub Wiki

Group Management is an autonomous implementation of Garcia-Molina's Leader Election algorithm. Right now, there is nothing to be influenced or changed via API, although that make change in the future. However, it is possible to query Group Management for the current peer list.

Making the query

Requests for the current peer list are done via the gm.PeerListQuery message. This message has only one internal submessage: gm.requester which should be set to the module who is requesting the current peer list. To facilitate this, the GMAgent class provides a static method, GMAgent::PeerListQuery which generates a query message. It has only one argument, requester, which is a string identifying the module to send the response to.

This query message can be sent to any node, even those outside the current group. All responses will include the node's coordinator and all nodes it is aware of in its group.

Note that most modules don't need to make this call, the peer list is pushed to all modules whenever there is a change in group membership.

Response

The response is a xxx.PeerList message. If the message was sent as part of an automatic push by the group management module xxx will be the value any, a special message type that is delivered to all modules. If the peer list was solicited using a PeerListQuery message, then then xxx will be the value of requester.

The PeerList message will always contain the following keys:

  • any.source The UUID of the peer who sent the message
  • any.coordinator The UUID of this node's coordinator.
  • any.peers A key which contains one or more peer sub-keys. Each peer sub-key contains sub-sub-keys host,port, and uuid which are sufficient to build a connection to the peer if it is not already available in your GlobalPeerList.

It is recommended that you parse this response using the GMAgent::ProcessPeerList function, which is a static member of GMAgent. This function takes two parameters: the peerlist message, and a connection manager instance. The connection manager is required to able to add nodes that this system is not aware of into its global peer list. (See a note about that below) This function will return a GMAgent::PeerSet which is a typedef for a map keyed on uuid to a PeerNodePtr a container which can be used to send messages, among other things.

Notes

If you wish to retrieve all available nodes in the system, the CGlobalPeerList class is provided as a singleton. Any function or class can read its list by invoking the methods it provides. However, its store is read only to all modules except by GroupManagement. Therefore, if you are attempting to send messages to the peers provided as a response from your query, it is strongly recommended you use the ProcessPeerList method, since it will guarantee all peers from the peer list will be constructed in the connection manager. If this is not done, it is not guaranteed that the node will be available to send messages to and attempting to add it to the ConnectionManager directly can produce inconsistent results!