Connection Composition

A connection (C type T_IPC_CONN) is composed of several parts, or properties. Not all properties are directly accessible, but all are important.

Figure 2 shows the flow of messages through the relevant properties of a connection.

A connection has these properties:

Socket

The socket property identifies the operating system device that provides the communication link to another process. All messages that are sent and received through the connection are transmitted using the socket. The socket property is an operating system file descriptor of type C type T_INT4. The property is set automatically when a client or server connection is created with TipcConnCreateClient, TipcConnCreateServer, or TipcConnAccept. To change the value of the property, you can use TipcConnSetSocket:

if (!TipcConnSetSocket(conn, fd)) { 
  /* error */ 
} 

To get the existing value of the socket property, use TipcConnGetSocket:

 
if (!TipcConnGetSocket(conn, &fd)) { 
  /* error */ 
} 

For an in-depth discussion of sockets, see Sockets.

A concept related to the connection socket is the connection Xt-compatible source. See Mixing Connections and Xt Intrinsics (Motif) for more information on how to use connections in a Motif program.

Read Buffer

The read buffer of a connection is where incoming messages are first stored when they are read from the connection’s socket. The incoming messages arrive as a stream of bytes, which are unpacked into messages and inserted into the connection’s message queue (for a discussion of connection message queues, see Message Queue) in priority order. Each time data is read from the connection’s socket, only a piece of a message may arrive. The read buffer is used to reassemble all the pieces of an incoming message.

The read buffer is not directly accessible. The read buffer is sized dynamically to hold all incoming data and is limited only by the amount of available virtual memory. Each time data is read from the connection’s socket, all complete messages in the read buffer are unpacked and moved from the read buffer to the message queue. Thus the read buffer does not use a large amount of memory unless large messages are used.

The function TipcConnRead reads data from the connection’s socket into the read buffer and converts the data into messages, which are then inserted into the connection’s message queue with the function TipcConnMsgInsert.

Write Buffer

The write buffer of a connection is where outgoing messages are stored before they are written to the connection’s socket. By accumulating several messages in the write buffer before actually writing them to the socket, better performance can be achieved.

The write buffer is not directly accessible. The write buffer is sized dynamically to hold all buffered outgoing data and is limited only by the amount of available virtual memory. The connection property auto flush size helps to limit the amount of memory used by the write buffer. For a discussion of the connection auto flush size, see Auto Flush Size.

The function TipcConnMsgSend copies a message to the end of the write buffer, and the function TipcConnFlush writes the write buffer to the connection’s socket.

Message Queue

The message queue of a connection is where incoming messages are stored waiting to be processed. Messages are normally stored in the message queue ordered by message priority, although they can be inserted anywhere into the message queue.

The message queue is not directly accessible. The function TipcConnMsgInsert inserts a message into a connection’s message queue. The function TipcConnMsgNext gets the first message from a connection’s message queue. The function TipcConnMsgSearch searches a connection’s message queue for a specific message. The function TipcConnGetNumQueued gets the number of messages in a connection’s message queue.

Block Mode

The block mode property is a boolean that identifies whether or not a process waits for a read, write, or accept operation to complete on a connection’s socket. Read, write, and accept operations are treated slightly differently. Read operations are always given a certain period of time to complete, while write operations are not. A write or accept operation either completes immediately or the process waits until the operation completes.

To change the value of the block mode property, use TipcConnSetBlockMode:

if (!TipcConnSetBlockMode(conn, TRUE)) { 
  /* error */ 
} 

To get the existing value of the property, use TipcConnGetBlockMode:

 
if (!TipcConnGetBlockMode(conn, &block_mode)) { 
  /* error */ 
} 

If the block mode property is TRUE, which is the default, the function TipcConnRead does not return until it has read some data from the connection’s socket into the connection’s read buffer, an error has occurred, or the specified period of time has elapsed. The function TipcConnFlush does not return until it has written all data from the connection’s write buffer to the connection’s socket or an error has occurred. The function TipcConnAccept does not return until it has accepted a client connection or an error has occurred.

If the block mode property is FALSE, then non-blocking read, write, and accept operations are enabled. It is unusual to use non-blocking accept operations; they are provided for completeness only. The behavior of non-blocking read and write operations depends on the settings of the connection timeout properties (see Read Timeout, Write Timeout, and Keep Alive Timeout for more information on these timeout properties). A connection’s block mode must be FALSE for the timeout properties to have any effect. Table 3 shows the relationship between the block mode and timeout properties. If the block mode property is FALSE and the write timeout property is 0.0, then TipcConnFlush returns immediately if not all data can be written. If the block mode property is FALSE and the write timeout property is greater than 0.0, then TipcConnFlush does not return until all data has been written or a period of time equal to the write timeout property has elapsed.

Auto Flush Size

The auto flush size property is defined as a four-byte integer that identifies how many bytes of data are allowed to accumulate in a connection’s write buffer before it is automatically written (flushed) to the connection’s socket. When a message is copied to the end of the connection’s write buffer with the function TipcConnMsgSend, the auto flush size is checked, and TipcConnMsgSend calls the function TipcConnFlush if the number of bytes of data in the write buffer is greater than the auto flush size. In addition, both TipcConnRead and TipcConnCheck automatically flush the write buffer to the socket when reading and checking for reading.

If the auto flush size property of a connection is set to 0, then each outgoing message is immediately written to the connection’s socket. To enable infinite buffering, an auto flush size of T_IPC_NO_AUTO_FLUSH can be used, and outgoing messages are never automatically flushed (they have to be explictly flushed). The default size is 8192 bytes.

To change the value of the auto flush size property, use TipcConnSetAutoFlushSize:

if (!TipcConnSetAutoFlushSize(conn, 0)) { 
  /* error */ 
} 

To get the existing value for the property, use TipcConnGetAutoFlushSize:

if (!TipcConnGetAutoFlushSize(conn, &auto_flush_size)) { 
  /* error */ 
} 

Read Timeout

The read timeout property is defined as an eight-byte real number that identifies how often, in seconds, data is expected to be available for reading on a connection’s socket. This timeout is used to check for possible network failures.

Whenever a process is waiting for a read operation on a connection’s socket to complete, it does not wait longer than read timeout seconds past the time of the last successful read. If a period of time longer than the read timeout has elapsed, then a hardware or software failure may have occurred; a query then is sent to the other end of the connection to determine if the connection is still alive. This query is called a keep alive. See Handling Network Failures for more information on keep alives.

If the read timeout property of a connection is set to 0.0, which is the default, then checking for read timeouts is disabled. Setting the block mode property of a connection to TRUE also disables checking for read timeouts.

To change the value of the read timeout property, use TipcConnSetTimeout:

if (!TipcConnSetTimeout(conn, T_IPC_TIMEOUT_READ, 10.0)) { 
  /* error */ 
} 

To get the existing value for the property, use TipcConnGetTimeout:

if (!TipcConnGetTimeout(conn, T_IPC_TIMEOUT_READ, &read_timeout)) 
{ 
  /* error */ 
} 

Write Timeout

The write timeout property is defined as an eight-byte real number that identifies how often, in seconds, data is expected to be able to be written to a connection’s socket. This timeout is used to check for possible network failures.

Whenever a process is waiting for a write operation on a connection’s socket to complete, it does not wait longer than write timeout seconds past the time of the last successful write. If a period of time longer than the write timeout has elapsed, then a hardware or software failure may have occurred, and the error callbacks for the connection will be called to recover from the error. See Error Callbacks for more information on error callbacks. Unlike the read timeouts, where a keep alive is initiated, no keep alive is initiated for write timeouts. See Handling Network Failures for more information on keep alives.

If the write timeout property of a connection is set to 0.0, which is the default, checking for write timeouts is disabled. Setting the block mode property of a connection to TRUE also disables checking for write timeouts.

To change the value for the write timeout property, use TipcConnSetTimeout:

if (!TipcConnSetTimeout(conn, T_IPC_TIMEOUT_WRITE, 10.0)) { 
  /* error */ 
} 

To get the existing value for the property, use TipcConnGetTimeout:

if (!TipcConnGetTimeout(conn, T_IPC_TIMEOUT_WRITE, 
&write_timeout)) { 
  /* error */ 
} 

Keep Alive Timeout

The keep alive timeout property is defined as an eight-byte real number that identifies how long, in seconds, to wait for a keep alive query to complete. A keep alive query consists of sending a KEEP_ALIVE_CALL through a connection and waiting for the process at the other end to send back a KEEP_ALIVE_RESULT message to indicate that the connection is still alive. See Handling Network Failures for more information on the keep alive timeout and keep alives.

If the keep alive timeout property of a connection is set to 0.0, which is the default, then keep alive queries are disabled. To change the value, use TipcConnSetTimeout:

if (!TipcConnSetTimeout(conn, T_IPC_TIMEOUT_KEEP_ALIVE, 10.0)) { 
  /* error */ 
} 

To get the existing value for the property, use TipcConnGetTimeout:

if (!TipcConnGetTimeout(conn, T_IPC_TIMEOUT_KEEP_ALIVE,  
                        &keep_alive_timeout)) { 
  /* error */ 
} 

Delivery Timeout

The delivery timeout property is defined as an eight-byte real number that identifies how long, in seconds, to wait for guaranteed delivery of a message sent from this process through a connection. This timeout is used to check for possible network failures, although at a slightly different level from the read timeout, write timeout, and keep alive timeout (those three are not directly involved with GMD).

Whenever a process sends a message with a delivery mode of T_IPC_DELIVERY_SOME or T_IPC_DELIVERY_ALL, a copy of the message and the current wall clock time are saved in the connection GMD area. See GMD Area for more information on GMD areas. The message copy is removed when acknowledgment of delivery is received by the sender from the receiving process(es). Delivery timeouts are checked each time the sending process reads data or checks if data can be read from the connection. If delivery timeout seconds have elapsed since the message was sent with GMD, then a GMD failure has occurred, and a GMD_FAILURE message will be processed by the sender. See Chapter 4, Guaranteed Message Delivery for more information on GMD. Note that each message can also have its own delivery timeout, which defaults to the connection’s delivery timeout if it is not set before the message is sent.

If the delivery timeout property of a message is set to 0.0, which is the default, checking for delivery timeouts is disabled. To change the value, use TipcConnSetTimeout:

if (!TipcConnSetTimeout(conn, T_IPC_TIMEOUT_DELIVERY, 10.0)) { 
  /* error */ 
} 

To get the existing value of the property, use TipcConnGetTimeout:

if (!TipcConnGetTimeout(conn, T_IPC_TIMEOUT_DELIVERY, 
                        &delivery_timeout)) { 
  /* error */ 
} 

GMD Area

The GMD area for a connection holds guaranteed message delivery information for both incoming and outgoing messages. There are two types of GMD:

The GMD area is not directly accessible. Using the RTclient option Ipc_Gmd_Directory, you can specify where you want the file-based GMD area created. Once the GMD area is created, it cannot be changed or destroyed except by destroying the connection. The function TipcConnSetGmdMaxSize can be used to set the maximum size of the GMD area.

See Chapter 4, Guaranteed Message Delivery for more information on GMD.

Thread Synchronization

The set of connection properties used for thread synchronization protect connections for multithreaded access. There are no functions that get or set the values for these properties:

For more information on using connections in multithreaded programs, see Using Threads With Connections. For more information on these mutex properties, see Working With Threads and Connections.

Peer Information

These connection properties are all pieces of information about the process at the other end of the connection. These properties are all simple types of monitoring and can be useful for diagnostic purposes. For more information on monitoring, see Chapter 5, Project Monitoring.

Architecture

The architecture property is defined as an identifier string that identifies the SmartSockets architecture of the peer process. The architecture is in the form Machine_OperatingSystem (for example, sun4_solaris).

This value is stored in:

This property is set automatically by TipcConnCreateClient and TipcConnAccept, and cannot be set manually. To find out the value set for this property, use TipcConnGetArch:

if (!TipcConnGetArch(conn, &arch)) { 
  /* error */ 
} 

Node

The node property is defined as a string that identifies the node name of the peer process. This property is set automatically by TipcConnCreateClient and TipcConnAccept, and cannot be set manually. To find out the value set for this property, use TipcConnGetNode:

if (!TipcConnGetNode(conn, &node)) { 
  /* error */ 
} 

Process ID

The process ID property is defined as a four-byte integer that provides the process identifier of the peer process. This property is set automatically by TipcConnCreateClient and TipcConnAccept, and cannot be set manually. To find out the value set for this property, use TipcConnGetPid:

if (!TipcConnGetPid(conn, &pid)) { 
  /* error */ 
} 

Unique Subject

The unique subject property is defined as a string that identifies the unique subject of the peer process. The unique subject, which is used to uniquely identify all SmartSockets processes, is stored in the option Unique_Subject. See Configuring GMD for a discussion of how Unique_Subject is used by connections.

This property is set automatically by TipcConnCreateClient and TipcConnAccept, and cannot be changed. To find out the value for this property, use TipcConnGetUniqueSubject:

if (!TipcConnGetUniqueSubject(conn, &unique_subject)) { 
  /* error */ 
} 

User

The user property is defined as a string that identifies the user name of the peer process. This property is set automatically by TipcConnCreateClient and TipcConnAccept, and cannot be set manually. To find out the value set for this property, use TipcConnGetUser:

if (!TipcConnGetUser(conn, &user)) { 
  /* error */ 
} 

Callbacks

Callbacks are functions that are executed when certain operations occur. Callbacks are conceptually equivalent to dynamically adding a line of code to a program.

These are the types of callbacks available to you:

When a message is sent out by calling TipcSrvMsgSend, the callbacks are called in this order:

For more discussion about callback functions, see Callbacks.