NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | RETURN VALUE | ERRORS | RESTRICTIONS | ATTRIBUTES | SEE ALSO
#include <ipc/chIpc.h>int svMsgHandler(KnCap * act, int portli, KnMsgHdl handler, unsigned int stacksize, void * cookie);
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 svMsgHandler() function connects a handler to the arrival of messages on the port whose local identifier is portli in the actor whose capability is given by act . If act is K_MYACTOR , the current actor is used.
If handler is NULL, svMsgHandler() disconnects the handler connected previously.
The message handler is called each time a message is posted to the port. If messages are queued behind the port at the time the handler is connected, the handler is invoked for these messages.
The cookie argument is user-defined and is passed as the last argument to the handler. This allows the application to identify the handler easily when multiple ports are using the same handler.
When a message handler has been connected for a given port, ipcReceive(2K) calls on that port are refused ( ipcReceive() returns the K_EINVAL error code).
A port to which a message handler is connected may not be migrated (see portMigrate(2K) ).
The stack size required by the handler execution is defined by stacksize . In the current version, this argument is ignored. The system only insures that, when the handler is called, the system stack of the thread is a constant number of free bytes (defined at microkernel generation time) .
The handler is a pointer to a function whose arguments are the following:
int handler (request, src, dest, port, reply, cookie) KnMsgDesc* request ; KnUniqueId* src ; KnIpcDest* dest ; int port ; KnMsgDesc* reply ; void* cookie ; |
The request message descriptor describes the message to be handled (the KnMsgDesc structure is described in ipcSend(2K) ). The seqNum member of this structure represents the count of messages that have been received behind the port up to and including the message being handled (see also ipcReceive(2K) ). If the K_USERBODY or K_USERANNEX flag is present in the flags field of this descriptor, the corresponding data must be obtained using svCopyIn(2K) . Otherwise, the data may be read directly from the system address space.
The src pointer points to the UI describing the port from which the message has been sent.
The dest pointer points to the destination to which the message has been sent.
The port pointer is the local identifier of the port to which the handler is attached.
The location for a reply to the message may already have been allocated by the system or the sender. In this case, reply is a non NULL pointer to a message descriptor. Otherwise, reply is NULL . Note that the K_USERBODY and K_USERANNEX flags may be present in the reply message descriptor. In this case, the handler should use svCopyOut(2K) to update the reply message annex or body.
To have the system update the handler's reply data, or if reply is NULL , the handler can invoke the svMsgHdlReply() function. This function updates the reply data according to the msg message description. This function does not cause the addressee of the reply to receive it. The operation is delayed until the handler exits. The value passed to svMsgHandler() is defined by cookie .
The handler is executed by a system thread. This thread is a handler thread , a restricted form of a thread. The handler thread is temporarily attached to the actor that owns the port to which the message handler has been attached. Any reference to the current actor ( K_MYACTOR ) within the context of the handler thread execution is interpreted as a reference to the actor which owns the port to which the handler is connected.
The handler thread possesses a local identifier within its actor and may be obtained using threadSelf(2K) (2K). However, this thread is a restricted type of thread. Its local identifier may not be used for external management of the thread ( threadAbort(2K) threadSuspend(2K) threadResume(2K) threadContext(2K) threadTimes(2K) ). Applying these services to a handler thread results in the K_EINVAL error code being returned (invalid thread)..
The only way to delete the handler thread is to return from the handler.
When entering the handler, the handler thread has no current message. This means that ipcSave(2K) , ipcReply(2K) and ipcSysInfo(2K) return the K_EINVAL error code. However, the handler thread can perform ipcReceive(2K) and get a current message. If the handler returns while the handler thread has a current message, this message is canceled.
When the handler exits, the handler return value defines the format of the reply to the sender's request, as follows:
If svMsgHdlReply() was not called during handler execution, and the handler returns a positive or NULL value, the message body and annex are updated by the handler (using the reply argument). In this case, the handler returns the message body size. If the handler return value is a negative error code, the caller does not receive a reply. However, if the message was sent using ipcCall(2K) , the negative error code returned by the handler is returned to the caller.
If svMsgHdlReply() was called during handler execution, the handler return code is ignored and the caller receives zero if the call was successful or a negative error code.
Both svMsgHandler() and svMsgHdlReply() are restricted to supervisor threads. The handler code must be located in the system address space.
On successful completion, a value of 0 is returned. Otherwise, a negative error code is returned.
( svMsgHandler() ) actorcap is an inconsistent actor capability, or portli is not a valid port identifier within the actor whose capability is given by actorcap . ( svMsgHdlReply() ) the current thread is not a handler thread.
( svMsgHandler() only) actorcap does not specify a reachable actor.
Some of the data provided are outside the current actor's address space.
Currently, if a handler processes an asynchronous message ( ipcSend(2K) ) or a message sent remotely, the invocation of svMsgHdlReply() sends the reply to the caller, instead of preparing it and delaying it until the handler returns.
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 | RESTRICTIONS | ATTRIBUTES | SEE ALSO