ChorusOS 5.0 Application Developer's Guide

ChorusOS IPC

The IPC feature enables threads to communicate and synchronize when they do not share memory, for example, when they do not run on the same node. Communications rely on the exchange of messages through ports.

The IPC feature includes a number of APIs. These are listed in the following table.

Table 11-1 IPC APIs


API	Purpose
`actorPi()`	Modify the PI of an actor
`portCreate()`	Create a port
`portDeclare()`	Declare a port
`portDelete()`	Destroy a port
`portDisable()`	Disable a port
`portEnable()`	Enable a port
`portGetSeqNum()`	Get a port sequence number
`portLi()`	Acquire the LI of a port
`portMigrate()`	Migrate a port
`portPi()`	Modify the PI of a port
`portUi()`	Acquire the UI of a port
`grpAllocate()`	Allocate a group name
`grpPortInsert()`	Insert a port into a group
`grpPortRemove()`	Remove a port from a group
`ipcCall()`	Send synchronously
`ipcGetData()`	Get the current message body
`ipcReceive()`	Receive a message
`ipcReply()`	Reply to the current message
`ipcRestore()`	Restore a message as the current message
`ipcSave()`	Save the current message
`ipcSend()`	Send asynchronously
`ipcSysInfo()`	Get information about the current message
`ipcTarget()`	Construct an address
`svMsgHandler()`	Connect a message handler
`svMsgHdlReply()`	Prepare a reply to a handled message

How IPC Works

The IPC feature enables threads to exchange messages in either asynchronous or demand/response mode. The demand/response mode is also known as a Remote Procedure Call (RPC).

In asynchronous mode, the sender of an asynchronous message is only blocked during the time of local processing of the message. The system does not guarantee that the message has been deposited at the destination location.

In RPC mode, the RPC protocol enables the construction of client-server applications using a demand/response protocol for the management of transactions. The client is blocked until a response is returned from the server, or a user-defined (optional) timeout occurs. RPC ensures at-most-once semantics for the delivery of the request. It also ensures that the response received by a client originates from the server. The response received by the client must also correspond to the request (and not to a former request to which the response might have been lost).

RPC also enables a client to be unblocked (which will generate an error) if the server is unreachable or has crashed before emitting a response.

Finally, the RPC protocol supports abort propagation. When a thread that is waiting for an RPC reply is aborted, the event will be propagated to the thread which is currently servicing the client request.

A thread that attempts to receive a message on a port is blocked until the new message is received or a until user-defined (optional) time-out occurs.

A thread can attempt to receive a message on several ports at a time. Among the set of ports attached to an actor, a subset of enabled ports is defined. A thread can also attempt to receive a message sent to any of the enabled ports in its actors.

Ports attached to an actor can be dynamically enabled or disabled. When a port is enabled, it receives a priority value. If several of the enabled ports hold a message when a thread attempts to receive the message on the enabled set of ports, the port with the highest priority will be selected.

An actor's default port is not automatically enabled. If a port has not been enabled, it is automatically disabled. This does not mean that the port cannot be used to send or to receive messages. It means that the port cannot be used in multiple port receive requests because the default value is disabled.

Message Handlers

The conventional way for an actor to receive messages delivered to its ports is to have threads explicitly express receive requests. An alternative to this method is the use of message handlers. Instead of explicitly creating threads, an actor can attach a handler (a routine in its address space) to the port. When a message is delivered to the port, the handler is executed within the context of a thread provided by the microkernel.

Message handlers and explicit receive requests are exclusive. When a message handler has been attached to a port, any attempt by a thread to receive a message on that port will return an error.

The use of message handlers is restricted to supervisor actors. Message handlers enable significant optimization of the RPC protocol when both client and server reside on the same site, thereby avoiding thread context switches and memory copies. From the point of view of the microkernel, the client thread is used to run the handler and copying of the message into microkernel buffers is avoided.

The method in which messages are consumed (threads or handlers) is completely transparent to the client (the sender of the message). The strategy is selected on the server only.

IPC_REMOTE

The IPC_REMOTE feature enables support for communication among multiple sites in a network, using a location-transparent communication feature. Without this feature, IPC services may be used only within a single site.