TipcConnCheck

Name

TipcConnCheck — check if data can be read from or written to a connection

Synopsis

T_BOOL TipcConnCheck(conn, check_mode, timeout) 
T_IPC_CONN conn; 
T_IO_CHECK_MODE check_mode; 
T_REAL8 timeout; 

Arguments

conn — connection to check

check_mode — how to check the connection for availability (T_IO_CHECK_READ to check for reading, T_IO_CHECK_WRITE to check for writing)

timeout — maximum number of seconds to wait for availability

Return Values

TRUE if data can be read or written, FALSE if timeout reached or error occurred.

Diagnostics

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

Description

TipcConnCheck checks if data can be read from or written to a connection by calling TutSocketCheck with the connection’s socket. Use 0.0 for timeout to poll the connection and return immediately. Use T_TIMEOUT_FOREVER for timeout to wait indefinitely for availability.

If check_mode is T_IO_CHECK_READ the connection is checked for reading. In this mode, if the connection’s auto flush size is not T_IPC_NO_AUTO_FLUSH, then TipcConnCheck first calls TipcConnFlush to flush the connection’s write buffer (so that any responses to the outgoing data are available sooner). If the connection’s block mode is TRUE or the connection’s read timeout is 0.0, then TipcConnCheck calls TutSocketCheck once with timeout and returns. Otherwise TipcConnCheck keeps calling TutSocketCheck over and over with a calculated timeout until data is available, the timeout period is reached, or an error occurs. The calculated timeout ensures that TipcConnCheck never waits for more than read timeout seconds past the last time data was read on the connection.

This pseudocode shows the calculation:

$elapsed_time = TutGetWallTime() - (the time when data was last 
read) 
if ($elapsed_time > read_timeout) { 
  $calculated_timeout = 0 
} 
else { 
  $calculated_timeout = read_timeout - $elapsed_time 
} 

After each call to TutSocketCheck with the calculated timeout, if no data is available, and read_timeout seconds have elapsed since the last time data was read, then a keep alive is initiated to check the health of the connection by calling TipcConnKeepAlive. If TipcConnKeepAlive fails, a network failure has occurred, and the connection’s error callbacks are called.

If no data is available for reading, TipcConnCheck checks for guaranteed message delivery timeouts. When messages with a delivery mode of T_IPC_DELIVERY_SOME or T_IPC_DELIVERY_ALL are sent through a connection with TipcConnMsgSend, copies of the messages are saved in the connection GMD area. The copies are removed when acknowledgment of delivery is received by the sender from the receiving processes. TipcConnCheck checks how many seconds have elapsed since each previously sent guaranteed message was sent. For each message where the elapsed time is greater than the connection delivery timeout, the timed-out message is removed from the connection GMD area, a GMD_FAILURE message is created whose first field is the timed-out message, and TipcConnMsgProcess is called to asynchronously notify the sending process that there has been a delivery timeout. See TipcCbConnProcessGmdFailure for more information on processing GMD_FAILURE messages. Because TipcConnCheck only checks for delivery timeouts after calling TutSocketCheck, ensure that the timeout used with TipcConnCheck is not larger than the connection delivery timeout property.

If check_mode is T_IO_CHECK_WRITE, the connection is checked for writing. If the connection’s block mode is TRUE or the connection’s write timeout is 0.0, then TipcConnCheck calls TutSocketCheck once with timeout and returns. Otherwise TipcConnCheck calls TutSocketCheck once with a calculated timeout that is similar to the one used when checking for reading (see above pseudocode). Note that checking for writing does not initiate keep alives; if data cannot be written in time, there is no point in trying a keep alive (which would send a KEEP_ALIVE_CALL message). If the check for writing fails, a network failure has occurred, and the connection’s error callbacks are called.

Caution

TipcConnCheck is a low-level function that is normally not used directly by developers. TipcConnCheck is normally called only by TipcConnFlush and TipcConnRead.

See Also

TipcConnFlush, TipcConnRead; see the TIBCO SmartSockets Utilities for information on TutSocketCheck.

Examples

This example checks if data is available for reading on a connection within 3.4 seconds:

if (!TipcConnCheck(conn, T_IO_CHECK_READ, 3.4)) { 
  return;  /* error */ 
}