1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
|
<span id="perfmaps"></span><h1>Support for Perf Maps</h1> <p>On supported platforms (as of this writing, only Linux), the runtime can take advantage of <em>perf map files</em> to make Python functions visible to an external profiling tool (such as <a class="reference external" href="https://perf.wiki.kernel.org/index.php/Main_Page">perf</a>). A running process may create a file in the <code>/tmp</code> directory, which contains entries that can map a section of executable code to a name. This interface is described in the <a class="reference external" href="https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/perf/Documentation/jit-interface.txt">documentation of the Linux Perf tool</a>.</p> <p>In Python, these helper APIs can be used by libraries and features that rely on generating machine code on the fly.</p> <p>Note that holding the Global Interpreter Lock (GIL) is not required for these APIs.</p> <dl class="c function"> <dt class="sig sig-object c" id="c.PyUnstable_PerfMapState_Init">
<code>int PyUnstable_PerfMapState_Init(void)</code> </dt> <dd>
<div class="unstable-c-api warning admonition"> <em>This is <a class="reference internal" href="stable#unstable-c-api"><span class="std std-ref">Unstable API</span></a>. It may change without warning in minor releases.</em>
</div> <p>Open the <code>/tmp/perf-$pid.map</code> file, unless it’s already opened, and create a lock to ensure thread-safe writes to the file (provided the writes are done through <a class="reference internal" href="#c.PyUnstable_WritePerfMapEntry" title="PyUnstable_WritePerfMapEntry"><code>PyUnstable_WritePerfMapEntry()</code></a>). Normally, there’s no need to call this explicitly; just use <a class="reference internal" href="#c.PyUnstable_WritePerfMapEntry" title="PyUnstable_WritePerfMapEntry"><code>PyUnstable_WritePerfMapEntry()</code></a> and it will initialize the state on first call.</p> <p>Returns <code>0</code> on success, <code>-1</code> on failure to create/open the perf map file, or <code>-2</code> on failure to create a lock. Check <code>errno</code> for more information about the cause of a failure.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyUnstable_WritePerfMapEntry">
<code>int PyUnstable_WritePerfMapEntry(const void *code_addr, unsigned int code_size, const char *entry_name)</code> </dt> <dd>
<div class="unstable-c-api warning admonition"> <em>This is <a class="reference internal" href="stable#unstable-c-api"><span class="std std-ref">Unstable API</span></a>. It may change without warning in minor releases.</em>
</div> <p>Write one single entry to the <code>/tmp/perf-$pid.map</code> file. This function is thread safe. Here is what an example entry looks like:</p> <pre data-language="c"># address size name
7f3529fcf759 b py::bar:/run/t.py
</pre> <p>Will call <a class="reference internal" href="#c.PyUnstable_PerfMapState_Init" title="PyUnstable_PerfMapState_Init"><code>PyUnstable_PerfMapState_Init()</code></a> before writing the entry, if the perf map file is not already opened. Returns <code>0</code> on success, or the same error codes as <a class="reference internal" href="#c.PyUnstable_PerfMapState_Init" title="PyUnstable_PerfMapState_Init"><code>PyUnstable_PerfMapState_Init()</code></a> on failure.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyUnstable_PerfMapState_Fini">
<code>void PyUnstable_PerfMapState_Fini(void)</code> </dt> <dd>
<div class="unstable-c-api warning admonition"> <em>This is <a class="reference internal" href="stable#unstable-c-api"><span class="std std-ref">Unstable API</span></a>. It may change without warning in minor releases.</em>
</div> <p>Close the perf map file opened by <a class="reference internal" href="#c.PyUnstable_PerfMapState_Init" title="PyUnstable_PerfMapState_Init"><code>PyUnstable_PerfMapState_Init()</code></a>. This is called by the runtime itself during interpreter shut-down. In general, there shouldn’t be a reason to explicitly call this, except to handle specific scenarios such as forking.</p> </dd>
</dl> <div class="_attribution">
<p class="_attribution-p">
© 2001–2023 Python Software Foundation<br>Licensed under the PSF License.<br>
<a href="https://docs.python.org/3.12/c-api/perfmaps.html" class="_attribution-link">https://docs.python.org/3.12/c-api/perfmaps.html</a>
</p>
</div>
|
