MsgReceivePulsev(), MsgReceivePulsev

Receive a pulse on a channel

Synopsis:

#include <sys/neutrino.h>

int MsgReceivePulsev( int chid,
                      const iov_t * piov,
                      size_t parts,
                      struct _msg_info * info );

int MsgReceivePulsev_r( int chid,
                        const iov_t * piov,
                        size_t parts,
                        struct _msg_info * info );

Arguments:

chid: The ID of a channel that you established by calling ChannelCreate(), or -1 to dissociate the thread from the last channel it received on (see “Server boost” in the Interprocess Communication chapter of the System Architecture guide).
piov: An array of buffers where the function can store the received data. Only the first buffer is used; any additional ones are ignored.
Note: The first buffer of the IOV (input/output vector) must be big enough to contain a struct _pulse structure. If it isn't, you'll get an EFAULT.
parts: The number of elements in the array.
info: The function doesn't update this structure, so you typically pass NULL for this argument.

Library:

libc

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

Description:

The MsgReceivePulsev() and MsgReceivePulsev_r() kernel calls wait for a pulse to arrive on the channel identified by chid and place the received data in the first element of the array of buffers pointed to by piov. If the buffer is large enough, the number of bytes written to it is the size of a struct _pulse structure.

These functions are identical, except in the way they indicate errors; see the Returns section for details. These functions aren't very useful because the “array of buffers” is really a single element that has to be the size of a struct _pulse structure. MsgReceivePulse() has a cleaner set of arguments.

If a pulse is waiting on the channel when you call MsgReceivePulsev(), the calling thread doesn't block, and the pulse is immediately copied. If a pulse isn't waiting, the calling thread enters the RECEIVE-blocked state until a pulse arrives.

If multiple pulses are sent to a channel without a thread waiting to receive them, the pulses are queued in priority order.

When a thread receives a pulse:

The kernel space allocated to hold the pulse is immediately released.
The IOV's first buffer contains a pulse message of type struct _pulse.
The thread's effective priority might change. For more information, see “Priority inheritance and messages” in the Interprocess Communication (IPC) chapter of the System Architecture guide.

Note: Don't reply to a pulse.

Blocking states

STATE_RECEIVE: There's no pulse waiting.

Returns:

The only difference between MsgReceivePulsev() and MsgReceivePulsev_r() is the way they indicate errors:

MsgReceivePulsev(): If successful, this function returns EOK. If an error occurs, it returns -1 and sets errno.
MsgReceivePulsev_r(): If successful, this function returns EOK. If an error occurs, it may return the negative of any value from the Errors section. This function does NOT set errno, even on success.

Errors:

EFAULT: A fault occurred when the kernel tried to access the buffers provided, or the size of the first element in the receive buffer is less than the size of a struct _pulse. The pulse is lost in this case.
EINTR: The call was interrupted by a signal.
EOVERFLOW: The sum of the IOV lengths exceeds SSIZE_MAX, or the number of parts exceeds 524288.
ESRCH: The channel indicated by chid doesn't exist.
ETIMEDOUT: A kernel timeout unblocked the call. See TimerTimeout().

Classification:

QNX Neutrino

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

MsgReceivePulsev(), MsgReceivePulsev_r()