MsgSendPulse(), MsgSendPulse_r()

Send a pulse to a process

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 );

Arguments:

coid
The ID of the connection to the channel to send the pulse on, which you've established by calling ConnectAttach() or one of its cover functions, such as name_open() or open().
priority
The priority to use for the pulse, or -1 to use the priority of the calling thread. The priority must be within the range of valid priorities, which you can determine by calling sched_get_priority_min() and sched_get_priority_max().
code
The 8-bit pulse code.

Although code can be any 8-bit signed value, you should avoid code values less than zero, in order to avoid conflict with pulse codes generated by the kernel or a QNX Neutrino manager. These codes all start with _PULSE_CODE_ and are defined in <sys/neutrino.h>; for more information, see the documentation for the _pulse structure. A safe range of pulse values is _PULSE_CODE_MINAVAIL through _PULSE_CODE_MAXAVAIL.

value
The 32-bit pulse value.

Library:

libc

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

Description:

The MsgSendPulse() and MsgSendPulse_r() kernel calls send a short, nonblocking message to a process's channel via the connection identified by coid.

These functions are identical except in the way they indicate errors. See the Returns section for details.

You can send a pulse to a process if:

You can use MsgSendPulse() for many purposes; however, due to the small payload of data, you shouldn't use it 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 compresses the pulses by storing an 8-bit count with an already queued pulse.

Note:
  • In order to send a pulse to a channel that was created by a different process with a different user ID, your process must have the PROCMGR_AID_CONNECTION ability enabled. For more information, see procmgr_ability().
  • The receiving thread's effective priority might change when you send a pulse to it. For more information, see "Priority inheritance and messages" in the Interprocess Communication (IPC) chapter of the System Architecture guide.

When you receive a pulse via 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*().

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

Blocking states

None for the local case. In the network case:

STATE_NET_SEND or STATE_NET_REPLY
The calling thread is blocked while the pulse is delivered to the local Qnet manager, which transmits it to the remote Qnet. The remote Qnet does a MsgSendPulse() on behalf of the caller, and the return value is transmitted back, at which point the calling thread is unblocked.

Native networking

You can use MsgSendPulse() 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.
EHOSTDOWN
The host is down (e.g., a send across Qnet failed).
EHOSTUNREACH
Unable to communicate with remote node (e.g., across Qnet).
EINVAL
The specified priority is invalid (e.g., 0).
EPERM
The calling process doesn't have the required permission; see procmgr_ability().
ESRVRFAULT
A fault occurred in the server's address space when the kernel tried to write the pulse message to the server's receive message buffer.

Classification:

QNX Neutrino

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

Caveats:

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