dispatch_destroy()

Destroy a dispatch handle, without cleaning up the dispatch framework

Synopsis:

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

int dispatch_destroy( dispatch_t *dpp );

Arguments:

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

Library:

libc

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

Description:

The function dispatch_destroy() destroys the given dispatch handle. To do so, it frees all objects, sets the memory of the dpp data to 0, then frees this memory. It also closes the channel, even if it's one you passed to dispatch_create_channel().

CAUTION:

Before destroying a dispatch handle, you must ensure that it is no longer in use. If you destroy a handle for a dispatch framework that's still active, this will most likely crash the process.

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:

0: Success.
-1: An error occurred (errno is set).

Errors:

EINVAL: The dispatch handle, dpp, is invalid.

Examples:

#include <sys/dispatch.h>
#include <stdio.h>        
#include <stdlib.h>       

int main( int argc, char **argv ) {
   dispatch_t    *dpp;
   int           destroyed;

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

   …
    
   if ( (destroyed = dispatch_destroy ( dpp )) == -1 ) {
      fprintf ( stderr, "Dispatch wasn't destroyed, \
                bad dispatch handle %d.\n", dpp);
      return EXIT_FAILURE;
   }
   /* else dispatch was destroyed */

   …
   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