VPI - Vision Programming Interface

1.0 Release

A representation of events used in stream synchronization and timing. More...

Typedefs

typedef struct VPIEventImpl * VPIEvent
 A handle to an event.
 

Functions

VPIStatus vpiEventCreate (uint32_t flags, VPIEvent *event)
 Create an event instance with the specified flags. More...
 
void vpiEventDestroy (VPIEvent event)
 Destroy an event instance as well as all resources it owns. More...
 
VPIStatus vpiEventRecord (VPIEvent event, VPIStream stream)
 Captures in the event the contents of the stream command queue at the time of this call. More...
 
VPIStatus vpiEventSync (VPIEvent event)
 Blocks the calling thread until the event is signaled. More...
 
VPIStatus vpiEventQuery (VPIEvent event, VPIEventState *state)
 Queries the status of all work currently captured by the event. More...
 
VPIStatus vpiEventElapsedTimeMillis (VPIEvent start, VPIEvent end, float *msec)
 Computes the elapsed time in (msec) between two completed events. More...
 
VPIStatus vpiEventGetFlags (VPIEvent event, uint32_t *flags)
 Returns the event flags passed during event creation. More...
 

Event-specific flags.

#define VPI_EVENT_DISABLE_TIMESTAMP   (1 << 18)
 disable time-stamping of event signaling for better performance.
 

Detailed Description

A representation of events used in stream synchronization and timing.

Each compute function in the API is executed asynchronously with respect to the calling thread, i.e., returns immediately without waiting for the completion. There are two ways of synchronizing with the backend. One is to wait until all the commands in the VPIStream queue are finished, with the vpiStreamSync call. This approach, while simple, doesn't allow for fine-grained ("wait for until function X is completed") or inter-device ("before running function A in device B, wait until function C in device D finishes") synchronization. That's where VPIEvent objects come in. Conceptually, they correspond to binary semaphores and are designed to closely mimic events in CUDA API:

Function Documentation

◆ vpiEventCreate()

VPIStatus vpiEventCreate ( uint32_t  flags,
VPIEvent event 
)

#include <vpi/Event.h>

Create an event instance with the specified flags.

Parameters
[in]flagsEvent flags. Here it can be specified in what backends the image can be used by or-ing together VPIBackend flags. Set flags to 0 to enable it in all backends supported by the active VPI context. Additional flags can also be specified.
[out]eventPointer to memory that will receive the created event handle.
Returns
an error code on failure else VPI_SUCCESS.

◆ vpiEventDestroy()

void vpiEventDestroy ( VPIEvent  event)

#include <vpi/Event.h>

Destroy an event instance as well as all resources it owns.

Parameters
[in]eventevent handle

◆ vpiEventElapsedTimeMillis()

VPIStatus vpiEventElapsedTimeMillis ( VPIEvent  start,
VPIEvent  end,
float *  msec 
)

#include <vpi/Event.h>

Computes the elapsed time in (msec) between two completed events.

If one or both are not completed at the time of the call, VPI_ERROR_NOT_READY is returned, otherwise VPI_SUCCESS.

Parameters
[in]startan event handle marking the start of the time interval
[in]endan event handle marking the end of the time interval
[out]mseca pointer to a variable which will be set to the time difference between the events
Returns
an error code on failure, VPI_ERROR_NOT_READY if at least one event is not ready, else VPI_SUCCESS

◆ vpiEventGetFlags()

VPIStatus vpiEventGetFlags ( VPIEvent  event,
uint32_t *  flags 
)

#include <vpi/Event.h>

Returns the event flags passed during event creation.

Parameters
[in]eventAn event handle.
[out]flagsPointer to memory that will hold the event flags. It can't be NULL.
Returns
An error code on failure, or else VPI_SUCCESS.

◆ vpiEventQuery()

VPIStatus vpiEventQuery ( VPIEvent  event,
VPIEventState state 
)

#include <vpi/Event.h>

Queries the status of all work currently captured by the event.

If all tasks are finished, VPI_SUCCESS is returned, otherwise VPI_ERROR_NOT_READY.

Parameters
[in]eventAn event handle.
[out]statePointer to memory that will receive the states of the event. State is only valid when the return status is VPI_SUCCESS.
Returns
an error code on failure else VPI_SUCCESS

◆ vpiEventRecord()

VPIStatus vpiEventRecord ( VPIEvent  event,
VPIStream  stream 
)

#include <vpi/Event.h>

Captures in the event the contents of the stream command queue at the time of this call.

When all tasks recorded are finished, the event will be signaled and calls that are waiting for it will be unblocked.

This function can be called multiple times on the same event, however existing vpiEventSync / vpiStreamWaitEvent calls are not affected by later calls to vpiEventRecord. This means they will wait for the event completion of the command queue tasks described by the event at the time of the initial vpiEventSync / vpiStreamWaitEvent call.

Parameters
[in]eventAn event handle
[in]streamA stream handle whose command queue with tasks yet to be executed will be recorded in the event.
Returns
an error code on failure else VPI_SUCCESS.

◆ vpiEventSync()

VPIStatus vpiEventSync ( VPIEvent  event)

#include <vpi/Event.h>

Blocks the calling thread until the event is signaled.

The event is considered signaled when all the tasks captured by vpiEventRecord are completed or when no tasks were captured.

Parameters
[in]eventAn event handle.
Returns
an error code on failure else VPI_SUCCESS