dispatch_block()

Arguments:

ctp

A pointer to a dispatch_context_t structure that defines the dispatch context.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The dispatch_block() function blocks by calling MsgReceive() while waiting for an event that's registered using one of the attach functions, message_attach(), pulse_attach(), resmgr_attach(), or select_attach(). This function is part of the dispatch layer of a resource manager. For more information, see Layers in a resource manager in the Bones of a Resource Manager chapter of Writing a Resource Manager.

Returns:

A dispatch context that was passed in, or NULL if an error occurs (errno is set).

If NULL is returned (for example, because a signal interrupted MsgReceive()), the old context pointer is still valid. Typically, a resource manager targets signals to a thread that is dedicated to handling signals. However, if a signal can be targeted to the thread doing dispatch_block(), you could use the following code:

dispatch_context_t *ctp;

ctp = dispatch_context_alloc( … );
while (1) {
  if ( dispatch_block( ctp ) == NULL ) {
       /* handle the error condition */
       …
       } else {
         dispatch_handler(ctp);
      }
}

Errors:

EFAULT

A fault occurred when the kernel tried to access the buffers.

EINTR

The call was interrupted by a signal.

EINVAL

Invalid arguments passed to dispatch_block().

See also the error constants returned by MsgReceive().

Examples:

#include <sys/dispatch.h>

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

   …

   for(;;) {
     if( dispatch_block( ctp ) ) {
       dispatch_handler( ctp );
     }
   }
}

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

Classification:

QNX OS