PxMcRequest_EvWait()

Create a memory class object while waiting for events.

APPLIES TO

1.0.0

SYNOPSIS
PxMcEvent_t PxMcRequest_EvWait (PxMcType_t mctype, PxSize_t size, PxOpool_t OpoolId, PxEvents_t events);
ARGUMENTS
mctype

Type of the memory class

size

Size parameter

OpoolId

Object pool where to take the memory class object from

events

Eventmask to make the call return

RETURN VALUES
  • Valid memory class handle on success

  • Invalid memory class handle on failure

  • Event mask that caused the call return

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

PXERR_UNSUPPORTED_MCTYPE

mctype is not supported (If mctype is PXMcVarsized, PXMcVarsizedAligned, PXMcVarsizedAdjusted)

PXERR_EVENT_ZERO

The given event mask is zero

DESCRIPTION

The PxMcRequest_EvWait 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_EvWait waits until a free object is available or until an event from the mask of events occurs. For each memory class type the size parameter has different meaning.

The following memory class types exist:

  • PXMcFixsized

  • PXMcBuddyMemory

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 PXMcBuddyMemory classes can manage memory blocks of different power of two sizes. Each block in the memory class is aligned to its size. The minimum block size is 32 bytes.

IMPLEMENTATION GUIDELINES
Before call
  • 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).

  • 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).

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

After call
  • The returned value is a structure of type PxMcEvent_t. The received events are stored in the events part, the memory class id is given in the mc part of the structure. 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_EvWait may block, if no PXROS-HR object is available and no instance (task or handler) sends an event. If blocking calls are prohibited, PxMcRequest_NoWait should be used instead or the call should be monitored by the PXROS-HR PxTo mechanism.

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

SEE ALSO
USAGE
#include "pxdef.h"

PxMcEvent_t mcEv = PxMcRequest_EvWait(64, PXMcFixsized, OpoolId, MY_EVENT_MASK)

if (!PxMcIdIsValid(mcEv.msg) || (mcEv.events != MY_EVENT_MASK)) {
    // Report error
}
else {
    // Handle event
}