dispatch_block()

Block while waiting for an event

Synopsis:

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

dispatch_context_t * dispatch_block
                   ( dispatch_context_t * ctp );

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.

Note: In the case of a timeout, a valid ctp is returned, but the ctp->message_context.rcvid is set to -1.

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

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