Debian Codegraph @

Doc/c-api/perfmaps.rst

raw
1 .. highlight:: c
2
3 .. _perfmaps:
4
5 Support for Perf Maps
6 ----------------------
7
8 On supported platforms (as of this writing, only Linux), the runtime can take
9 advantage of *perf map files* to make Python functions visible to an external
10 profiling tool (such as `perf <https://perf.wiki.kernel.org/index.php/Main_Page>`_).
11 A running process may create a file in the ``/tmp`` directory, which contains entries
12 that can map a section of executable code to a name. This interface is described in the
13 `documentation of the Linux Perf tool <https://git.kernel.org/pub/scm/linux/
14 kernel/git/torvalds/linux.git/tree/tools/perf/Documentation/jit-interface.txt>`_.
15
16 In Python, these helper APIs can be used by libraries and features that rely
17 on generating machine code on the fly.
18
19 Note that holding an :term:`attached thread state` is not required for these APIs.
20
21 .. c:function:: int PyUnstable_PerfMapState_Init(void)
22
23 Open the ``/tmp/perf-$pid.map`` file, unless it's already opened, and create
24 a lock to ensure thread-safe writes to the file (provided the writes are
25 done through :c:func:`PyUnstable_WritePerfMapEntry`). Normally, there's no need
26 to call this explicitly; just use :c:func:`PyUnstable_WritePerfMapEntry`
27 and it will initialize the state on first call.
28
29 Returns ``0`` on success, ``-1`` on failure to create/open the perf map file,
30 or ``-2`` on failure to create a lock. Check ``errno`` for more information
31 about the cause of a failure.
32
33 .. c:function:: int PyUnstable_WritePerfMapEntry(const void *code_addr, unsigned int code_size, const char *entry_name)
34
35 Write one single entry to the ``/tmp/perf-$pid.map`` file. This function is
36 thread safe. Here is what an example entry looks like::
37
38 # address size name
39 7f3529fcf759 b py::bar:/run/t.py
40
41 Will call :c:func:`PyUnstable_PerfMapState_Init` before writing the entry, if
42 the perf map file is not already opened. Returns ``0`` on success, or the
43 same error codes as :c:func:`PyUnstable_PerfMapState_Init` on failure.
44
45 .. c:function:: void PyUnstable_PerfMapState_Fini(void)
46
47 Close the perf map file opened by :c:func:`PyUnstable_PerfMapState_Init`.
48 This is called by the runtime itself during interpreter shut-down. In
49 general, there shouldn't be a reason to explicitly call this, except to
50 handle specific scenarios such as forking.