PxOpoolRequest_NoWait()

Create an object pool object with immediate return.

APPLIES TO

1.0.0

SYNOPSIS
PxOpool_t PxOpoolRequest_NoWait (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_NoWait 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_NoWait immediately returns with error code PXERR_OBJ_NOOBJ.

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_NoWait should only be called during initialization to ensure the availability of the object pool.

SEE ALSO
USAGE
#include "pxdef.h"

PxOpool_t Opool = PxOpoolRequest_NoWait(PXOpoolReal, 1, PXOpoolSystemdefault, OpoolId);

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