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).|
#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 ));
- 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.
- The permissions for the channel. For more information, see “Access permissions” in the documentation for stat().
- The size, in bytes, of each buffer used to store messages.
- The maximum number of buffers to allocate, or 0 if you don't want the function to allocate any buffers.
- 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.
- 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.
Use the -l asyncmsg option to qcc to link against this library.
The asyncmsg_channel_create() function creates an asynchronous message channel.
If the recvbuf_callback argument isn't NULL, the asynchronous-messaging library calls this function when you call:
- 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.
- 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.
The channel ID of the newly created channel, or -1 if an error has occurred (errno is set).
- All kernel channel objects are in use.
- Attach to a synchronous message channel.
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