Crate hprof [] [src]

A real-time hierarchical profiler.

What is hierarchical profiling?

Hierarchical profiling is based on the observation that games are typically organized into a "tree" of behavior. You have an AI system that does path planning, making tactical decisions, etc. You have a physics system that does collision detection, rigid body dynamics, etc. A tree might look like:

  • Physics
    • Collision detection
      • Broad phase
      • Narrow phase
    • Fluid simulation
    • Rigid body simulation
      • Collision resolution
      • Update positions
  • AI
    • Path planning
    • Combat tactics
    • Build queue maintenance
  • Render
    • Frustum culling
    • Draw call sorting
    • Draw call submission
    • GPU wait

A hierarchical profiler will annotate this tree with how much time each step took. This is an extension of timer-based profiling, where a timer is used to measure how long a block of code takes to execute. Rather than coding up a one-time timer, you merely call Profiler::enter("description of thing") and a new entry will be made in the profile tree.

The idea came from a 2002 article in Game Programming Gems 3, "Real-Time Hierarchical Profiling" by Greg Hjelstrom and Byon Garrabrant from Westwood Studios. They report having thousands of profile nodes active at a time.

There are two major ways to use this library: with explicit profilers, and with an implicit profiler.

Implicit (thread-local) profiler

To use the implicit profiler, call hprof::start_frame(), hprof::end_frame(), and hprof::enter("name"). Destructors will take care of the rest. You can access the profiler using hprof::profiler().

Explicit profilers

Use Profiler::new() and pass it around/store it somewhere (for example, using current).



A "guard" for calling Profiler::leave when it is destroyed.


A single node in the profile tree.


A single tree of profile data.