# [−][src]Crate hprof

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`).

## Structs

ProfileGuard | A "guard" for calling `Profiler::leave` when it is destroyed.
ProfileNode | A single node in the profile tree.
Profiler | A single tree of profile data.

## Functions

end_frame |
enter |
profiler |
start_frame |

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)