PxMcRequest()

Create a memory class object.

APPLIES TO

8.2.0

SYNOPSIS
PxMc_t PxMcRequest (PxMcType_t mctype, PxSize_t size, PxOpool_t opoolid);
ARGUMENTS






mctype




Type of the memory class


















size




Size parameter


















opoolid




Object pool where to take the memory class object from

















RETURN VALUES






    

  • 

    Valid memory class handle on success
    

    • 

  • 

    Invalid memory class handle on failure
    

    • 







ERROR CODES















PXERR_ACCESS_RIGHT




the calling task has not the right to access the object pool








PXERR_OPOOL_ILLOPOOL




opoolid is not a valid object pool








PXERR_OBJ_ABORTED




Request aborted by an event








PXERR_OBJ_NOOBJ




No free object is available








PXERR_GLOBAL_ILLEGAL_CORE




The requested object pool is not on the same core








PXERR_OBJ_ILLOBJ




The passed object handle is not valid








PXERR_MC_ILLTYPE




Illegal MC type








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









DESCRIPTION










The PxMcRequest function creates a memory class of type mctype by converting a generic object from object pool opoolid. The memory class object handle is returned. If there is no free object available, the PxMcRequest waits until a free object is available. For each memory class type the size parameter has different meaning.














The following memory class types exist:














    

  • 

    PXMcFixsized
    

    • 

  • 

    PXMcVarsized
    

    • 

  • 

    PXMcVarsizedAligned
    

    • 

  • 

    PXMcVarsizedAdjusted
    

    • 















The PXMcFixsized memory class can only manage memory blocks of the same size. The size parameter is set during memory class creation and defines the (common) size of any memory block managed by the memory class. The size parameter can be read by PxMcGetSize function.














The PXMcVarsized, PXMcVarsizedAligned and PXMcVarsizedAdjusted memory classes can manage memory blocks of different sizes. For PXMcVarsized memory classes the size parameter has no meaning and can be set to any value. For PXMcVarsizedAligned memory classes the size parameter defines the user alignment of memory blocks returned by function PxTakeBlk. For PXMcVarsizedAdjusted memory classes the size parameter defines the minimum size (adjustment) of the memory blocks returned by function PxTakeBlk. Minimum alignment and size of any memory block is 8 bytes.






















IMPLEMENTATION GUIDELINES
















Before call






    

  • 

    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 memory class type given in mctype must be of type PxMcType_t and may have one of the following values (V):
    

    

      

    • 

      PXMcFixsized
      

      • 

    • 

      PXMcVarsized
      

      • 

    • 

      PXMcVarsizedAligned
      

      • 

    • 

      PXMcVarsizedAdjusted
      

      • 

    

    

    • 

  • 

    The size parameter must have a plausible value (V).
    

    • 

  • 

    The calling task must have the access right to create new resources (V).
    

    • 



















After call






    

  • 

    The returned value is the id of type PxMc_t. This id may be checked with one of the following macros:
    

    

      

    • 

      PxMcIdIsValid() must be true.
      

      • 

    • 

      PxMcIdGet() must not be _PXIllegalObjId.
      

      • 

    • 

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

      • 

    

    

    • 



















Best Practice






    

  • 

    PxMcRequest may block, if no PXROS-HR object is available. If blocking calls are prohibited, PxMcRequest_NoWait should be used instead.
    

    • 

  • 

    PxMcRequest should only be called during initialization to ensure the availability of the memory class.
    

    • 






























SEE ALSO











USAGE








#include "pxdef.h"

PxMc_t mcHnd = PxMcRequest(64, PXMcFixsized, opoolid)

if (!PxMcIdIsValid (mcHnd)) {
    // Report error;
}