MsgPause(), MsgPause_r()

Arguments:

rcvid

The receive ID that MsgReceive*() returned when you received the message.

cookie

A value for the kernel to pass back to the resource manager with the _PULSE_CODE_RESTART pulse when the situation has been resolved.

Library:

libc

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

Description:

The MsgPause() and MsgPause_r() kernel calls pause a message. The thread associated with the rcvid must be reply-blocked on a channel that's owned by the calling process.

Here's an overview of how you'd use these functions:

• When a resource manager creates its channel by calling ChannelCreate(), it sets _NTO_CHF_MSG_PAUSING if it wants to allow the kernel to pause a message that would otherwise cause a deadlock. A deadlock situation could be caused by such things as:
  • writing to a memory-mapped file from a buffer mapped in from a memory-mapped file that's managed by the same resource manager
  • reading from a memory-mapped file

  The deadlock could make (for example) a thread of the user application block on the resource manager, a thread from the resource manager block on procnto, and a procnto thread block on the resource manager.

• The resource manager uses pulse_attach() or message_attach() to set up a handler for _PULSE_CODE_RESTART pulses.
• If a MsgRead*(), MsgWrite*(), or MsgReply*() call indicates an error of EDEADLK, the resource manager calls MsgPause() to pause the message.
• When the kernel resolves things (e.g., by loading the appropriate page of memory), it sends a _PULSE_CODE_RESTART to the resource manager.
• The resource manager uses the cookie passed with the pulse to identify the message, and then tries again to read, write, or reply to it.

Blocking states

None. If priority inheritance causes the priority of the calling thread to drop, other threads may run.

Returns:

The only difference between these functions is the way they indicate errors.

MsgPause()

If successful, this function returns EOK. If an error occurs, it returns -1 and sets errno.

MsgPause_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:

EINVAL

The thread associated with the rcvid already has a message paused.

ENOMEM

There wasn't enough memory available.

ESRCH

The thread associated with the rcvid isn't in STATE_REPLY.

Classification:

QNX Neutrino