MsgReceivePulse(), MsgReceivePulse_r()

Receive a pulse on a channel

Synopsis:

#include <sys/neutrino.h>

int MsgReceivePulse( int chid,
                     void * pulse,
                     int bytes,
                     struct _msg_info * info );

int MsgReceivePulse_r( int chid,
                       void * pulse,
                       int bytes,
                       struct _msg_info * info );

Description:

The MsgReceivePulse() and MsgReceivePulse_r() functions are identical except in the way they indicate errors. See the Returns section for details.

These kernel calls wait for a pulse to arrive on the channel identified by chid. The channel chid was established by calling ChannelCreate(). The receive data is placed in the buffer pointed to by pulse. The size of the buffer is given by bytes.

The number of bytes transferred is the minimum of that specified by both the sender and the receiver. The received data won't be allowed to overflow the receive buffer area provided.

The pulse buffer must be big enough to contain a pulse. If it isn't, -1 is returned and errno is set to EFAULT.

If a pulse is waiting on the channel when MsgReceivePulse() is called, the calling thread won'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.

Since the info parameter isn't updated, you'll typically pass NULL.

The MsgReceivePulse() function returns a value that's referred to as a rcvid (receive identifier). It can take on the following values:

Value	Description
-1	An error occurred.
0	A pulse was received. Unlike a message, a pulse shouldn't be replied to using MsgReply()*. When a pulse is received, the kernel space allocated to hold it is immediately released.

When a pulse is received, pulse contains a pulse message of type struct _pulse, that contains at least the following members:

Member	Description
`uint16_t` type	0
`uint16_t` subtype	0
`int8_t` code	A pulse code. System pulses are defined in `<sys/neutrino.h>`
`union sigval` value	Information relevant to the code
`int32_t` scoid	Server connection ID

Blocking states

State	Meaning
STATE_RECEIVE	There's no pulse waiting.

Returns:

The only difference between the MsgReceivePulse() and MsgReceivePulse_r() functions is the way they indicate errors:

MsgReceivePulse(): A rcvid (receive ID). If an error occurs, -1 is returned and errno is set.
MsgReceivePulse_r(): A rcvid (receive ID). This function does NOT set errno. If an error occurs, the negative of a value from the Errors section is returned.

Errors:

EFAULT: A fault occurred when the kernel tried to access the buffers provided. Because QNX accesses the sender's buffers only when MsgReceivePulse() is called, a fault could occur in the sender if the sender's buffers are invalid. If a fault occurs when accessing the sender buffers (only) they'll receive an EFAULT and MsgReceivePulse() won't unblock.
EINTR: The call was interrupted by a signal.
ESRCH: The channel indicated by chid doesn't exist.
ETIMEDOUT: A kernel timeout unblocked the call. See TimerTimeout().

Classification:

QNX 6

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