PxToRequest_EvWait()

Request a timeout object while waiting for events.

APPLIES TO

8.2.0

SYNOPSIS
PxTo_t PxToRequest_EvWait (PxOpool_t OpoolId, PxTicks_t timeout, PxEvents_t events, PxEvents_t abortevents);
ARGUMENTS






OpoolId




The object pool to request the timeout object from


















timeout




Number of ticks after which the event is signalled


















events




Events to be signalled after period ticks


















abortevents




Event mask with events making the call return

















RETURN VALUES






    

  • 

    Invalid timeout object on failure
    

    • 

  • 

    Timeout object on success
    

    • 

  • 

    Events, if request aborted by an event
    

    • 







ERROR CODES















PXERR_OPOOL_ILLOPOOL




The passed object pool handle is invalid








PXERR_OBJ_NOOBJ




No free object is available








PXERR_OBJ_ABORTED




The request was aborted by an event








PXERR_OBJ_ILLOBJ




The passed object handle is not valid








PXERR_GLOBAL_ILLEGAL_CORE




The requested object pool is not on the same core








PXERR_EVENT_ZERO




The given event mask is zero








PXERR_ACCESS_RIGHT




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








PXERR_INTERNAL_INCONSISTENCY-




Inconsistency of internal structures








PXERR_TO_ILLTO




The given object is no timeout object









DESCRIPTION










PxToRequest_EvWait creates and initializes a timeout event handler object, which is returned. It is associated with period and events. System resources are allocated, as needed, to signal events to the calling task after a period of ticks has passed since the timeout is started (PxToStart). It is necessary to finish up with PxToRelease, when the timeout event is no longer used. If there is no object available in the object pool OpoolId, the PxToRequest_EvWait waits until a free object is available or until an event from mask of the 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 timeout parameter must have a plausible value. It should be a constant or the result of a PxTickGetTicksFromMilliSeconds call (V);
    

    • 

  • 

    The parameter events contains an event bit  and should not be zero. Typically the event is a constant (V).
    

    • 

  • 

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

    

      

    • 

      PxToIdIsValid() must be true.
      

      • 

    • 

      PxToIdGet() must not be _PXIllegalObjId.
      

      • 

    • 

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

      • 

    

    

    • 



















Best Practice






    

  • 

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

    • 

  • 

    PxToRequest_EvWait should only be called during initialization to ensure the availability of the timeout  object.
    

    • 






























SEE ALSO











USAGE








#include "pxdef.h"

#define MY_EVENT 0x1l
#define TICKS 0x1l

PxTo_t To = PxToRequest_EvWait(OpoolId, TICKS, MY_EVENT, abortevents);

if (PxToIdError(To) != PXERR_NOERROR){
    // Report error
}