PxOpoolRequest()

Create an object pool object.

APPLIES TO

1.0.0

SYNOPSIS
PxOpool_t PxOpoolRequest (PxOpoolType_t opooltype, PxUInt_t capacity, PxOpool_t src, PxOpool_t OpoolId);
ARGUMENTS






opooltype




Type of the object pool (real or virtual)


















capacity




Number of objects in the created object pool


















src




Object pool where to take the objects from


















OpoolId




Object pool where to take the object pool object from

















RETURN VALUES






    

  • 

    Valid object pool handle on success
    

    • 

  • 

    Invalid object pool handle on failure
    

    • 







ERROR CODES















PXERR_OPOOL_ILLOPOOL




OpoolId or src is not a valid pool object








PXERR_ACCESS_RIGHT




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








PXERR_GLOBAL_ILLEGAL_CORE




The requested object pool is not on the same core








PXERR_OPOOL_ILLTYPE




Illegal object pool type








PXERR_OPOOL_ILLCAPACITY




Insufficient capacity in the source object pool








PXERR_OPOOL_ILLSRC




The source of a real object pool must be real








PXERR_OBJ_ABORTED




The request was aborted by an event








PXERR_OBJ_NOOBJ




No free object is available








PXERR_OBJ_ILLOBJ




The passed object handle is not valid








PXERR_INTERNAL_INCONSISTENCY




Inconsistency of internal structures









DESCRIPTION










PxOpoolRequest function creates an object pool object of type opooltype by converting a generic object from object pool OpoolId. The new object handle is returned. If there is no object available, PxOpoolRequest waits until a free object is available.














The object pool can be of type:














    

  • 

    PXOpoolReal
    

    • 

  • 

    PXOpoolVirtual
    

    • 















When creating a new object pool of type PXOpoolReal, the number of free objects in parent object pool is reduced in favour of a newly created object pool. The new PXOpoolReal object pool can be used for reserving the required number of objects for critical tasks.














When creating a new object pool of type PXOpoolVirtual, the newly created object pool still shares the objects with the parent object pool, but the capacity parameter defines the maximum number of consumed objects. The new PXOpoolVirtual object pool can be used to limit the number of object consumed by a task.






















IMPLEMENTATION GUIDELINES
















Before call






    

  • 

    opooltype must be of type PxOpoolType_t and may have one of the following values
    

    

      

    • 

      PXOpoolReal
      

      • 

    • 

      PXOpoolVirtual
      

      • 

    

    

    • 

  • 

    capacity should be a plausible value held in a variable (C) or in a constant (V).
    

    • 

  • 

    src and OpoolId must be valid PXROS-HR object pools and the calling task must have the access right to take objects from them. The validity of src and 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.
    

    • 



















After call






    

  • 

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

    

      

    • 

      PxOpoolIdIsValid() must be true.
      

      • 

    • 

      PxOpoolIdGet() must not be _PXIllegalObjId.
      

      • 

    • 

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

      • 

    

    

    • 



















Best Practice






    

  • 

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

    • 

  • 

    PxOpoolRequest should only be called during initialization to ensure the availability of the object pool.
    

    • 






























SEE ALSO











USAGE








#include "pxdef.h"

PxOpool_t Opool = PxOpoolRequest(PXOpoolVirtual, 1, PXOpoolTaskdefault, OpoolId);

if (PxOpoolIdError(Opool) != PXERR_NOERROR) {
    // Report error
}