TipcSrvSubjectLbInit

Name

TipcSrvSubjectLbInit — initialize load balancing accounting in RTserver for a subject to which messages will be published

Synopsis

T_BOOL TipcSrvSubjectLbInit(subject) 
T_STR subject; 

Arguments

subject — name of subject to which messages will be published with load balancing

Return Values

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

Diagnostics

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

Description

TipcSrvSubjectLbInit initializes load balancing 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 load balancing initialization is complete. The response should come back very quickly. The GMD_INIT_RESULT message contains one field: a STR string 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 load balancing, it keeps track of which RTclients should receive the message. If this RTserver is not already tracking load balancing 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 load balancing because only the relevant RTservers dynamically exchange load balancing information.The load balancing 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 load balancing accounting is very fast but not instantaneous. TipcSrvSubjectLbInit is intended to be used by advanced publish-subscribe applications that wish to ensure that RTserver is primed and immediately ready for load balancing publish-subscribe routing.

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

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

Caution

TipcSrvSubjectLbInit 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

TipcSrvSubjectLbInit, TipcSrvMsgSend, TipcSrvMsgWrite

Examples

This example uses TipcSrvSubjectLbInit to initialize load balancing 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 load balancing accounting in RTserver */ 
if (!TipcSrvSubjectLbInit("/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 */