Publish-Subscribe and GMD

RTserver and RTclient can take full advantage of the GMD of connections. In addition to the connection GMD capabilities, both RTclient and RTserver have several additional features related to GMD.

Delivery can be guaranteed to all subscribing RTclients or to at least one subscribing RTclient.

RTserver manages the gathering of acknowledgments from the necessary subscribers and sends a single acknowledgment back to the publisher.

RTclient automatically resends unacknowledged GMD messages when it connects or reconnects to RTserver.

RTserver can maintain warm RTclient information to prevent GMD messages from being lost if an RTclient crashes and restarts.

RTserver keeps GMD messages in memory so it can easily resend them without having to notify or wait for the original sending RTclient.

RTclient can query RTserver for the delivery status of a message sent with GMD.

Message is sent to RTserver.

Message is sent to Receiver.

After processing message, highest sequence number is updated in the receiver’s GMD area.

Acknowledgment message is sent to RTserver.

Acknowledgment message is sent to Sender.

Message is deleted from GMD area.

Working with GMD in RTserver and RTclient is very similar to working with GMD in peer-to-peer connections, and thus no complete source code example is shown. The source code files rtclgmds.c and rtclgmdr.c illustrate the most probable GMD failures and are located in these directories:

Delivery Mode in Publish-Subscribe Model

As discussed in Delivery Mode, in peer-to-peer connections the GMD delivery modes T_IPC_DELIVERY_SOME and T_IPC_DELIVERY_ALL are the same because there is only one receiving process. With the RTserver and RTclient GMD, T_IPC_DELIVERY_SOME is a subset of T_IPC_DELIVERY_ALL. With T_IPC_DELIVERY_ALL, delivery is not considered successful until all subscribing RTclients acknowledge delivery. With T_IPC_DELIVERY_SOME, delivery is considered successful as soon as at least one subscriber acknowledges delivery. This is useful for programs where it is acceptable to continue after at least one subscriber, such as an operator console, receives notification of an event.

Warm RTclient in RTserver

A warm RTclient in RTserver is somewhat analogous to a warm connection to RTserver in RTclient, although there are many differences. As described in Warm Connection to RTserver, a warm connection to RTserver is a subset of a full connection that allows messages, including messages sent without GMD, to be buffered for later sending.

A warm RTclient in RTserver, however, is used only for GMD. With a warm RTclient, the only thing RTserver remembers is the name of the RTclient and the GMD-using subjects to which the RTclient was subscribing when that RTclient disconnected. RTserver then tracks the GMD messages that this warm RTclient should receive and acknowledge (see How GMD Works in RTserver for a full discussion of how RTserver operates for GMD). RTserver does not buffer any non-GMD messages for the RTclient (those with a delivery mode of T_IPC_DELIVERY_BEST_EFFORT or T_IPC_DELIVERY_ORDERED).

RTclient informs RTserver to keep warm RTclient information for itself by setting the Server_Disconnect_Mode option to warm before calling either TipcSrvCreate or TipcSrvDestroy (both of these functions send the value of Server_Disconnect_Mode to RTserver). In this warm mode, if an RTclient disconnects for any reason, such as crashes or simply calls TipcSrvDestroy, all necessary RTservers (those with direct GMD publishing RTclients) keep warm RTclient information.

The warm RTclient is not considered to be associated with any RTserver, and it can later reconnect to any RTserver in the same multiple RTserver group. Until the warm RTclient reconnects or the timeout specified in the RTserver option Client_Reconnect_Timeout is reached, each RTserver continues to buffer GMD messages sent by its own direct RTclients that have a destination subject being subscribed to by the warm RTclient. If the warm RTclient reconnects in time, then all RTservers resend the proper GMD messages to the reconnected RTclient in the proper order. RTclient can even switch from one RTserver to another, and the RTserver takes care of all the necessary rerouting for GMD.

Note that no warm RTserver-to-RTserver information is needed for GMD. An RTserver does route the messages for GMD, but it is the subjects to which the RTclient is subscribing that are really important. Therefore, warm RTclient information is needed in RTserver for GMD, but not warm RTserver information.

GMD Message Types

There are six message types used to implement GMD in connections, RTservers, and RTclients. GMD_ACK and GMD_FAILURE are used in all GMD, while the other four are used only by an RTserver and RTclient. This section describes how these message types are used in RTclient/RTserver GMD.

GMD_ACK

GMD_ACK messages are used by RTclient and RTserver much as they are by peer-to-peer connections. When an RTclient publishes a message with GMD, the subscribing RTclients all send a GMD_ACK message to acknowledge delivery. The original publishing RTclient does not get these acknowledgments, however. RTserver manages the gathering of acknowledgments from the necessary subscribers and sends a single acknowledgment back to the original publisher. This greatly simplifies GMD for the publishing RTclient.

GMD_DELETE

The function TipcSrvGmdMsgServerDelete sends a GMD_DELETE message to RTserver to inform RTserver to terminate GMD for a specific message, which allows RTserver to reclaim the memory for the message. TipcSrvGmdMsgServerDelete is usually only used from a connection process callback for a GMD_FAILURE message, but it can be called at any time by advanced programs that wish to poll for GMD status.

GMD_FAILURE

GMD_FAILURE messages are used to notify RTclient of asynchronous GMD failures much as they are for peer-to-peer connections. In addition to the T_ERR_GMD_SENDER_TIMEOUT error code described in Delivery Timeout Failures, RTclients should be prepared to handle these additional error codes:

Table 14 GMD Failure Error Numbers
Error Number	Description
T_ERR_GMD_RECEIVER_TIMEOUT	A receiving RTclient (whose Server_Disconnect_Mode option is set to `warm`) disconnects before acknowledging the message and does not reconnect to RTserver in time.
T_ERR_GMD_RECEIVER_EXIT	A receiving RTclient (whose Server_Disconnect_Mode option is set to `gmd_failure`) disconnects before acknowledging the message.
T_ERR_GMD_NO_RECEIVERS	No RTclients are subscribing to the destination subject of the message, and the option Zero_Recv_Gmd_Failure in RTserver is set to `TRUE.`

GMD_NACK

GMD_NACK messages are sent from RTserver to RTclient, indicating that a GMD failure occurred. RTclient automatically builds a GMD_FAILURE message from the information in the GMD_NACK message and processes the GMD_FAILURE message. RTclients should not try to process GMD_NACK messages and should only manipulate callbacks for GMD_FAILURE messages. The GMD_NACK message type is documented for completeness and to illustrate how GMD operates.

GMD_STATUS_CALL

The function TipcSrvGmdMsgStatus sends a GMD_STATUS_CALL message to RTserver to poll RTserver for the current GMD status of a specific message. If RTserver is aware of the message, it sends back a GMD_STATUS_RESULT message with the requested information. TipcSrvGmdMsgStatus is intended to be used from a connection process callback for a GMD_FAILURE message.

GMD_STATUS_RESULT

GMD_STATUS_RESULT messages are sent from RTserver to RTclient as the result of a query with TipcSrvGmdMsgStatus. Each GMD_STATUS_RESULT message contains these four fields:

an INT4 integer field containing the sequence number property of the message

a STR_ARRAY string array field containing the names of the RTclients that have acknowledged successful delivery of the message

a STR_ARRAY string array field containing the names of the RTclients where GMD failed for the message

a STR_ARRAY string array field containing the names of the RTclients where delivery is still pending for the message

The polling RTclient acquires the GMD_STATUS_RESULT message after calling TipcSrvGmdMsgStatus, using functions like TipcSrvMsgSearchType.