Previous Contents Next

B   Ensemble Membership Service TCP Interface

[This is intended as an appendix to the Maestro paper (Maestro: A Group Structuring Tool For Applications With Multiple Quality of Service Requirements). It describes the exact TCP messaging interface to the group membership service described in that paper.] The description here is of the nuts-and-bolts TCP interface to the maestro membership service service described in the Ensemble tutorial. Ensemble also supports a direct interface to this service in ML. Developers using ML should probably use this interface instead. See appl/maestro/*.mli for the source code for the interface to this service.

B.1   Locating the service

The membership service uses the environment variable ENS_GROUPD_PORT to select a TCP port number to use. Client processes connect to this port in the normal fashion for TCP services. Client processes can join any number of groups over a single connection to a server, so they normally only connect once to the servers. If you run groupd on all the hosts from which your clients will be using the service, then processes can connect to the local port on their host. However, clients are not limited to using local servers, and can connect to any membership server on their system. If the TCP connection breaks, the membership service will fail the member from all groups that it joined. However, a client can reconnect to the same server and rejoin the groups it was in. If client's membership server crashes, it can reconnect to a different server.

B.2   Communicating with the service

Communication with the service is done through specially formatted messages. We describe the message types and their format here.
[messages:] Messages in both directions are formatted as follows. Both directions of the TCP streams are broken into variable-length packets. A packet has a header of size 8 of which the first 4 bytes are an unsigned integer in network byte order (NBO) giving the length of the message body (not including the header). The next 4 bytes must be zero (this is done for internal reasons, which we shall not go into here). The next message follows immediately after the body.
[integers:] Integers are unsigned and are formatted as 4 bytes in NBO.
[strings:] Strings have a somewhat more complex format. The first 4 bytes are an integer length (unsigned, NBO). The body of the string immidiately follows the length.
[endpoint and group identifiers:] These types have the same format as strings. For non-Ensemble applications, the contents can contain whatever the transport service you are using requires. Ensemble only tests the contents of endpoint and group identifiers for equality with other endpoints and groups.
[lists:] Lists have two parts. The first is an integer giving the number of elements in the list. Immediately following that are the elements in the list, one after the other and adjacent to one-another. It is assumed that the application knows the formats of the items in the list in order to break them up.



Figure 8: Client state machine diagram of the client-server membership protocol.


The actual messages sent between the client and the servers are composed of integers and strings. The first field of a message is an integer tag value from which the format of the remainder of the message can be determined.
Previous Contents Next