PxMsgRelease()

Release a message object (task service).

APPLIES TO

1.0.0

SYNOPSIS
PxMsg_t PxMsgRelease (PxMsg_t Msg);
ARGUMENTS
Msg

Message object to be released

RETURN VALUES
  • Invalid message handle on success

  • Msg on failure

ERROR CODES

PXERR_MSG_ILLMSG

The passed message handle is invalid

PXERR_MSG_ILLUSER

The calling task is not the user of the message

PXERR_PROT_ILL_HANDLE

The associated protection handle is not valid

PXERR_REQUEST_INVALID_PARAMETER

Request with invalid parameter

PXERR_ILL_NULLPOINTER_PARAMETER

Illegal null pointer parameter in the call

PXERR_PROT_ILL_SIZE

The size of the protection region is not valid

PXERR_PROT_ILL_ALIGN

Alignment of protection region is not valid

PXERR_MBX_ILLMBX

The passed mailbox handle is invalid

PXERR_MSG_ILLOWNER

The message has no owner

PXERR_MC_ILLMC

The memory class for the message is invalid

PXERR_OPOOL_ILLOPOOL

The passed object pool handle is invalid

PXERR_INIT_ILLMCTYPE

The type for PXMcSystemdefault is different from PXMcVarsized, PXMcVarsizedAdjusted and PXMcVarsizedAligned

PXERR_MC_DAMAGED_BLOCK

The block in memory class has been damaged

PXERR_MC_INCONSISTENCY

Inconsistency in memory class: blk

PXERR_MC_ILLALIGN

Invalid memory block or size alignment in memory insert

PXERR_MC_ILLSIZE

Insufficient block size

PXERR_GLOBAL_ILLEGAL_CORE

The requested object pool is not on the same core

PXERR_TASK_ILLTASK

The task is not a valid task object

PXERR_INTERNAL_INCONSISTENCY

Inconsistency of internal structures

DESCRIPTION

The PxMsgRelease function releases the message specified in Msg. All necessary cleanup operations are performed. For envelope messages the release service checks if a task is waiting for the message being released. If so, the task is readied.

IMPLEMENTATION GUIDELINES
Before call
  • Msg must be a valid message object, requested via PxMsgRequest…​ or PxMsgEnvelop…​ or received by a PxMsgReceive…​ call (V). 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).

After call
  • PxMsgRelease returns the message object to the object pool it has been taken from. On success PxMsgRelease returns the invalidated message object. This may be checked with one of the following macros:

    • PxMsgIdIsValid() must be false.

    • PxMsgIdGet() must be _PXIllegalObjId.

    • PxMsgIdError() must be PXERR_NOERROR otherwise the returned error code has to be interpreted (C).

Best Practice
  • After PxMsgRelease, the given message object Msg is no longer valid and may never be used as message object!

SEE ALSO
USAGE
#include "pxdef.h"

PxMsg_t Msg = PxMsgRelease(Msg);

if (PxMsgIdIsValid(Msg)) {
    // Report error
}