Python Annotation API¶
1 | |
API for naming specific ranges or points in time in code so that they appear in the trace.
| Function | Signature | Notes |
|---|---|---|
annotate |
(message: str) -> ContextManager[None] |
Context manager. Opens a Range on entry and closes it on exit, and closes it safely even if an exception is raised in the block |
range_push |
(message: str) -> int |
Opens a new Range on the Range stack of the calling thread. Returns the nesting depth of the new Range (starting at 0) |
range_pop |
() -> int |
Closes the most recently pushed Range. Returns the depth of the closed Range, or -1 if the stack is empty |
range_start |
(message: str) -> int |
Opens an independent Range unrelated to the stack. Returns a handle (int) valid across the process |
range_stop |
(id: int) -> None |
Closes a Range created with range_start() by its handle. Invalid handles are safely ignored |
mark |
(message: str) -> None |
Records an instantaneous event (a point in time, not a Range) |
Keep annotations in production code
Annotations are recorded in the trace only when the program runs under the haprof launcher. When it runs in a
normal environment without haprof, the import and the related function calls complete without error but
record nothing. It is therefore safe to keep annotation code in production code.
Example¶
annotate¶
Wraps one block in a range.
Example
1 2 3 4 | |
range_push¶
Opens a range that does not fit a block. Always close it with range_pop on the same thread.
Example
1 2 3 4 5 6 7 | |
range_pop¶
Closes the most recently opened range. The return value lets you check the push/pop balance.
Example
1 2 3 4 5 6 7 | |
range_start¶
Opens a range independent of the stack. Ranges may overlap and may cross function and thread boundaries.
Example
1 2 3 4 5 | |
range_stop¶
Closes a range with the handle returned by range_start.
Example
1 2 3 4 5 6 | |
mark¶
Records a point in time with no duration.
Example
1 2 3 | |