https://github.com/python/cpython/commit/1dfe99ae3bed6cac01732b47bf7fa637abadf51b
commit: 1dfe99ae3bed6cac01732b47bf7fa637abadf51b
branch: main
author: Peter Bierma <[email protected]>
committer: ZeroIntensity <[email protected]>
date: 2026-03-14T22:58:35-04:00
summary:
gh-141004: Document `PyDTrace*` (GH-141856)
files:
M Doc/howto/instrumentation.rst
diff --git a/Doc/howto/instrumentation.rst b/Doc/howto/instrumentation.rst
index b3db1189e5dcbc..06c1ae40da5e67 100644
--- a/Doc/howto/instrumentation.rst
+++ b/Doc/howto/instrumentation.rst
@@ -341,6 +341,84 @@ Available static markers
.. versionadded:: 3.8
+C Entry Points
+^^^^^^^^^^^^^^
+
+To simplify triggering of DTrace markers, Python's C API comes with a number
+of helper functions that mirror each static marker. On builds of Python without
+DTrace enabled, these do nothing.
+
+In general, it is not necessary to call these yourself, as Python will do
+it for you.
+
+.. list-table::
+ :widths: 50 25 25
+ :header-rows: 1
+
+ * * C API Function
+ * Static Marker
+ * Notes
+ * * .. c:function:: void PyDTrace_LINE(const char *arg0, const char *arg1,
int arg2)
+ * :c:func:`!line`
+ *
+ * * .. c:function:: void PyDTrace_FUNCTION_ENTRY(const char *arg0, const
char *arg1, int arg2)
+ * :c:func:`!function__entry`
+ *
+ * * .. c:function:: void PyDTrace_FUNCTION_RETURN(const char *arg0, const
char *arg1, int arg2)
+ * :c:func:`!function__return`
+ *
+ * * .. c:function:: void PyDTrace_GC_START(int arg0)
+ * :c:func:`!gc__start`
+ *
+ * * .. c:function:: void PyDTrace_GC_DONE(Py_ssize_t arg0)
+ * :c:func:`!gc__done`
+ *
+ * * .. c:function:: void PyDTrace_INSTANCE_NEW_START(int arg0)
+ * :c:func:`!instance__new__start`
+ * Not used by Python
+ * * .. c:function:: void PyDTrace_INSTANCE_NEW_DONE(int arg0)
+ * :c:func:`!instance__new__done`
+ * Not used by Python
+ * * .. c:function:: void PyDTrace_INSTANCE_DELETE_START(int arg0)
+ * :c:func:`!instance__delete__start`
+ * Not used by Python
+ * * .. c:function:: void PyDTrace_INSTANCE_DELETE_DONE(int arg0)
+ * :c:func:`!instance__delete__done`
+ * Not used by Python
+ * * .. c:function:: void PyDTrace_IMPORT_FIND_LOAD_START(const char *arg0)
+ * :c:func:`!import__find__load__start`
+ *
+ * * .. c:function:: void PyDTrace_IMPORT_FIND_LOAD_DONE(const char *arg0,
int arg1)
+ * :c:func:`!import__find__load__done`
+ *
+ * * .. c:function:: void PyDTrace_AUDIT(const char *arg0, void *arg1)
+ * :c:func:`!audit`
+ *
+
+
+C Probing Checks
+^^^^^^^^^^^^^^^^
+
+.. c:function:: int PyDTrace_LINE_ENABLED(void)
+.. c:function:: int PyDTrace_FUNCTION_ENTRY_ENABLED(void)
+.. c:function:: int PyDTrace_FUNCTION_RETURN_ENABLED(void)
+.. c:function:: int PyDTrace_GC_START_ENABLED(void)
+.. c:function:: int PyDTrace_GC_DONE_ENABLED(void)
+.. c:function:: int PyDTrace_INSTANCE_NEW_START_ENABLED(void)
+.. c:function:: int PyDTrace_INSTANCE_NEW_DONE_ENABLED(void)
+.. c:function:: int PyDTrace_INSTANCE_DELETE_START_ENABLED(void)
+.. c:function:: int PyDTrace_INSTANCE_DELETE_DONE_ENABLED(void)
+.. c:function:: int PyDTrace_IMPORT_FIND_LOAD_START_ENABLED(void)
+.. c:function:: int PyDTrace_IMPORT_FIND_LOAD_DONE_ENABLED(void)
+.. c:function:: int PyDTrace_AUDIT_ENABLED(void)
+
+ All calls to ``PyDTrace`` functions must be guarded by a call to one
+ of these functions. This allows Python to minimize performance impact
+ when probing is disabled.
+
+ On builds without DTrace enabled, these functions do nothing and return
+ ``0``.
+
SystemTap Tapsets
-----------------
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
