TipcConnKeepAlive

Name

TipcConnKeepAlive — check if the process at the other end of a connection is still alive

Synopsis

T_BOOL TipcConnKeepAlive(conn) 
T_IPC_CONN conn; 

Arguments

conn — connection to initiate keep alive on

Return Values

TRUE if the other end of the connection responded in time, FALSE otherwise.

Diagnostics

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

Description

TipcConnKeepAlive performs a remote procedure call to check if the process at the other end of a connection is still alive. This explicit attempt to check the health of a connection is called a keep alive. TipcConnKeepAlive is normally used only by TipcConnCheck, which automatically checks the connection based on the read timeout property of the connection. TipcConnKeepAlive can be called explicitly, though, to check the health of the connection.

TipcConnKeepAlive performs these steps:

If the other end of the connection is alive, it receives the KEEP_ALIVE_CALL message, processes it with TipcCbConnProcessKeepAliveCall, and sends a KEEP_ALIVE_RESULT message back to this end.

Caution

If keep alives are used for non-RTserver connections, care must be taken to read and process messages at a regular interval. Otherwise the keep alives fail.

See Also

TipcCbConnProcessKeepAliveCall, TipcConnGetTimeout, TipcConnSetTimeout, TipcConnMsgSendRpc

Examples

This example shows a simple way to check the health of a connection every 10 seconds:

/* enable keep alives by setting the keep alive timeout to a non-zero value */ 
if (!TipcConnSetTimeout(conn, T_IPC_TIMEOUT_KEEP_ALIVE, 5.0)) { 
  return;  /* error */ 
} 
 
for (;;) { 
  if (!TipcConnKeepAlive(conn)) { 
    return;  /* error */ 
  } 
  TutSleep(10.0); 
}  

Because TipcConnCheck automatically calls TipcConnKeepAlive when checking for reading, the above fragment could be rewritten as:

/* enable keep alives by setting the keep alive timeout to a non-zero value */ 
if (!TipcConnSetTimeout(conn, T_IPC_TIMEOUT_KEEP_ALIVE, 5.0)) { 
  return;  /* error */ 
} 
 
/* enable read timeout checking by setting the read timeout to a non-zero value */ 
if (!TipcConnSetTimeout(conn, T_IPC_TIMEOUT_READ, 10.0)) { 
  return;  /* error */ 
} 
 
/* based on the above timeout settings, TipcConnCheck will initiate a keep alive every 10 seconds 
and wait for up to 5 seconds for the keep alive to complete */ 
if (!TipcConnCheck(conn, T_IO_CHECK_READ, T_TIMEOUT_FOREVER)) { 
  return;  /* error */ 
}