NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES | SEE ALSO
#include <ipc/chIpc.h>int ipcCall(KnMsgDesc *reqmsg, int reqsrc, KnIpcDest *reqdest, KnMsgDesc *repmsg, int delay);
The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.
See API(5FEA) for details.
IPC
The ipcCall function sends a message in transactional (RPC) mode, and blocks the caller until a reply to the request is received or the optional delay expires.
The delay field is the maximum waiting time, expressed in milliseconds. If delay has a negative value, the blocking time is unlimited.
The reqdest field defines the destination of the message, and is a pointer to a KnIpcDest structure. Its meaning is described in ipcSend(2K). Use of the K_BROADMODE addressing mode on a port group is forbidden.
The reqsrc field is a local identifier for the source port of the message. If reqsrc is K_DEFAULTPORT, the default port of the current actor is used.
The reqmsg field points to a descriptor for the request message to be sent, on condition that reqmsg points to a KnMsgDesc structure, as described in ipcSend(2K).
The repmsg field is a descriptor for the reply message to be received, as described in ipcReceive(2K). As in ipcReceive(2K), the K_ABORTABLE flag may be present in the flags field of this structure. In this case, the ipcCall is ABORTABLE. Otherwise, it is NONABORTABLE. These two different states determine the behavior of the thread when a threadAbort(2K) is applied to it. If threadAbort(2K) is applied to a NONABORTABLE ipcCall, the thread replies and stays in the ABORTED state (see threadAbort(2K)). If threadAbort(2K) is applied to an ABORTABLE ipcCall, the microkernel attempts to pass the abortion on to the thread which is processing the request messages:
If the request message is queued behind the destination port, the message is deleted and the ipcCall returns K_EABORT.
If a thread (called the server) currently is processing the request message, the server is aborted.
This propagation mechanism is recursive: in the case of nested ipcCall (2K), (the server is itself blocked in an ABORTABLE ipcCall), the abortion of the server is also passed on to its server.
Unless explicitly shown by the return of the K_EABORT error code, a client thread aborted during its ipcCall always enters the ABORTED state upon return (the abortion still has to be processed; it appears as if the abortion occurred after the ipcCall returned).
Upon return, the reply received does not become the current message for the current thread. As a consequence, ipcReply(2K), ipcSave(2K), ipcGetData(2K) and ipcSysInfo(2K) may never be applied to the reply of an ipcCall.
Upon successful completion, the size of the message body received is returned. Otherwise, a negative error code is returned. The error codes are those listed below, except when the destination port is connected to a message handler. In this case the error code is the return value of the handler function.
The thread was aborted while waiting; the request message was never delivered to its destination.
Attempt to broadcast an RPC request.
The ipcCall transaction has failed.
Some of the data provided are outside the current actor's address space.
The destination port is local and its queue is full, or the local remote-communication subsystem is saturated.
reqsrc is not a valid local port identifier.
The timeout has occurred.
The request message body is too big.
Unreachable destination. When the destination port is connected to a message handler, the error code is the return value of the handler function.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES | SEE ALSO