dispatch_context_alloc()

Return a dispatch context

Synopsis:

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

dispatch_context_t * dispatch_context_alloc
                   ( dispatch_t * dpp );

Arguments:

dpp
A dispatch handle created by a successful call to dispatch_create().

Library:

libc

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

Description:

The dispatch_context_alloc() function returns a dispatch context pointer. The function is passed in the handle dpp from dispatch_create(). The dispatch context is used by dispatch to do its work. It's passed as an argument to dispatch_block() and dispatch_handler().

Note:
  • The dispatch_context_alloc() function fails if you haven't attached any events to dispatch yet (i.e., you didn't call message_attach(), pulse_attach(), resmgr_attach(), or select_attach()). The dispatch library can't allocate a proper context until it knows what kind of events you want to block.
  • Once you've called dispatch_context_alloc(), don't call message_attach() or resmgr_attach() specifying a larger maximum message size or a larger number of message parts for the same dispatch handle. In QNX Neutrino 7.0 or later, these functions indicate an error of EINVAL if this happens.

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 pointer to a dispatch context, or NULL if an error occurs (errno is set).

Errors:

EINVAL
No events were attached.
ENOMEM
Insufficient memory to allocate context.

Examples:

#include <sys/dispatch.h>
#include <stdio.h>    
#include <stdlib.h>   
    
int main( int argc, char **argv ) {
   dispatch_t           *dpp;
   dispatch_context_t   *ctp;

   if( ( dpp = dispatch_create() ) == NULL ) {
     fprintf( stderr, "%s: Unable to allocate \
              dispatch handle.\n",argv[0] );
     return EXIT_FAILURE;
   }

   ...

   ctp = dispatch_context_alloc( dpp );

   ...

   return EXIT_SUCCESS;
}

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

Classification:

QNX Neutrino

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