MsgSendPulsePtr(), MsgSendPulsePtr_r()

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 message_connect().

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(). A priority of 0 (which is reserved for the idle thread) is changed to 1.

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 OS 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 pointer that you want to use as the pulse value. The data that the pointer references isn't copied; the actual pointer value is transmitted.

Library:

libc

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

Description:

The MsgSendPulsePtr() and MsgSendPulsePtr_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 use MsgSendPulsePtr() to wake up another thread in the same process and provide it with the address of an object to operate on. It's possible to use this function between processes, but as the pointer will be invalid in the receiving process, it might be clearer to send an integer value by using MsgSendPulse(). If you want to copy the data instead of a pointer to it, use MsgSend().

You can send a pulse to a process if:

• the sending process's effective user ID matches the real, effective, and saved user IDs of the receiving process

  Or:

• the calling process has the PROCMGR_AID_CONNECTION ability enabled. For more information, see procmgr_ability().

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.

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*().

Blocking states

None.

Returns:

The only difference between the MsgSendPulsePtr() and MsgSendPulsePtr_r() functions is the way they indicate errors:

MsgSendPulsePtr()

If an error occurs, this function returns -1 and sets errno. Any other value returned indicates success.

MsgSendPulsePtr_r()

If successful, this function returns EOK. This function does NOT set errno, even on success. If an error occurs, it may return any value from the Errors section.

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.

EINVAL

The specified priority is invalid (e.g., greater than 255).

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 OS

Caveats:

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