PxToRequest()

Request a timeout object.

APPLIES TO

8.2.0

SYNOPSIS
PxTo_t PxToRequest (PxOpool_t OpoolId, PxTicks_t timeout, PxEvents_t events);
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

RETURN VALUES
  • Timeout object

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 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 waits until a free object is available.

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

After call
  • The returned value is the id of type PxTo_t. 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 may block, if no PXROS-HR object is available. If blocking calls are prohibited, PxToRequest_NoWait() should be used instead.

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

SEE ALSO
USAGE
#include "pxdef.h"

#define MY_EVENT_MASK 0x1l

PxTo_t To = PxToRequest(OpoolId, 1, MY_EVENT_MASK);

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