mstar.utils.profiler#

Utilities for NVTX range annotations for profiling with nsys.

Functions

`mark`(name)	Emit an instant NVTX marker without CUDA synchronization.
`nvtx_enabled`(requested[, device])	Enable NVTX only for a CUDA deployment or an explicitly CUDA device.
`nvtx_range`(name, *[, synchronize])	Convenience context manager for range_push/range_pop.
`phase_buffer`()	The shared sample buffer; `Worker.run` reads and clears it.
`phase_end`(name, start)	Record wall time as `name` and this thread's CPU time as `name.cpu`.
`phase_record`(name, dt)
`phase_start`()	Start stamp for `phase_end`: None unless MSTAR_PHASE_TIMING is set.
`range_pop`(*[, synchronize])	Pop the current NVTX range, optionally syncing before the marker.
`range_push`(name, *[, synchronize])	Push an NVTX range, optionally syncing before the marker.

Classes

PhaseLaps([prefix])

Consecutive stage timings: each lap(stage) records the wall and CPU time since the previous lap (or construction) as prefix + stage and prefix + stage + ".cpu".

class mstar.utils.profiler.PhaseLaps(prefix='')[source]#

Bases: object

Consecutive stage timings: each lap(stage) records the wall and CPU time since the previous lap (or construction) as prefix + stage and prefix + stage + ".cpu". A no-op unless MSTAR_PHASE_TIMING is set; skip() restarts the clock without recording, for a stretch timed elsewhere.

Parameters:: prefix (str)

lap(stage)[source]#

Parameters:: stage (str)
Return type:: None

skip()[source]#

Return type:: None

mstar.utils.profiler.mark(name)[source]#

Emit an instant NVTX marker without CUDA synchronization.

Parameters:: name (str)
Return type:: None

mstar.utils.profiler.nvtx_enabled(requested, device=None)[source]#

Enable NVTX only for a CUDA deployment or an explicitly CUDA device.

Parameters:

requested (bool)
device (device | None)

Return type:

bool

mstar.utils.profiler.nvtx_range(name, *, synchronize=False)[source]#

Convenience context manager for range_push/range_pop.

Parameters:

name (str)
synchronize (bool)

Return type:

Iterator[None]

mstar.utils.profiler.phase_buffer()[source]#

The shared sample buffer; Worker.run reads and clears it.

Return type:: dict[str, list[float]]

mstar.utils.profiler.phase_end(name, start)[source]#

Record wall time as name and this thread’s CPU time as name.cpu. Wall minus CPU is time the thread spent blocked – on the GIL, an event or a lock – which wall time alone cannot tell from work. Three threads share the GIL, so that gap is often large.

Parameters:

name (str)
start (tuple[float, float] | None)

Return type:

None

mstar.utils.profiler.phase_record(name, dt)[source]#

Parameters:

name (str)
dt (float)

Return type:

None

mstar.utils.profiler.phase_start()[source]#

Start stamp for phase_end: None unless MSTAR_PHASE_TIMING is set.

Return type:: tuple[float, float] | None

mstar.utils.profiler.range_pop(*, synchronize=False)[source]#

Pop the current NVTX range, optionally syncing before the marker.

Same semantics as range_push — default is synchronize=False.

Parameters:: synchronize (bool)
Return type:: None

mstar.utils.profiler.range_push(name, *, synchronize=False)[source]#

Push an NVTX range, optionally syncing before the marker.

Default is synchronize=False so adding NVTX markers doesn’t serialize the execution. Set synchronize=True only when the caller specifically wants the range to extend over the GPU work it wraps (e.g. an ad-hoc benchmark of one kernel) — and remember that each synchronize=True call drains the entire default stream via torch.cuda.synchronize(), not just the wrapped kernel.

Parameters:

name (str)
synchronize (bool)

Return type:

None

mstar.utils.profiler

Contents

mstar.utils.profiler#