PxMsgReceive_NoWait()
Receive a message from a mailbox with immediate return.
- APPLIES TO
-
8.2.0
- SYNOPSIS
-
PxMsg_t PxMsgReceive_NoWait (PxMbx_t mbxid);
- ARGUMENTS
|
- 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 bePXERR_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 withPxGetCoreId
(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 bePXERR_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 }