MsgSendPulse(), MsgSendPulse_r()

Send a pulse to a channel

Synopsis:

#include <sys/neutrino.h>

int MsgSendPulse ( int coid,
                   int priority,
                   int code,
                   int value );

int MsgSendPulse_r ( int coid,
                     int priority,
                     int code,
                     int value );

Library:

libc

Description:

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

These kernel calls send a short nonblocking message to a process's channel identified by coid. This connection coid is established by calling ConnectAttach(). The pulse data are passed as arguments and consist of an 8-bit code and a 32-bit value. The priority argument must be within the range of valid priorities, that you can discover using sched_get_priority_min() and sched_get_priority_max().

You can send a pulse to any process in your process group if you have the appropriate permissions to drop a signal on another process (permission checking is identical to the checking used by the kill() function).

The MsgSendPulse() function can be used for many purposes; however, due to the small payload of data it shouldn't be used for transmitting large amounts of bulk data by sending a great number of pulses. Pulses are queued for the receiving process in the system using a dynamic pool of memory objects. If pulses are generated faster than they can be consumed by the receiver, then over a period of time the system queue for the pulses could reach a low memory condition. If there's no memory available for the pulse to be queued in the system, the kernel fails the pulse request with an error of EAGAIN. If the priority, code and value don't change, the kernel performs pulse compression by storing an 8-bit count with an already queued pulse.

When a pulse is received by the MsgReceive*() kernel call, the rcvid returned is zero. This indicates to the receiver that it's a pulse and unlike a message, shouldn't be replied to using MsgReply*().

Although code can be any 8-bit signed value, programs should avoid code values less than zero in order to avoid conflict with kernel or QNX manager generated pulse codes. These codes all start with _PULSE_CODE_ and are defined in <sys/neutrino.h>. A safe range of pulse values is _PULSE_CODE_MINAVAIL to _PULSE_CODE_MAXAVAIL.

In a client/server designs MsgDeliverEvent() is typically used in the server, and MsgSendPulse() in the client.

Blocking states

None. In the network case, lower priority threads may run.

Native networking

Currently, the MsgSendPulse() function can't be used to send pulses across the network.

Returns:

The only difference between the MsgSendPulse() and MsgSendPulse_r() functions is the way they indicate errors:

MsgSendPulse()  

If an error occurs, -1 is returned and errno is set. Any other value returned indicates success.  

MsgSendPulse_r()  

EOK is returned on success. This function does NOT set errno.    If an error occurs, any value in the Errors section may be returned.

Errors:

EAGAIN

The kernel had insufficient resources to enqueue the pulse.

EBADF

The connection indicated by coid is no longer connected to a channel or the connection indicated by coid doesn't exist. The channel may have been terminated by the server or the network manager if it failed to respond to multiple polls.

EFAULT

A fault occurred when the kernel tried to access the buffers provided.

EPERM

This process doesn't have sufficient permission to send a pulse to the connection, coid.

ESRVRFAULT

A fault occurred in the server's address space when it tried to write the pulse message to the server's receive message buffer.

Classification:

QNX 6

Caveats:

If the server faults on delivery, the pulse is either lost or an error is returned.

See also:

MsgDeliverEvent(), MsgReceive(), MsgReceivev(), sched_get_priority_min(), sched_get_priority_max()