com.solacesystems.solclientj.core.handle

Interface IPCSupport

public interface IPCSupport

Inter-Process Communications

Introduction

The Inter-Process Communications (IPC) capability of the Messaging API for C allow applications to communicate directly with each other and to communicate with a Solace Messaging Platform (that is, the Solace Appliance network).

The primary use-case for the IPC capability is to facilitate communications between applications co-residing on a host. Instead of communicating through connections to a Solace messaging Appliance, the applications can establish direct communication channels to each other. Typically, this is done to achieve ultra-low latency communications among the applications, or to reduce the bandwidth used by the applications on both the host and the Solace messaging Appliance.

Communications between applications on a single host can occur through shared memory or a shared TCP channel. Communicating through shared memory offers lower overhead and lower latency than communicating through a TCP channel. It is also possible for applications on the same host to use both shared memory and a shared TCP channel at the same time to communicate with each other.

Another use case for IPC is to allow applications residing on separate hosts to establish a direct communication channel, and bypass the Solace messaging Appliance network. For example, two applications could establish a direct channel to exchange large data sets which no other application in the network is interested in. Such direct communication preserves capacity in the Solace Messaging Platform, but it also requires a tight coupling between the communicating applications.

Applications on separate hosts can communicate with each other through a TCP channel; communicating through shared memory is not possible.

Spinning and Blocking Shared Memory Threads

You can configure the internal shared memory thread to hard-spin for extremely low-latency receive processing or to block to preserve CPU resources when waiting for incoming messages. You can also configure a combination of these two actions.

When configured to always spin, the internal shared memory thread continuously polls all shared memory channels that it is handling to look for new incoming messages. The use of spinning avoids operating system calls, and it avoids the scheduling overhead and latency incurred with block waiting for incoming messages. It provides the lowest possible receive latency, but it also requires that the application dedicate a CPU core for incoming message processing.

When configured to block, the internal shared memory thread blocks on an operating system synchronization call and waits until new messages arrive on one of the shared memory channels being handled.

The other option is for the internal shared memory thread to spin a set number times while waiting for new incoming message, and then if no messages arrive it enters the operating system to block. It is up to the application to tune the number of times to spin before blocking. This allows for low-latency receive processing when messages are constantly arriving, but the thread can also fall back into a blocking behavior when there is a lull in incoming message traffic.

When two applications communicate over a shared memory channel, each application independently decides if it will block or spin to receive message from that channel.

Mixing Transport Modes

Separate Context and shared memory threads exist with a Context. This means that there are two different threads that can dispatch received messages to the application when TCP and shared memory transports are used at the same time within a single Context.

However, to protect the application, the API only allows one thread at a time to dispatch messages to the application. Therefore a message cannot be simultaneously dispatched from a TCP transport and a shared memory transport at the same time. This is done so that the message receive logic in the application does not have to be re-entrant.

If the application uses the timer service offered by the API, time-out events are only dispatched from the Context thread, not from the internal shared memory thread. Likewise, Session events are only dispatched from the Context thread.

Configuring the Transport Channel Type

The transport channel type used for IPC is configured through the syntax of the SessionHandle.PROPERTIES.HOST property. The entry for the SessionHandle.PROPERTIES.HOST property should provide a protocol, host, and port specified as follows:

[Protocol:]Host[:Port]

The SessionHandle.PROPERTIES.HOST supports multiple host entries separated by semi-colon. Each such semi-colon entry specifies the host for another sub-channel for the Session.

Where: Protocol is the protocol used for the transport channel. The valid values are:

• tcp - use a TCP channel for communications between the application and its peers. If no protocol is set, tcp is used as a default.
• shm - use a shared memory channel for communications between the application and its peers. A TCP channel is first established, the peers then switch to a shared memory channel and tear down the TCP connection.
• listen - have the Session listen for and accept incoming TCP connections. The peer establishing the connection indicates whether communications should continue over TCP or be switched to shared memory communications.

Host - the IP address (or host name) to connect to or listen to for incoming connections. When the protocol is 'listen', Host may be set to '*' which indicates the C API should listen on all interfaces (INADDR_ANY).

Port - the port to connect to for an outgoing TCP connection, or to listen on for incoming TCP connections. A value is only required when using a port other than the automatically assigned default port number. (The default port is 55555 when compression is not in use, or 55003 when compression is in use.)
The following examples show how to specify transport channel types. Unless it is otherwise specified, the default port 55555 is used.

• 192.168.160.28 - connect to this IP address over TCP
• tcp:192.168.160.28 - connect to this IP address over TCP
• shm:127.0.0.1 - connect to this IP address over TCP, and then switch to shared memory communications.
• listen:127.0.0.1:44444 - listen for incoming TCP connections on a loopback IP address, port 44444. Incoming connections can specify whether communication should continue over TCP or use shared memory.

Session Events with IPC

An application only sees a single Session, even though there can be many sub-Sessions below it within the API, to allow IPC communications with multiple peer applications (as shown in Figure 1-1). Therefore, because the application only interacts with the one Session, it only receives Session events from that single Session.

When the application connects the Session, it receives a Session up event when the first subSession successfully connects. There are no further Session up events as more sub-Sessions are established by the API. Similarly, the application only receives a reconnecting or Session down event when the last subSession is no longer established.

As a result, the application does not see, and cannot query, the status of individual IPC transports to peer applications. This view is similar to what the application would have if it were communicating with other applications through a Solace messaging Appliance, instead of communicating with them directly through IPC.

IPC Shared Memory Size

When shared memory is used for IPC communications, the Session parameters SessionHandle.PROPERTIES.SOCKET_SEND_BUF_SIZE and SessionHandle.PROPERTIES.SOCKET_RCV_BUF_SIZE are used to set the size of the shared memory FIFO created for messaging. The connecting application creates two shared memory FIFOs and the listening application attaches to the FIFOs. SessionHandle.PROPERTIES.SOCKET_SEND_BUF_SIZE bytes of shared memory are available for sending messages from the connecting application to the listening application. see SessionHandle.PROPERTIES.SOCKET_RCV_BUF_SIZE bytes of shared memory are available for receiving messages in the connecting application that are sent by the listening application.

IPC Resource Cleanup

As there is no way to safely catch every exit signal, IPC resources cleanup in the case of a crash is the responsibility of host OS / system administrator.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	IPCSupport.CONTEXT_PROPERTIES Defines property names that support IPC settings for a ContextHandle, these settings are used to create a Context Solclient.createContextForHandle()
static class	IPCSupport.SESSION_PROPERTIES Defines property names that support IPC settings for a SessionHandle, these settings can be combined with SessionHandle.PROPERTIES and used to create a Session (ContextHandle.createSessionForHandle())