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
}