PxDelayRequest_EvWait()

Request a delay job handle while waiting for events.

APPLIES TO

1.0.0

SYNOPSIS
PxDelayEvent_t PxDelayRequest_EvWait (PxOpool_t opoolid, PxEvents_t events);
ARGUMENTS
events

Event mask with events making the call return

opoolid

The object pool, where the delay job object is requested from

RETURN VALUES
  • Valid delay job handle on success

  • Events, if request was aborted by an event

ERROR CODES

PXERR_OPOOL_ILLOPOOL

opoolid is not a valid object pool

PXERR_ACCESS_RIGHT

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

PXERR_OBJ_ABORTED

The request was aborted by an event

PXERR_EVENT_ZERO

The given event mask is zero

PXERR_OBJ_NOOBJ

No free object is available

PXERR_DELAY_ILLDELAY

Invalid delay object

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_INTERNAL_INCONSISTENCY

Inconsistency of internal structures

DESCRIPTION

PxDelayRequest_EvWait function creates a delay job handle by converting a free object from object pool opool. The object handle is returned. If there is no free object available, PxDelayRequest_EvWait waits until either there is a free object or an event specified in the set events occurs.

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 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 PxDelayEvent_t. The received events are stored in the events part, the delay id is given in the delay part of the structure. This id may be checked with one of the following macros:

    • PxDelayIdIsValid() must be true.

    • PxDelayIdGet() must not be _PXIllegalObjId.

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

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

  • PxDelayRequest_EvWait should only be called during initialization to ensure the availability of the delay object.

SEE ALSO
USAGE
#include "pxdef.h"

#define MY_EVENT 0x1l

PxDelay_t Delay = PxDelayRequest_EvWait(opoolid, MY_EVENT);

if PxDelayIdError(Delay) != PXERR_NOERROR) {
  // Report error
}