Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 3db0a21

Browse files
mpagempage
authored
gh-91053: Add an optional callback that is invoked whenever a function is modified (#98175)
1 parent 20d9749 commit 3db0a21

File tree

9 files changed

+524
-0
lines changed

9 files changed

+524
-0
lines changed

‎Doc/c-api/function.rst

+60
Original file line numberDiff line numberDiff line change
@@ -118,3 +118,63 @@ There are a few functions specific to Python functions.
118118
must be a dictionary or ``Py_None``.
119119
120120
Raises :exc:`SystemError` and returns ``-1`` on failure.
121+
122+
123+
.. c:function:: int PyFunction_AddWatcher(PyFunction_WatchCallback callback)
124+
125+
Register *callback* as a function watcher for the current interpreter.
126+
Return an ID which may be passed to :c:func:`PyFunction_ClearWatcher`.
127+
In case of error (e.g. no more watcher IDs available),
128+
return ``-1`` and set an exception.
129+
130+
.. versionadded:: 3.12
131+
132+
133+
.. c:function:: int PyFunction_ClearWatcher(int watcher_id)
134+
135+
Clear watcher identified by *watcher_id* previously returned from
136+
:c:func:`PyFunction_AddWatcher` for the current interpreter.
137+
Return ``0`` on success, or ``-1`` and set an exception on error
138+
(e.g. if the given *watcher_id* was never registered.)
139+
140+
.. versionadded:: 3.12
141+
142+
143+
.. c:type:: PyFunction_WatchEvent
144+
145+
Enumeration of possible function watcher events:
146+
- ``PyFunction_EVENT_CREATE``
147+
- ``PyFunction_EVENT_DESTROY``
148+
- ``PyFunction_EVENT_MODIFY_CODE``
149+
- ``PyFunction_EVENT_MODIFY_DEFAULTS``
150+
- ``PyFunction_EVENT_MODIFY_KWDEFAULTS``
151+
152+
.. versionadded:: 3.12
153+
154+
155+
.. c:type:: int (*PyFunction_WatchCallback)(PyFunction_WatchEvent event, PyFunctionObject *func, PyObject *new_value)
156+
157+
Type of a function watcher callback function.
158+
159+
If *event* is ``PyFunction_EVENT_CREATE`` or ``PyFunction_EVENT_DESTROY``
160+
then *new_value* will be ``NULL``. Otherwise, *new_value* will hold a
161+
:term:`borrowed reference` to the new value that is about to be stored in
162+
*func* for the attribute that is being modified.
163+
164+
The callback may inspect but must not modify *func*; doing so could have
165+
unpredictable effects, including infinite recursion.
166+
167+
If *event* is ``PyFunction_EVENT_CREATE``, then the callback is invoked
168+
after `func` has been fully initialized. Otherwise, the callback is invoked
169+
before the modification to *func* takes place, so the prior state of *func*
170+
can be inspected. The runtime is permitted to optimize away the creation of
171+
function objects when possible. In such cases no event will be emitted.
172+
Although this creates the possitibility of an observable difference of
173+
runtime behavior depending on optimization decisions, it does not change
174+
the semantics of the Python code being executed.
175+
176+
If the callback returns with an exception set, it must return ``-1``; this
177+
exception will be printed as an unraisable exception using
178+
:c:func:`PyErr_WriteUnraisable`. Otherwise it should return ``0``.
179+
180+
.. versionadded:: 3.12

‎Include/cpython/funcobject.h

+49
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,55 @@ PyAPI_DATA(PyTypeObject) PyStaticMethod_Type;
131131
PyAPI_FUNC(PyObject *) PyClassMethod_New(PyObject *);
132132
PyAPI_FUNC(PyObject *) PyStaticMethod_New(PyObject *);
133133

134+
#define FOREACH_FUNC_EVENT(V) \
135+
V(CREATE) \
136+
V(DESTROY) \
137+
V(MODIFY_CODE) \
138+
V(MODIFY_DEFAULTS) \
139+
V(MODIFY_KWDEFAULTS)
140+
141+
typedef enum {
142+
#define DEF_EVENT(EVENT) PyFunction_EVENT_##EVENT,
143+
FOREACH_FUNC_EVENT(DEF_EVENT)
144+
#undef DEF_EVENT
145+
} PyFunction_WatchEvent;
146+
147+
/*
148+
* A callback that is invoked for different events in a function's lifecycle.
149+
*
150+
* The callback is invoked with a borrowed reference to func, after it is
151+
* created and before it is modified or destroyed. The callback should not
152+
* modify func.
153+
*
154+
* When a function's code object, defaults, or kwdefaults are modified the
155+
* callback will be invoked with the respective event and new_value will
156+
* contain a borrowed reference to the new value that is about to be stored in
157+
* the function. Otherwise the third argument is NULL.
158+
*
159+
* If the callback returns with an exception set, it must return -1. Otherwise
160+
* it should return 0.
161+
*/
162+
typedef int (*PyFunction_WatchCallback)(
163+
PyFunction_WatchEvent event,
164+
PyFunctionObject *func,
165+
PyObject *new_value);
166+
167+
/*
168+
* Register a per-interpreter callback that will be invoked for function lifecycle
169+
* events.
170+
*
171+
* Returns a handle that may be passed to PyFunction_ClearWatcher on success,
172+
* or -1 and sets an error if no more handles are available.
173+
*/
174+
PyAPI_FUNC(int) PyFunction_AddWatcher(PyFunction_WatchCallback callback);
175+
176+
/*
177+
* Clear the watcher associated with the watcher_id handle.
178+
*
179+
* Returns 0 on success or -1 if no watcher exists for the supplied id.
180+
*/
181+
PyAPI_FUNC(int) PyFunction_ClearWatcher(int watcher_id);
182+
134183
#ifdef __cplusplus
135184
}
136185
#endif

‎Include/internal/pycore_function.h

+2
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ extern "C" {
88
# error "this header requires Py_BUILD_CORE define"
99
#endif
1010

11+
#define FUNC_MAX_WATCHERS 8
12+
1113
struct _py_func_runtime_state {
1214
uint32_t next_version;
1315
};

‎Include/internal/pycore_interp.h

+6
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ extern "C" {
1717
#include "pycore_dict_state.h" // struct _Py_dict_state
1818
#include "pycore_exceptions.h" // struct _Py_exc_state
1919
#include "pycore_floatobject.h" // struct _Py_float_state
20+
#include "pycore_function.h" // FUNC_MAX_WATCHERS
2021
#include "pycore_genobject.h" // struct _Py_async_gen_state
2122
#include "pycore_gc.h" // struct _gc_runtime_state
2223
#include "pycore_list.h" // struct _Py_list_state
@@ -171,6 +172,11 @@ struct _is {
171172
// Initialized to _PyEval_EvalFrameDefault().
172173
_PyFrameEvalFunction eval_frame;
173174

175+
PyDict_WatchCallback dict_watchers[DICT_MAX_WATCHERS];
176+
PyFunction_WatchCallback func_watchers[FUNC_MAX_WATCHERS];
177+
// One bit is set for each non-NULL entry in func_watchers
178+
uint8_t active_func_watchers;
179+
174180
Py_ssize_t co_extra_user_count;
175181
freefunc co_extra_freefuncs[MAX_CO_EXTRA_USERS];
176182

‎Lib/test/test_capi/test_watchers.py

+93
Original file line numberDiff line numberDiff line change
@@ -336,5 +336,98 @@ def test_no_more_ids_available(self):
336336
self.add_watcher()
337337

338338

339+
class TestFuncWatchers(unittest.TestCase):
340+
@contextmanager
341+
def add_watcher(self, func):
342+
wid = _testcapi.add_func_watcher(func)
343+
try:
344+
yield
345+
finally:
346+
_testcapi.clear_func_watcher(wid)
347+
348+
def test_func_events_dispatched(self):
349+
events = []
350+
def watcher(*args):
351+
events.append(args)
352+
353+
with self.add_watcher(watcher):
354+
def myfunc():
355+
pass
356+
self.assertIn((_testcapi.PYFUNC_EVENT_CREATE, myfunc, None), events)
357+
myfunc_id = id(myfunc)
358+
359+
new_code = self.test_func_events_dispatched.__code__
360+
myfunc.__code__ = new_code
361+
self.assertIn((_testcapi.PYFUNC_EVENT_MODIFY_CODE, myfunc, new_code), events)
362+
363+
new_defaults = (123,)
364+
myfunc.__defaults__ = new_defaults
365+
self.assertIn((_testcapi.PYFUNC_EVENT_MODIFY_DEFAULTS, myfunc, new_defaults), events)
366+
367+
new_defaults = (456,)
368+
_testcapi.set_func_defaults_via_capi(myfunc, new_defaults)
369+
self.assertIn((_testcapi.PYFUNC_EVENT_MODIFY_DEFAULTS, myfunc, new_defaults), events)
370+
371+
new_kwdefaults = {"self": 123}
372+
myfunc.__kwdefaults__ = new_kwdefaults
373+
self.assertIn((_testcapi.PYFUNC_EVENT_MODIFY_KWDEFAULTS, myfunc, new_kwdefaults), events)
374+
375+
new_kwdefaults = {"self": 456}
376+
_testcapi.set_func_kwdefaults_via_capi(myfunc, new_kwdefaults)
377+
self.assertIn((_testcapi.PYFUNC_EVENT_MODIFY_KWDEFAULTS, myfunc, new_kwdefaults), events)
378+
379+
# Clear events reference to func
380+
events = []
381+
del myfunc
382+
self.assertIn((_testcapi.PYFUNC_EVENT_DESTROY, myfunc_id, None), events)
383+
384+
def test_multiple_watchers(self):
385+
events0 = []
386+
def first_watcher(*args):
387+
events0.append(args)
388+
389+
events1 = []
390+
def second_watcher(*args):
391+
events1.append(args)
392+
393+
with self.add_watcher(first_watcher):
394+
with self.add_watcher(second_watcher):
395+
def myfunc():
396+
pass
397+
398+
event = (_testcapi.PYFUNC_EVENT_CREATE, myfunc, None)
399+
self.assertIn(event, events0)
400+
self.assertIn(event, events1)
401+
402+
def test_watcher_raises_error(self):
403+
class MyError(Exception):
404+
pass
405+
406+
def watcher(*args):
407+
raise MyError("testing 123")
408+
409+
with self.add_watcher(watcher):
410+
with catch_unraisable_exception() as cm:
411+
def myfunc():
412+
pass
413+
414+
self.assertIs(cm.unraisable.object, myfunc)
415+
self.assertIsInstance(cm.unraisable.exc_value, MyError)
416+
417+
def test_clear_out_of_range_watcher_id(self):
418+
with self.assertRaisesRegex(ValueError, r"invalid func watcher ID -1"):
419+
_testcapi.clear_func_watcher(-1)
420+
with self.assertRaisesRegex(ValueError, r"invalid func watcher ID 8"):
421+
_testcapi.clear_func_watcher(8) # FUNC_MAX_WATCHERS = 8
422+
423+
def test_clear_unassigned_watcher_id(self):
424+
with self.assertRaisesRegex(ValueError, r"no func watcher set for ID 1"):
425+
_testcapi.clear_func_watcher(1)
426+
427+
def test_allocate_too_many_watchers(self):
428+
with self.assertRaisesRegex(RuntimeError, r"no more func watcher IDs"):
429+
_testcapi.allocate_too_many_func_watchers()
430+
431+
339432
if __name__ == "__main__":
340433
unittest.main()

‎Misc/NEWS.d/next/Core and Builtins/2022-10-05-11-44-52.gh-issue-91053.f5Bo3p.rst

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Optimizing interpreters and JIT compilers may need to invalidate internal
2+
metadata when functions are modified. This change adds the ability to
3+
provide a callback that will be invoked each time a function is created,
4+
modified, or destroyed.

0 commit comments

Comments
 (0)