Skip to content

GH-103082: Document PEP-669: Low Impact Monitoring for CPython #107772

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
markshannon merged 18 commits into from
Sep 5, 2023
Merged

GH-103082: Document PEP-669: Low Impact Monitoring for CPython #107772

Changes from 1 commit
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
22e5d83
Add what's new for PEP 669
markshannon Aug 4, 2023
6e5a435
Document sys.monitoring. First draft.
markshannon Aug 4, 2023
e373cbe
Fix sphinx errors
markshannon Aug 5, 2023
c648e70
Address review comments
markshannon Aug 28, 2023
ed94e2e
Merge branch 'main' into doc-669
markshannon Aug 28, 2023
c15022c
Use add more cross-references
markshannon Aug 28, 2023
5d54704
Fix note
markshannon Aug 28, 2023
7a500bd
Fix lint
markshannon Aug 28, 2023
bb4100c
Fix lint
markshannon Aug 28, 2023
181843e
Another attempt to fix the syntax
markshannon Aug 28, 2023
200e4a3
Remove double space
markshannon Sep 5, 2023
fb16167
Update Doc/library/sys.monitoring.rst
markshannon Sep 5, 2023
bfb3b1d
Update Doc/library/sys.monitoring.rst
markshannon Sep 5, 2023
0833922
Update Doc/library/sys.monitoring.rst
markshannon Sep 5, 2023
6364315
Update Doc/library/sys.monitoring.rst
markshannon Sep 5, 2023
4894333
Update Doc/library/sys.monitoring.rst
markshannon Sep 5, 2023
a943679
Apply suggestions from code review
markshannon Sep 5, 2023
002e744
Drop use of range(6) to avoid confusing sphinx
markshannon Sep 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Address review comments
  • Loading branch information
@markshannon
markshannon committed Aug 28, 2023
commit c648e70969d84679d265993c48e2cc0bec0aa197
29 changes: 15 additions & 14 deletions Doc/library/sys.monitoring.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@

.. note::

:mod:`sys.monitoring` is a namespace within the `sys` module,
:mod:`!sys.monitoring` is a namespace within the `sys` module,
not an independent module, so ``import sys.monitoring`` will not
work.

Expand All @@ -17,7 +17,7 @@ This namespace provides access to the functions and constants necessary to
activate and control event monitoring.

As programs execute, events occur that might be of interest to tools that
monitor execution. The :mod:`sys.monitoring` namespace provides means to
monitor execution. The :mod:`!sys.monitoring` namespace provides means to
receive callbacks when events of interest occur.

The monitoring API consists of three components:
Expand All @@ -40,14 +40,15 @@ Identifiers are integers in the range 0 to 5.

To register a tool::

sys.monitoring.use_tool_id(id: range(6), name:str) -> None
sys.monitoring.use_tool_id(id: range(6), name: str) -> None
sys.monitoring.free_tool_id(id: range(6)) -> None
sys.monitoring.get_tool(id: range(6)) -> str | None


``sys.monitoring.use_tool_id`` raises a ``ValueError`` if ``id`` is in use.
``sys.monitoring.get_tool`` returns the name of the tool if ``id`` is in use,
otherwise it returns ``None``.
:py:func:`sys.monitoring.use_tool_id` raises a ``ValueError``
if ``id`` is in use.
:py:func:`sys.monitoring.get_tool` returns the name of the tool
if ``id`` is in use, otherwise it returns ``None``.

All IDs are treated the same by the VM with regard to events, but the
following IDs are pre-defined to make co-operation of tools easier::
Expand Down Expand Up @@ -87,7 +88,7 @@ The following events are supported:

More events may be added in the future.

These events are attributes of the :mod:`sys.monitoring.events` namespace.
These events are attributes of the :mod:`!sys.monitoring.events` namespace.
Each event is represented as a power-of-2 integer constant.
To define a set of events, simply bitwise or the individual events together.
For example, to specify both ``PY_RETURN`` and ``PY_START`` events, use the
Expand All @@ -113,8 +114,8 @@ The local events are:
* BRANCH
* STOP_ITERATION

Ancilliary events
'''''''''''''''''
Ancillary events
''''''''''''''''

Ancillary events can be monitored like other events, but are controlled
by another event:
Expand Down Expand Up @@ -167,10 +168,10 @@ Setting events globally

Events can be controlled globally by modifying the set of events being monitored:

* ``sys.monitoring.get_events(tool_id:int)->int``
* ``sys.monitoring.get_events(tool_id: int) -> int``
Returns the ``int`` representing all the active events.

* ``sys.monitoring.set_events(tool_id:int, event_set: int)``
* ``sys.monitoring.set_events(tool_id: int, event_set: int)``
Activates all events which are set in ``event_set``.
Raises a ``ValueError`` if ``tool_id`` is not in use.

Expand All @@ -181,10 +182,10 @@ Per code object events

Events can also be controlled on a per code object basis:

* ``sys.monitoring.get_local_events(tool_id:int, code: CodeType)->int``
* ``sys.monitoring.get_local_events(tool_id: int, code: CodeType) -> int``
Returns all the local events for ``code``

* ``sys.monitoring.set_local_events(tool_id:int, code: CodeType, event_set: int)``
* ``sys.monitoring.set_local_events(tool_id: int, code: CodeType, event_set: int)``
Activates all the local events for ``code`` which are set in ``event_set``.
Raises a ``ValueError`` if ``tool_id`` is not in use.

Expand All @@ -211,7 +212,7 @@ Registering callback functions

To register a callable for events call::

sys.monitoring.register_callback(tool_id:int, event: int, func: Callable | None) -> Callable | None
sys.monitoring.register_callback(tool_id: int, event: int, func: Callable | None) -> Callable | None

If another callback was registered for the given ``tool_id`` and ``event``,
it is unregistered and returned.
Expand Down