asyncmsg_channel_create()

Create an asynchronous message channel


Caution: Asynchronous messaging is an experimental feature; for information about the use of experimental software, see the Commercial Software License Agreement (CSLA) or Partner Software License Agreement (PSLA) in the Licensing area of our website, http://www.qnx.com/legal/licensing/.


Note: Asynchronous messaging doesn't work with Transparent Distributed Processing (i.e., it doesn't work across Qnet).

The prototypes for this function and the callback changed in QNX Neutrino 6.4.1 to include the recvbuf_callback_handle and handle arguments respectively.


Synopsis:

#include <sys/neutrino.h>
#include <sys/asyncmsg.h>

int asyncmsg_channel_create (
       unsigned flags,
       mode_t mode,
       size_t buffer_size,
       unsigned max_num_buffer,
       const struct sigevent *ev,
       int (*recvbuf_callback) (
              size_t bufsize,
              unsigned num_bufs,
              void *bufs[],
              int flags,
              void *handle ),
       void *recvbuf_callback_handle );

Arguments:

flags
Flags that specify the attributes of the channel:

This function automatically sets _NTO_CHF_ASYNC.

mode
The permissions for the channel. For more information, see access permissions in the description of the st_mode member of the stat structure in the entry for stat().
buffer_size
The size, in bytes, of each buffer used to store messages.
max_num_buffer
The maximum number of buffers to allocate, or 0 if you don't want the function to allocate any buffers.
ev
NULL, or a pointer to a sigevent structure that specifies an event that you want to be delivered when a message becomes available to be received on a previously empty queue.
recvbuf_callback
NULL, or a pointer to a callback function that the library can use to allocate a buffer for an incoming message, or to free buffers when the channel is destroyed. If the callback is NULL, the library uses malloc() and free() instead. For more information, see Callback function,” below.
recvbuf_callback_handle
NULL, or a pointer to arbitrary data that you want to pass to the callback function.

Library:

libasyncmsg

Use the -l asyncmsg option to qcc to link against this library.

Description:

The asyncmsg_channel_create() function creates an asynchronous message channel.

Callback function

If the recvbuf_callback argument isn't NULL, the asynchronous-messaging library calls this function when you call:

asyncmsg_get()
The callback is invoked once for each buffer being received, and the flags argument is set to ASYNCMSG_RECVBUF_ALLOC. The callback is expected to allocate space for the message, put a pointer to the buffer in the bufs table, and then return 1 if you want the library to receive another buffer, or 0 if you want it to stop.
asyncmsg_channel_destroy()
In this case, the callback is invoked one or more times to free the outstanding receive buffers; the flags argument is set to ASYNCMSG_RECVBUF_FREE, and the return value is ignored.

The arguments to the callback are as follows:

size_t bufsize
The buffer size for the message currently being received, including the headers.
unsigned num_bufs
void* bufs[]
A table of pointers to the receive buffers. The number of buffers is given by num_bufs.
int flags
ASYNCMSG_RECVBUF_ALLOC when asyncmsg_get() invokes the callback, and ASYNCMSG_RECVBUF_FREE when asyncmsg_channel_destroy() invokes it.
handle
NULL, or a pointer to arbitrary data (specified with the recvbuf_callback_handle argument to asyncmsg_channel_create()) that you want to pass to the callback function.

Returns:

The channel ID of the newly created channel, or -1 if an error has occurred (errno is set).

Errors:

EAGAIN
All kernel channel objects are in use.
EINVAL
An attempt was made to attach to a synchronous message channel.

Classification:

QNX Neutrino

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

See also:

asyncmsg_channel_destroy(), asyncmsg_connect_attach(), asyncmsg_connect_attr(), asyncmsg_connect_detach(), asyncmsg_flush(), asyncmsg_free(), asyncmsg_get(), asyncmsg_malloc(), asyncmsg_put(), asyncmsg_putv(), ChannelCreate(), sigevent

Asynchronous Messaging technote