Event

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

Typedefs
typedef struct VPIEventImpl *	VPIEvent
	A handle to an event.

Functions
VPIStatus	vpiEventCreate (uint64_t flags, VPIEvent *event)
	Create an event instance. 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 milliseconds between two completed events. More...
VPIStatus	vpiEventGetFlags (VPIEvent event, uint64_t *flags)
	Returns the event flags passed during event creation. More...

Event-specific flags.
#define	VPI_EVENT_DISABLE_TIMESTAMP   (1ULL << 63)
	Disable time-stamping of event signaling. More...

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 using 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:

• Users can capture all commands submitted to a VPIStream instance in an event instance (see vpiEventRecord). The event is considered completed when all captured commands have been processed and removed from VPIStream command queue.
• Inter-device synchronization is possible with vpiStreamWaitEvent call that pushes a command to VPIStream queue that blocks processing of future queued commands until given event is completed.
• Host threads can query the event's state with vpiEventQuery
• Host threads can block until event is completed with vpiEventSync.
• Events can be time-stamped when completed.
• Users can compute time-stamp difference between completed events in the same device as well as between different devices. This implies that internally, the API has to have a notion of unified time source.

Macro Definition Documentation

VPI_EVENT_DISABLE_TIMESTAMP

#define VPI_EVENT_DISABLE_TIMESTAMP   (1ULL << 63)

#include </opt/nvidia/vpi3/include/vpi/Event.h>

Disable time-stamping of event signaling.

It allows for better performance in operations involving events.

Definition at line 105 of file Event.h.

Function Documentation

vpiEventCreate()

VPIStatus vpiEventCreate	(	uint64_t	flags,
		VPIEvent *	event
	)

#include </opt/nvidia/vpi3/include/vpi/Event.h>

Create an event instance.

Parameters

[in]	flags	Bit field specifying the desired characteristics of the event. The field must be a combination of zero or more of the following flags: VPIBackend flags. This even can be used in streams that have these backends enabled. If no backend flags are passed and VPI_REQUIRE_BACKENDS flag isn't present, it'll consider all backends supported by the active context. Event-specific flags. Common object flags. If flag VPI_REQUIRE_BACKENDS is given, user must pass at least one valid backend, and they all must be enabled in current context.
[out]	event	Pointer to memory that will receive the created event handle. Mandatory parameter, can't be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	Output event handle is NULL.
VPI_ERROR_INVALID_ARGUMENT	flags is invalid.
VPI_ERROR_INVALID_ARGUMENT	No backend were given and VPI_REQUIRE_BACKENDS is set.
VPI_ERROR_OUT_OF_MEMORY	Not enough resources to allocate event.
VPI_ERROR_INVALID_CONTEXT	Current context is invalid.
VPI_ERROR_INVALID_OPERATION	Requested backend isn't enabled in current context.
VPI_SUCCESS	Operation executed successfully.

vpiEventDestroy()

void vpiEventDestroy

(

VPIEvent

event

)

#include </opt/nvidia/vpi3/include/vpi/Event.h>

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

Parameters

[in]

event

Event handle to be destroyed. It can be NULL. In this case, the function doesn't do anything. All streams referencing the event must be idle, or else undefined behavior will ensue.

vpiEventRecord()

VPIStatus vpiEventRecord	(	VPIEvent	event,
		VPIStream	stream
	)

#include </opt/nvidia/vpi3/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 previous vpiEventSync / vpiStreamWaitEvent call.

The operation will implicitly flush the stream.

Parameters

[in]	event	An event handle. Mandatory, it can't be NULL.
[in]	stream	A stream handle whose command queue with tasks yet to be executed will be recorded in the event. Mandatory, it can't be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	event is NULL or doesn't represent an VPIEvent instance.
VPI_ERROR_INVALID_ARGUMENT	stream is NULL or not valid or doesn't represent VPIStream instance.
VPI_ERROR_INVALID_ARGUMENT	Event doesn't have the backend required by the stream enabled.
VPI_ERROR_INTERNAL	Event doesn't have any backends enabled for recording.
VPI_ERROR_INVALID_CONTEXT	Current context is invalid.
VPI_SUCCESS	Operation executed successfully.

vpiEventSync()

VPIStatus vpiEventSync

(

VPIEvent

event

)

#include </opt/nvidia/vpi3/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]

event

An event handle. Mandatory, it can't be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	event is NULL or doesn't represent an VPIEvent instance.
VPI_SUCCESS	Operation executed successfully.

vpiEventQuery()

VPIStatus vpiEventQuery	(	VPIEvent	event,
		VPIEventState *	state
	)

#include </opt/nvidia/vpi3/include/vpi/Event.h>

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

Parameters

[in]	event	An event handle. Mandatory, it can't be NULL.
[out]	state	Pointer to memory that will receive the event state. The returned state is only valid when the status returned is VPI_SUCCESS.

Return values

VPI_ERROR_INVALID_ARGUMENT	Output state pointer is NULL.
VPI_SUCCESS	Operation executed successfully.

vpiEventElapsedTimeMillis()

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

#include </opt/nvidia/vpi3/include/vpi/Event.h>

Computes the elapsed time in milliseconds between two completed events.

Parameters

[in]	start	An event handle marking the start of the time interval. Mandatory, cannot be NULL. Must have been completed/signaled. Must not have been created with VPI_EVENT_DISABLE_TIMESTAMP flag.
[in]	end	An event handle marking the end of the time interval Mandatory, cannot be NULL. Must have been completed/signaled. Must not have been created with VPI_EVENT_DISABLE_TIMESTAMP flag.
[out]	msec	A pointer to a variable which will be set to the time difference between the events signaling. Mandatory, cannot be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	start or end is NULL or don't represent an VPIEvent instance.
VPI_ERROR_INVALID_ARGUMENT	Output msec pointer is NULL.
VPI_ERROR_INVALID_OPERATION	At least one event was created with timestamps disabled.
VPI_ERROR_NOT_READY	At least one event is not completed/signaled.
VPI_SUCCESS	Operation executed successfully.

vpiEventGetFlags()

VPIStatus vpiEventGetFlags	(	VPIEvent	event,
		uint64_t *	flags
	)

#include </opt/nvidia/vpi3/include/vpi/Event.h>

Returns the event flags passed during event creation.

Parameters

[in]	event	An event handle. Mandatory, cannot be NULL.
[out]	flags	Pointer to memory that will hold the event flags. It can't be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	event is NULL or doesn't represent an VPIEvent instance.
VPI_ERROR_INVALID_ARGUMENT	flags is NULL.
VPI_SUCCESS	Operation executed successfully.