TipcConnRead

TipcConnRead — read data from a connection and queue messages in priority order

Synopsis

T_BOOL TipcConnRead(conn, timeout) 
T_IPC_CONN conn; 
T_REAL8 timeout;

Arguments

Return Values

Diagnostics

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

T_ERR_NULL_PTR — conn was null

T_ERR_VAL_TOO_SMALL — timeout was negative

T_ERR_IN_PROGRESS — TipcConnRead was called recursively for a connection (from a read callback or queue callback)

T_ERR_C — a C error has occurred. Call the function TutErrNumGetC to obtain the related C-specific error value.

T_ERR_OS — an operating system error has occurred. Call the function TutErrNumGetOs to obtain the related OS-specific error value.

T_ERR_SOCKET — a socket error has occurred. Call the function TutErrNumGetSocket to obtain the related socket-specific error value.

T_ERR_EOF — the other end of the connection’s socket has been closed (EOF has been reached). The connection should be destroyed and then a new connection created if necessary.

T_ERR_WOULD_BLOCK — conn is in non-blocking mode, and no data could be received without blocking

any error number from TipcConnFlush

any error number from TipcConnCheck

Description

TipcConnRead reads and queues messages that arrive (within a certain period of time) from a connection’s socket. If the connection’s auto flush size is not T_IPC_NO_AUTO_FLUSH, then TipcConnRead first calls TipcConnFlush to flush the connection’s write buffer (so that any responses to the outgoing data are available sooner). TipcConnRead then reads data (in the form of message packets) from a connection’s socket and calls the connection decode callbacks. If necessary, the integers and strings in the message header are converted to the formats used by the receiving process. TipcConnRead then converts the message packets into messages, and calls the connection’s read callbacks. TipcConnRead returns as soon as at least one message is read, so that high-data-rate applications do not sit forever reading data.

For each message read in, if the message has a delivery mode of either T_IPC_DELIVERY_SOME or T_IPC_DELIVERY_ALL then TipcConnRead performs some extra steps for guaranteed message delivery. If the connection does not have a GMD area open, then TipcConnRead calls TipcConnGmdFileCreate to create the necessary GMD area. TipcConnRead checks if the message has already been received and acknowledged, and, if so, immediately reacknowledges the message and destroys the message. TipcConnRead also directly acts on incoming acknowledgment messages that are received for messages that have been sent on this connection.

If any messages are read in, TipcConnRead 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 process(es). TipcConnRead 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 TipcConnRead only checks for delivery timeouts after reading in messages, be careful to ensure that the timeout used with TipcConnRead is not larger than the connection delivery timeout property.

TipcConnRead then inserts the new messages according to priority into the connection’s queue of available messages and calls the connection’s queue callbacks.

TipcConnRead calls TipcConnCheck with timeout to check for network failures and to prevent the process from waiting longer than the desired timeout. TipcConnRead blocks if the socket function recv blocks (that is, no data is available on the socket). If the read fails (because recv returned 0 or -1), the connection’s error callbacks are called to clean up, and TipcConnRead returns FALSE.

Caution

TipcConnRead is a low-level function that is normally not used directly by developers; it is normally called only by TipcConnMsgNext and TipcConnMsgSearch.

If TipcConnGmdFileCreate fails to create a file-based GMD area, a warning similar to this is output with TutWarning:

WARNING: Could not create GMD file(s) with base name 
<local_node_test> 
for connection <client:local:_node:test>. 
The option Unique_Subject must be set to a value other 
than the default (_workstation1_8668). 
Switching to memory-only GMD.

If this warning appears, the process is not configured properly to use file-based GMD. See TipcConnGmdFileCreate for more information on creating GMD areas.

Because TipcConnRead returns as soon as at least one message is read in, message priorities often have a limited impact on ordering. Large messages sent over a network are often fragmented by the network hardware and cause TipcConnRead to never read multiple large messages in one call. On systems like Solaris 2.X local sockets are not byte streams but are record-oriented devices. On these systems, if several small messages are flushed with TipcConnFlush one at a time by the sender, TipcConnRead does not read several messages at a time and sort them by priority.