API

NVTX.@mark [message] [domain=...] [color=...] [category=...] [payload=...]

Instruments an instantaneous event.

• message is a string. Default is to use "file:lineno"`. String interpolation is supported, but may incur additional overhead.
• domain is a Domain. Default is to use the default domain of the current module.
• color is either a Colorant from the Colors.jl package, or an UInt32 containing an ARGB32 value. Default is to generate one based on the hash of the message.
• category: an integer describing the category of the event. Default is 0.
• payload: an optional integer (Int32, UInt32, Int64, UInt64) or floating point (Float32, Float64) value to attach to the event.

Example

for i = 1:10
    NVTX.@mark "iterate" payload=i
    do_work()
end

NVTX.@range [message] [domain=...] [color=...] [category=...] [payload=...] expr

Instruments a range over the expr.

The default message is the expression, with file and line number. See @mark for the other arguments.

Example

for i = 1:10
    NVTX.@range "iterate" payload=i begin
        do_work()
    end
end

NVTX.@annotate [message] [domain=...] [color=...] [category=...] [payload=...] function ... end

Instruments a range a function definition, so that each invocation of the method will be marked with a range. Equivalent to using @range within the body of the function.

The default message is the function signature with file and line number.. See @mark for the other arguments. Function arguments can be used as range arguments.

Example

NVTX.@annotate payload=x function foo(x)
    # function body
end
# is equivalent to
function foo(x)
    NVTX.@range payload=x begin
        # function body
    end
end

foo(1)
foo(2)

NVTX.@category value name

Annotate an NVTX category value with name in the modules default domain. For convenience, this returns the evaluated value

const category_3 = @category 3 "category 3"

A category should only be defined once for a particular value within a given domain.

See also name_category

NVTX.enable_gc_hooks(;gc=true, alloc=false, free=false)

Add NVTX hooks for the Julia garbage collector:

• gc: instrument GC invocations as ranges,
• alloc: instrument calls to alloc as marks (payload will contain allocation size), and
• free: instrument calls to free as marks.

If the JULIA_NVTX_CALLBACKS environment variable is set, this will be automatically called at module initialization. JULIA_NVTX_CALLBACKS should be either a comma (,) or bar (|) separated list of callbacks to enable. For example, setting it to gc|alloc|free will enable all hooks. The --env-var argument can be helpful for setting this variable, e.g.

nsys profile --env-var=JULIA_NVTX_CALLBACKS=gc|alloc|free julia --project script.jl

NVTX.enable_inference_hook(active::Bool=true)

Add hooks for method inference. Can also be activated by adding inference to the JULIA_NVTX_CALLBACKS environment variable.

name_threads_julia([namefn])

Name the threads owned by the Julia process using namefn(). The default is namefn() = "julia thread $(Threads.threadid())".

This function is called at module initialization if the profiler is active, so should not generally need to be called manually unless a custom name is required.

NVTX.isactive()

Determine if Nsight Systems profiling is currently active.

initialize()

Force NVTX library to initialize. The first call to any NVTX API function will automatically initialize the entire API. This can make the first call much slower than subsequent calls.

NVTX.activate()

Activate the NVTX APIs. This is called automatically when importing NVTX.jl while running under Nsight profilers. It can also be called manually to enable NVTX when running under a different profiler that is compatible with NVTX. Note that in such cases, you may have to manually set the NVTX_INJECTION64_PATH environment variable and have it point to a library that can handle the NVTX APIs.

Domain(name::AbstractString)

Construct a new NVTX domain with name.

See NVTX Domains.

Domain(::Module)

Get the default domain for a module. If no domain has been defined for the module, a new one is created.

StringHandle(domain::NVTX.Domain, string::AbstractString)

Register string with domain, returning a StringHandle object.

Registered strings are intended to increase performance by lowering instrumentation overhead.

NVTX.mark([domain::Domain]; message, color, payload, category)

Marks an instantaneous event in the application.

The domain positional argument allows specifying a custom Domain, otherwise the default domain is used.

Optional keyword arguments:

• message: a text string, or StringHandle object.
• color: a Colorant from the Colors.jl package, or an integer containing an ARGB32 value.
• payload: a value of one of the following types: UInt64, Int64, UInt32, Int32, Float64, Float32.
• category: a positive integer. See name_category.

NVTX.range_start([domain::Domain]; message, color, payload, category)

Starts a process range.

Returns a RangeId value, which should be passed to range_end.

See mark for the keyword arguments.

NVTX.range_end(range::RangeId)

Ends a process range started with range_start.

range_push([domain]; message, color, payload, category)

Starts a nested thread range. Returns the 0-based level of range being started (the level is per-domain).

Must be completed with range_pop with the same domain argument.

See mark for the keyword arguments.

range_pop([domain::Domain])

Ends a nested thread range created by range_push on domain.

Returns the 0-based level of the range being ended.

name_category([domain::Domain,] category::Integer, name::AbstractString)

Annotate an NVTX category with name. If a Domain argument is provided, then annotation only applies within that domain.

See also @category

gettid()

Get the system thread ID of the current Julia thread. This is compatible with name_os_thread.

name_os_thread(threadid::Integer, name::AbstractString)

Attach a name to an operating system thread. threadid is the OS thread ID, returned by gettid.