PxMsgRequest_EvWait()

Create a message object together with data area while waiting for events.

APPLIES TO

1.0.0

SYNOPSIS
PxMsgEvent_t PxMsgRequest_EvWait (PxSize_t msgsize, PxMc_t McId, PxOpool_t OpoolId, PxEvents_t events);
ARGUMENTS






msgsize




Size of the message


















McId




Memory class where to take the data area from


















OpoolId




Object pool where to take the message object from


















events




Event mask to make the call return

















RETURN VALUES






    

  • 

    Valid message handle on success
    

    • 

  • 

    Invalid message handle on failure
    

    • 

  • 

    Event mask that caused the call return
    

    • 







ERROR CODES















PXERR_OPOOL_ILLOPOOL




The passed object pool handle is invalid








PXERR_MC_ILLMC




The passed memory class handle is invalid








PXERR_MC_NOMEM




Not enough memory








PXERR_ACCESS_RIGHT




The calling task has not the right to access the object pool or the memory class








PXERR_GLOBAL_ILLEGAL_CORE




The passed memory class is not on the same core








PXERR_OBJ_NOOBJ




No free object is available








PXERR_EVENT_ZERO




The given event mask is zero








PXERR_OBJ_ABORTED




Request aborted by an event








PXERR_OBJ_ILLOBJ




The passed object handle is not valid








PXERR_MC_ILLTYPE




Illegal MC type








PXERR_MC_SIZETOOBIG




Fixed block size too small to satisfy the request








PXERR_INIT_ILLMCTYPE




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








PXERR_REQUEST_ABORTED




Request aborted








PXERR_MC_DAMAGED_BLOCK




The block in the memory class has been damaged








PXERR_MC_INCONSISTENCY




Inconsistency in memory class: blk








PXERR_MC_ILLSIZE




Insufficient block size








PXERR_MC_ILLALIGN




Invalid memory block or size alignment in memory insert








PXERR_INTERNAL_INCONSISTENCY




Inconsistency of internal structures








PXERR_UNSUPPORTED_MCTYPE




mc is not supported (If McId corresponds to PXMcVarsized, PXMcVarsizedAligned, PXMcVarsizedAdjusted)









DESCRIPTION










The PxMsgRequest_EvWait function creates a message with a data area of size msgsize specified in byte units. The data area is taken from memory class mc, and the message object is taken from object pool opool. The message object handle is returned. If there is no free object available, the PxMsgRequest_EvWait waits until a free object is available or until an event from the mask of events occurs.














The calling task becomes the (permanent) owner and the (temporary) user of the message created. The call also fails, if the memory class does not contain sufficient memory to meet the request. A fatal PXROS error occurs, if mc is fixsized and its block size is smaller than msgsize. If msgsize is zero, no data buffer is requested and only the metadata of the message object can be used.






















IMPLEMENTATION GUIDELINES
















Before call






    

  • 

    msgsize must be a plausible value given as a constant (V) or a variable (C).
    

    • 

  • 

    McId must be a valid PXROS-HR memory class and the calling task must have the access right to take memory from this memory class (V). The validity of McId may also be checked by the PxMcIsValid macro (F). The memory class must be created on the same core as the caller runs on. The creator core id can be read with the macro PxMcCoreId and the own core id with PxGetCoreId (C). Typically the task’s default memory class PXMcTaskdefault is used for this purpose.
    

    • 

  • 

    OpoolId must be a valid PXROS-HR object pool and the calling task must have the access right to take objects from this object pool (V). The validity of OpoolId may also be checked by the PxOpoolIsValid macro (F). The object pool must be created on the same core as the caller runs on. The creator core id can be read with the macro PxOpoolCoreId and the own core id with PxGetCoreId (C). Typically the task’s default object pool PXOpoolTaskdefault is used for this purpose.
    

    • 

  • 

    The parameter events contains a bitmask of events awaited and should not be zero. Typically the event mask is a constant (V).
    

    • 



















After call






    

  • 

    The returned value is a structure of type PxMsgEvent_t. The received events are stored in the events part, the message id is given in the msg part of the structure. 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






    

  • 

    PxMsgRequest_EvWait may block, if no PXROS-HR object or memory is available and no instance (task or handler) sends an event. If blocking calls are prohibited, PxMsgRequest_NoWait() should be used instead or the call should be monitored by the PXROS-HR PxTo mechanism.
    

    • 






























SEE ALSO











USAGE








#include "pxdef.h"

#define MY_EVENT_MASK 0x1l

PxMsgEvent_t msgEvHnd = PxMsgRequest_EvWait(64, McId, OpoolId, MY_EVENT_MASK)

if (PxMsgIdIsValid (msgEvHnd.msg)) {
    /// Request successful - handle message
}
else if (msgEvHnd.events & MY_EVENT_MASK) {
    // Request not successful - interrupted by event
}
else
{
    // Request not successful - check the msgEvHnd.msg.error
}