dispatch_create

Allocate a dispatch structure, specifying a channel ID

Synopsis:

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

dispatch_t *dispatch_create_channel( int chid,
                                     unsigned flags );

Arguments:

chid

The ID of the channel to use for the dispatch layer.

flags

0, or the following:

DISPATCH_FLAG_CHANNEL_COIDDEATH — (QNX Neutrino 7.0 or later) set this flag if you've created the channel with NTO_CHF_COID_DISCONNECT and intend to use pulse_attach() to attach a handler to _PULSE_CODE_COIDDEATH pulses.

Library:

libc

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

Description:

The dispatch_create_channel() function allocates and initializes a dispatch structure, and returns a handle to this structure. This function is similar to dispatch_create(), but lets you specify a channel. This is useful if you want to control the channel for name_attach() or resmgr_attach(). For example, if you wanted two or more names to the same channel, or if you wanted non-default channel flags.

After you've called this function, you need to call one or more of the following functions to attach handlers for the things you want the dispatch layer to deal with:

Then you call dispatch_context_alloc() to allocate the context for dispatch_block() and dispatch_handler().

Note: 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 structure. In QNX Neutrino 7.0 or later, these functions indicate an error of EINVAL if this happens.

If the dispatch structure is for use in a resource manager, meaning you will later call resmgr_attach() with the associated dispatch handle, then at least the flags _NTO_CHF_UNBLOCK and _NTO_CHF_DISCONNECT should be set for the supplied channel to ensure proper resource manager behavior.

If you wish, you can do a resmgr_attach() with a NULL path. This has the effect of initializing the dispatch structure to receive messages, among other things.

Note: In order to create a public channel (i.e., without _NTO_CHF_PRIVATE set), your process must have the PROCMGR_AID_PUBLIC_CHANNEL ability enabled. For more information, see procmgr_ability().

The dispatch_create_channel() function is part of the dispatch layer of a resource manager. For more information, see “Layers in a resource manager” in the “The Bones of a Resource Manager” chapter of Writing a Resource Manager.

Returns:

A handle to a dispatch structure, or NULL if an error occurred (errno is set). The dispatch_t structure is an opaque data type; you can't access its contents directly.

Errors:

EBUSY: (QNX Neutrino 7.0 or later) You specified DISPATCH_FLAG_CHANNEL_COIDDEATH in the flags, and a dispatch framework with that flag already exists.
EINVAL: (QNX Neutrino 7.0 or later) The flags argument is invalid.
ENOMEM: Insufficient memory to allocate context.

Classification:

QNX Neutrino

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