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.

The dispatch_block() function blocks while waiting for an event (e.g. message or signal) that's registered using one of the attach functions, message_attach(), pulse_attach(), resmgr_attach(), or select_attach(). (The sigwait_attach() function isn't currently implemented.)

If the type of blocking is:	dispatch_block() does a:
message (resmgr, message, select)	MsgReceive()
signal	SignalWaitinfo()

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's passed in by dispatch_context_alloc(). 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.

In the case of a timeout, a valid ctp is returned, but either the ctp->message_context.rcvid or ctp->sigwait_context.signo is set to -1.

If a non-NULL context pointer is returned, it could be different from the one passed in, as it's possible for the ctp to be reallocated to a larger size. In this case, the old ctp is no longer valid. However, if NULL is returned (for example, because a signal interrupted the MsgReceive()), the old context pointer is still valid. Typically, a resource manager would target signals to a thread dedicated to handling signals. However, if a signal can be targeted to the thread doing dispatch_block(), you could use the following code in this situation:

dispatch_context_t   *ctp, *new_ctp;

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

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 in MsgReceive() and SignalWaitinfo().

Examples:

#include <sys/dispatch.h>

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

   …

   for(;;) {
     if( ctp = 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