TipcCbConnProcessGmdFailure

Name

TipcCbConnProcessGmdFailure — callback on all connections to process GMD_FAILURE messages when guaranteed message delivery fails

Synopsis

void TipcCbConnProcessGmdFailure(conn, data, arg) 
T_IPC_CONN conn; 
T_IPC_CONN_PROCESS_CB_DATA data; 
T_CB_ARG arg; 

Arguments

conn — connection where guaranteed message delivery failed

data — callback data

arg — callback argument (not used)

Return Values

None

Diagnostics

None

Description

TipcCbConnProcessGmdFailure is a callback that processes each GMD_FAILURE message that is generated internally when guaranteed message delivery fails. When a message with a delivery mode of T_IPC_DELIVERY_SOME or T_IPC_DELIVERY_ALL is sent through a connection (always with TipcConnMsgSend), a copy of the message is saved in the connection’s GMD area. The copy is removed when the sender receives acknowledgment from the receiving processes of successful delivery. If GMD fails, a GMD_FAILURE message is created internally and TipcConnMsgProcess is called to asynchronously notify the sending process that there has been a GMD failure.

When a GMD_FAILURE message is processed by a sender, one of two scenarios is possible:

Each GMD_FAILURE message contains four fields:

There are several ways GMD can fail. These error numbers are used only in GMD_FAILURE messages, not in the global SmartSockets global error number accessible with TutErrNumGet:

TipcCbConnProcessGmdFailure is intended as a sample callback which is designed only to warn the user that guaranteed delivery of a message has failed. More sophisticated applications should create their own process callbacks for GMD_FAILURE messages to perform actions such as user-defined recovery procedures.

TipcCbConnProcessGmdFailure first prints output with TutWarning that is similar to this output:

WARNING: Guaranteed message delivery failed (error number 
T_ERR_GMD_ERROR) on the connection <client:local:_node:RTSERVER>. 
WARNING: The message was originally sent at TIME. 

TipcCbConnProcessGmdFailure then prints some error-code-specific output with TutWarning, prints the undelivered message with TipcMsgPrint and TutOut, and finally calls TipcConnGmdMsgDelete to terminate GMD for the message.

TipcConnCreate calls TipcConnProcessCbCreate to create a process callback with message type GMD_FAILURE, function TipcCbConnProcessGmdFailure, and argument NULL. This callback may be destroyed by looking up the callback with TipcConnProcessCbLookup and then destroying it with TutCbDestroy.

T_ERR_GMD_SENDER_TIMEOUT is the only error number applicable for GMD that uses only TipcConn* functions. For GMD using RTclient TipcSrv* functions, the other error numbers also apply, and additional actions are usually needed to process GMD_FAILURE messages. TipcSrvCreate creates an additional GMD_FAILURE process callback using TipcCbSrvProcessGmdFailure. See TipcCbSrvProcessGmdFailure for more information on the RTclient-specific aspects of GMD failure.

Caution

TipcCbConnProcessGmdFailure is not meant to be called directly and should only be used as a callback function.

See Also

TipcCbSrvProcessGmdFailure, TipcConnCreate, TipcConnCheck, TipcConnProcessCbCreate, TipcConnRead

Examples

This example creates a client connection to a server process, looks up the callback that uses TipcCbConnProcessGmdFailure, destroys the callback, and creates a new process callback for GMD_FAILURE messages:

T_IPC_CONN conn; 
T_IPC_MT mt; 
T_CB cb; 
conn = TipcConnCreateClient("local:_node:test.tmp"); 
if (conn == NULL) { 
  return;  /* error */ 
}  
 
mt = TipcMtLookupByNum(T_MT_GMD_FAILURE); 
if (mt == NULL) { 
  return;  /* error */ 
}  
 
cb = TipcConnProcessCbLookup(conn, mt, 
                             TipcCbConnProcessGmdFailure, NULL); 
if (cb == NULL) { 
  return;  /* error */ 
}  
 
if (!TutCbDestroy(cb)) { 
  return;  /* error */ 
} 
 
cb = TipcConnProcessCbCreate(conn, mt, my_gmd_failure_cb_func, 
                             NULL); 
if (cb == NULL) { 
  return;  /* error */ 
}