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).

Errors can occur when the blocking kernel call returns with an error, for example, due to the delivery of a signal.

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().

ENOMEM

Insufficient memory to allocate internal data structures.

See also the error constants returned by MsgReceive() and SignalWaitinfo().

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 Neutrino