asyncmsg_channel_create()

Create an asynchronous message channel

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/.

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:

_NTO_CHF_ASYNC_NONBLOCK — make asyncmsg_get() nonblocking when no messages are available.

This function automatically sets _NTO_CHF_ASYNC.

mode

The permissions for the channel. For more information, see “Access permissions” in the documentation 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

When the callback is invoked because you called asyncmsg_get(), this argument is 1 (the callback is called once for each buffer received).
When the callback is invoked because you called asyncmsg_channel_destroy(), this argument is the number of buffers to free.

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