asyncmsg_get()

Receive an asynchronous message


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

Synopsis:

#include <sys/asyncmsg.h>

struct _asyncmsg_get_header *asyncmsg_get( int chid );

Arguments:

chid
The channel ID.

Library:

libasyncmsg

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

Description:

The asyncmsg_get() function receives up to five asynchronous messages from the channel identified by the chid argument. In order to receive more messages, you must call this function in a loop until the function returns NULL and sets errno to EAGAIN to signify that you've drained the queue of messages.


Note: Threads that receive asynchronous messages don't inherit the sender's priority.

If you provided a callback function when you called asyncmsg_channel_create(), asyncmsg_get() invokes the callback to allocate space for the message; otherwise asyncmsg_get() invokes malloc().

_asyncmsg_get_header structure

The asyncmsg_get() function stores each asynchronous message in an _asyncmsg_get_header structure:

struct _asyncmsg_get_header {
    struct _msg_info info;
    int err;
    iov_t *iov;
    int parts;
    struct _asyncmsg_get_header *next;
    unsigned reserve[2];
};

The members include:

info
A _msg_info structure, just as for synchronous messages.
err
The error status of this message.
iov
A pointer to the IOV (Input/Output Vector) for the message body.
parts
The size of the iov array.
next
A pointer to the next message returned by asyncmsg_get().

Returns:

A pointer to a linked list of _asyncmsg_get_header structures containing the messages received, or NULL if an error occurred (errno is set).


Note: You should free this list of headers when you're finished with them.

Errors:

EBADF
The channel specified by chid doesn't exist.
EFAULT
A fault occurred when the kernel tried to access the buffers provided.
EMSGSIZE
The buffer provided isn't big enough to hold the received message.
EAGAIN
No message is available at this time.

Classification:

QNX Neutrino

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

See also:

asyncmsg_channel_create(), asyncmsg_channel_destroy(), asyncmsg_connect_attach(), asyncmsg_connect_attr(), asyncmsg_connect_detach(), asyncmsg_flush(), asyncmsg_free(), asyncmsg_malloc(), asyncmsg_put(), asyncmsg_putv()

Asynchronous Messaging technote