Support for Perf Maps¶

On supported platforms (as of this writing, only Linux), the runtime can takeadvantage ofperf map files to make Python functions visible to an externalprofiling tool (such asperf).A running process may create a file in the/tmp directory, which contains entriesthat can map a section of executable code to a name. This interface is described in thedocumentation of the Linux Perf tool.

In Python, these helper APIs can be used by libraries and features that relyon generating machine code on the fly.

Note that holding the Global Interpreter Lock (GIL) is not required for these APIs.

intPyUnstable_PerfMapState_Init(void)¶

This isUnstable API. It may change without warning in minor releases.

Open the/tmp/perf-$pid.map file, unless it’s already opened, and createa lock to ensure thread-safe writes to the file (provided the writes aredone throughPyUnstable_WritePerfMapEntry()). Normally, there’s no needto call this explicitly; just usePyUnstable_WritePerfMapEntry()and it will initialize the state on first call.

Returns0 on success,-1 on failure to create/open the perf map file,or-2 on failure to create a lock. Checkerrno for more informationabout the cause of a failure.

intPyUnstable_WritePerfMapEntry(constvoid*code_addr,unsignedintcode_size,constchar*entry_name)¶

This isUnstable API. It may change without warning in minor releases.

Write one single entry to the/tmp/perf-$pid.map file. This function isthread safe. Here is what an example entry looks like:

# address      size  name7f3529fcf759bpy::bar:/run/t.py

Will callPyUnstable_PerfMapState_Init() before writing the entry, ifthe perf map file is not already opened. Returns0 on success, or thesame error codes asPyUnstable_PerfMapState_Init() on failure.

voidPyUnstable_PerfMapState_Fini(void)¶

This isUnstable API. It may change without warning in minor releases.

Close the perf map file opened byPyUnstable_PerfMapState_Init().This is called by the runtime itself during interpreter shut-down. Ingeneral, there shouldn’t be a reason to explicitly call this, except tohandle specific scenarios such as forking.