|
NVTX C API Reference v3
NVIDIA Tools Extension Library
|
The NVIDIA Tools Extension library is a set of functions that a developer can use to provide additional information to tools. The additional information is used by the tool to improve analysis and visualization of data.
The library introduces close to zero overhead if no tool is attached to the application. The overhead when a tool is attached is specific to the tool.
Typically the tool's library that plugs into NVTX is indirectly loaded via enviromental properties that are platform specific. For some platform or special cases, the user may be required to instead explicity initialize instead though. This can also be helpful to control when the API loads a tool's library instead of what would typically be the first function call to emit info. For these rare case, see INITIALIZATION for additional information.
Markers and ranges are used to describe events at a specific time (markers) or over a time span (ranges) during the execution of the application respectively.
Markers denote specific moments in time.
See Domains and Event Attributes for additional information on how to specify the domain.
Thread ranges denote nested time ranges. Nesting is maintained per thread per domain and does not require any additional correlation mechanism. The duration of a thread range is defined by the corresponding pair of nvtxRangePush* to nvtxRangePop API calls.
See Domains and Event Attributes for additional information on how to specify the domain.
Process ranges denote a time span that can expose arbitrary concurrency, as opposed to thread ranges that only support nesting. In addition the range start event can happen on a different thread than the end marker. For the correlation of a start/end pair an unique correlation ID is used that is returned from the start API call and needs to be passed into the end API call.
Markers and Ranges can be annotated with various attributes to provide additional information for an event or to guide the tool's visualization of the data. Each of the attributes is optional and if left unused the attributes fall back to a default value. The attributes include:
To specify any attribute other than the text message, the Event Attribute Structure must be used.
Domains enable developers to scope annotations. By default all events and annotations are in the default domain. Additional domains can be registered. This allows developers to scope markers, ranges, and resources names to avoid conflicts.
The function nvtxDomainCreateA or nvtxDomainCreateW is used to create a named domain.
Each domain maintains its own
The function nvtxDomainDestroy marks the end of the domain. Destroying a domain unregisters and destroys all objects associated with it such as registered strings, resource objects, named categories, and started ranges.
This section covers calls that allow to annotate objects with user-provided names in order to allow for a better analysis of complex trace data. All of the functions take the handle or the ID of the object to name and the name. The functions can be called multiple times during the execution of an application, however, in that case it is implementation dependent which name will be reported by the tool.
Some function in this library support associating an integer category to enable filtering and sorting. The category naming functions allow the application to associate a user friendly name with the integer category. Support for domains have been added in NVTX_VERSION_2 to avoid collisions when domains are developed independantly.
Resource objects are a generic mechanism for attaching data to an application resource. The identifier field makes the association to a pointer or handle, while the type field helps provide deeper understanding of the identifier as well as enabling differentiation in cases where handles generated by different APIs may collide. The resource object may also have an associated message to associate with the application resource, enabling further annotation of this object and how it is used.
The resource object was introduced in NVTX_VERSION_2 to supersede existing naming functions and allow the application resource identified by those functions to be associated to a domain. The other naming functions are still supported for backward compatibility but will be associated only to the default domain.
Some operating system resources creation APIs do not support providing a user friendly name, such as some OS thread creation APIs. This API support resource naming though both through resource objects and functions following the pattern nvtxName[RESOURCE_TYPE][A|W](identifier, name). Resource objects introduced in NVTX_VERSION 2 supersede the other functions with a a more general method of assigning names to OS resources, along with associating them to domains too. The older nvtxName* functions are only associated with the default domain.
Optional extensions will either appear within the existing sections the extend or appear in the "Related Pages" when they introduce new concepts.
1.9.5