IPC Framework

The IPC framework is based on message-passing. The interface is asynchronous (i.e. non-blocking).

Throughout the documentation, the programs that are written by the user will be referred to as “(user) applications”. They communicate with the services provided by the platform, referred to as “services”. The term “peer” is used to refer to a more generic entity, which may be either a user application or a service.

This page describes the general IPC framework, for implementations in different programming languages and the associated APIs, see the respecitve page

Functional description

Basics

The use of the IPC framework always starts by initializing an instance of the framework, and it ends by destroying the instance. All communication with other peers is performed in sessions.

When sending messages, they must be initialized and filled with data before being sent. To be able to receive messages, a pre-created buffer must be available.

The typical message handling flow looks this:

start

:Initialize IPC;

repeat
fork
:Set up buffer;
:Init message;
:Set parameters;
:Send;

fork again
:Set up buffer;
:Receive;
:Check errors;
:Read parameters;

end fork
repeat while (app done) is (no)
->yes;

:Destroy IPC;
end

Initialization

The steps required to initialize the IPC framework is language dependent. See the respecitve language implementation page for examples on how to setup the IPC framework.

Messages

All communication in the IPC framework is done in the form of messages. Each message is of a specific message type which in turn belongs to a message class.

A message can contain one or more parameters, whose type is defined in Data types. The representation of a message in the SDK is defined in each language implementation page.

Message classes

The message class is identified by the suffix of the message type name and indicates its behavior. E.g. foo_ind is an Indication, which means that no response message will be sent by the receiver.

Class	Suffix	Description	Direction
Indication	ind	Message with no response.	service -> application
Request no response	req_norsp	Message with no response.	application -> service
Request	req	Message that expects a corresponding response.	application -> service
Response	rsp	Message in response to a request.	service -> application

Sessions

To keep track of peer state and restarts, the IPC framework has a session concept. Before doing any other communication with a peer, the application has to open a communication session.

To open a session, the application sends ipc_open_session_req. After the session is successfully set up (given by the result in ipc_open_session_rsp) the application can start communicating with the peer.

To close a session, the application sends ipc_close_session_req_norsp. The session is immediately closed.

An application shall assume that state in the peer is lost when a session is closed (This might not be instant).

Subscriptions

The IPC framework provides a subscription mechanism. It’s a generic method of subscribing to needed messages, and receiving all published messages for a given subscription.

Typically the user application subscribes to IPC messages in its initialization phase.

The application should check the subscription response to make sure that a subscription is established. When data is not needed anymore, the application should unsubscribe.

Subscriptions are automatically removed if the client is not reachable by the service, but it might not happen immediately.

Class	Suffix	Description
Publish Indication	publish_ind	New data published from the service.
Subscribe Request	subscribe_req	Subscribe to receive data on new events/periodically.
Subscribe Response	subscribe_rsp	Response to the subscribe request. Indicates if the request was successful.
Unsubscribe Request	unsubscribe_req_norsp	Unsubscribe from data updates.

Send error and Delivery guarantees

IPC message delivery is not guaranteed, neither lack of delivery or out of order delivery is considered an error in the system, however the IPC framework will do best effort to deliver messages or give an error indication.

If a message can not be delivered and the framework detects it, the application receives an ipc_send_error_ind message. The send error indicates the type of the undeliverable message, in msg_type, and a reason. The cause for send errors is typically that the receiver is not running or a session problem, but could also be due to the receiver’s inbox being full.

When watching for incoming messages, the application should make sure to watch for ipc_send_error_ind.

Data types

IPC messages can contain multiple different types of data.

Primitive Types

type int8 int16 int32 int64 uint8 uint16 uint32 uint64: Standard integer type, signed and unsigned variants with different bitlength

type bool: Boolean type, representing a true or false value

type string: Standard string. Strings are of a dynamic length, unless an explicit array length is specified in which case it is a fixed length string.

Enumerations

Enumerations are values that can take one of a few pre-determined values, called enumerators. The enumeration specification lists the names as well as the integer values they correspond to.

Only enumerators (or their respecitve) value is valid, even if an Implementation of the IPC framework in some language might allow other values to be sent.

Structs

Messages can contain internal structs, for organization or reuse reasons. The structs themselves can contain the same type of members as a message.

Arrays

Arrays are indicated by a [] suffix in the message parameter specification, possibly with a number inside the square brackets. If a number is included, the array is a static array where the number of elements is specified by the number. If no number is given the array is a dynamic array that can contain a variable number of entires.

Each element in the array has the base type, listed before the [] suffix.

The IPC framework currently support arrays of primitive types and enums, but not of structs. Dynamic arrays of strings is not supported.