TipcSrvSubjectGmdInit

Name

TipcSrvSubjectGmdInit — initialize GMD accounting in RTserver for a subject to which messages will be published

Synopsis

T_BOOL TipcSrvSubjectGmdInit(subject) 
T_STR subject; 

Arguments

subject — name of subject to which messages will be published with GMD

Return Values

TRUE if the request for GMD initialization was successfully initiated, FALSE otherwise.

Diagnostics

If TipcSrvSubjectGmdInit fails, it returns FALSE and sets the global SmartSockets error number to one of:

Description

TipcSrvSubjectGmdInit initializes GMD accounting in RTserver for a subject to which messages will be published by sending a GMD_INIT_CALL message to RTserver. RTserver responds by sending back a GMD_INIT_RESULT message when GMD initialization is complete. The response should come back very quickly. The GMD_INIT_RESULT message contains one field: a STR field containing the subject name for which initialization has completed. The polling RTclient can use functions such as TipcSrvMsgSearchType to get the response.

Both guaranteed message delivery and load balancing currently use the same accounting mechanism. Use TipcSrvSubjectLbInit, however, to initialize load balancing accounting for a subject.

When the RTserver connected to the publishing RTclient routes a message for GMD, it keeps track of which RTclients should receive the message and the status of GMD to each of these RTclients. If this RTserver is not already tracking GMD for subject when the first published message arrives from RTclient, the RTserver must start a monitoring-like watch mechanism between the RTservers of all subscribing RTclients. This increases the scalability of GMD because only the relevant RTservers dynamically exchange GMD information.The GMD accounting continues until no messages have been published with GMD or load balancing for an interval specified by the Gmd_Publish_Timeout option. The default for Gmd_Publish_Timeout is 300 seconds.

The starting of this GMD accounting is very fast, but not instantaneous. TipcSrvSubjectGmdInit is intended to be used by advanced publish-subscribe applications that wish to ensure that RTserver is primed and immediately ready for GMD publish-subscribe routing.

TipcSrvSubjectGmdInit is usually only used at initialization, but it can be called at any time by advanced applications that wish to initialize GMD publishing accounting. The use of TipcSrvSubjectGmdInit is strictly optional for GMD publishing; if it is not called, the GMD setup occurs when the first GMD message is published to subject.

If RTserver is already tracking GMD for subject, RTserver immediately returns a GMD_INIT_RESULT message.

Caution

TipcSrvSubjectGmdInit sends a GMD_INIT_CALL message to RTserver, but does not explicitly flush the message. See TipcSrvGetAutoFlushSize for more information on message buffering.

See Also

TipcSrvMsgSend, TipcSrvMsgWrite, TipcSrvSubjectLbInit

Examples

This example uses TipcSrvSubjectGmdInit to initialize GMD accounting in RTserver for the /system/thermal subject and then waits for the result message:

T_IPC_MT mt; 
T_IPC_MSG result_msg; 
 
/* initialize GMD accounting in RTserver */ 
if (!TipcSrvSubjectGmdInit("/system/thermal")) { 
  return;  /* error */ 
} 
 
mt = TipcMtLookupByNum(T_MT_GMD_INIT_RESULT); 
if (mt == NULL) { 
  return;  /* error */ 
} 
 
/* wait a short time for the GMD init result */ 
result_msg = TipcSrvMsgSearchType(10.0, mt); 
if (result_msg == NULL) { 
  return;  /* error */ 
} 
 
/* must set current field first */ 
if (!TipcMsgSetCurrent(result_msg, 0)) { 
  return;  /* error */ 
} 
 
/* at this point, we could read the first field of the result message to verify the subject name */