dispatch_handler()

Handle events received by dispatch_block

Synopsis:

#include <sys/dispatch.h>

int dispatch_handler( dispatch_context_t * ctp );

Library:

libc

Description:

The dispatch_handler() function handles events received by dispatch_block(). Depending on the blocking type, dispatch_handler() does one of the following:

Calls the message_* subsystem. A search is made (based upon the message type or pulse code) for a matching function (that was attached with message_attach() or pulse_attach()). If a match is found, the attached function is called.
If the message type is in the range handled by the resource manager (e.g. I/O messages) and pathnames were attached using resmgr_attach(), then the resmgr_* subsystem is called and handles the resource manager messages.
If a pulse is received, it may be dispatched to the resmgr_* subsystem if it's one of the codes (unblock and disconnect pulses) handled by the resource manager. If a select_attach() was done and the pulse matches the one used by select_attach(), then the select_* subsystem is called and dispatches that event.
If a message is received, and no matching handler is found for that message type, MsgError() returns ENOSYS to the sender.
If a SignalWaitinfo() blocking type is used, then a search is made based upon the signal number for a matching function attached by the program (using the sigwait_attach() function, not currently implemented). If a match is found, that function is called.

Returns:

0

Success.

-1

This may occur for a number of reasons:

the message was a _PULSE_CODE_THREADDEATH pulse message (see ChannelCreate()) for which there's no default handler function.
the message length was less than 2 bytes. A 2 byte message type is required at the beginning of the message so that a handler function can be found or identified.
the message wasn't in native endian format and there were no handler functions that specified MSG_FLAG_CROSS_ENDIAN on this range even though a handler was registered for it using message_attach(). The MSG_FLAG_CROSS_ENDIAN flag wasn't given to message_attach().
a handler was found for the message but the handler determined that there was a problem.

In any case, if the message wasn't a pulse, then the client will be replied to with an appropriate errno.

Examples:

#include <stdlib.h>
#include <sys/dispatch.h>

int main( int argc, char **argv ) {
   dispatch_context_t   *ctp;

   ...

   for(;;) {
     if( ctp = dispatch_block( ctp ) ) {
       dispatch_handler( ctp );
     }
   }
   return EXIT_SUCCESS;
}

For examples using the dispatch interface, see dispatch_create(), message_attach(), resmgr_attach(), and thread_pool_create().

Classification:

QNX 6

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	No
Thread	Yes