PxMsgReceive_NoWait()

Receive a message from a mailbox with immediate return.

APPLIES TO

1.0.0

SYNOPSIS

PxMsg_t PxMsgReceive_NoWait (PxMbx_t mbxid);

ARGUMENTS

mbxid: The mailbox handle

ERROR CODES

PXERR_MBX_ILLMBX

The passed mailbox handle is invalid

PXERR_MSG_NOMSG

No message available

PXERR_MSG_ILLMSG

The passed message handle is invalid

PXERR_MSG_ILLUSER

The calling task is not the user of the message

PXERR_EVENT_ZERO

The given event mask is zero

DESCRIPTION

PxMsgReceive_NoWait receives a message object from mailbox mbxid and returns the received message handle. The task becomes the user of the received message. If there is no message in the mailbox mbxid, the PxMsgReceive_NoWait immediately returns with invalid object handle.

IMPLEMENTATION GUIDELINES

Before call

The parameter mbxid must be a valid mailbox object id. This id may be
- the calling task’s own mailbox (V)
- the result of a nameserver query (V)
- part of a message sent by another task (V)
The mailbox may be checked with the macros
- PxMsgIdIsValid() must be true.
- PxMsgIdGet() must not be _PXIllegalObjId.
- PxMsgIdError() must be PXERR_NOERROR otherwise the returned error code has to be interpreted (C).
or with a call of PxMbxCheck() (C).
The mailbox mbx must be created on the same core as the caller runs on. The creator core id can be read with the macro PxMbxCoreId and the own core id with PxGetCoreId (C).

After call

The returned value is the id of type PxMsg_t, if a message is taken from the mailbox. This id may be checked with one of the following macros:
- PxMsgIdIsValid() must be true.
- PxMsgIdGet() must not be _PXIllegalObjId.
- PxMsgIdError() must be PXERR_NOERROR otherwise the returned error code has to be interpreted (C).

Best Practice

No restrictions.

SEE ALSO

USAGE

#include "pxdef.h"

PxMsg_t Msg = PxMsgReceive_NoWait(mbxid);

if (!PxMsgIdIsValid(Msg)) {
    // Report error
}
else if (PxMsgIdError(RetMsg) == PXERR_MSG_NOMSG) {
    // No message in the mailbox
}
else {
    // Handle mailbox
}