fix: keep async query callback closures alive to prevent use-after-free crash

[qevolg]

Problem

Running docs/examples/python/async_query_example.py (and any code using the native async query API) crashes with a segmentation fault:

Fatal Python error: Segmentation fault
Current thread ... (most recent call first):
  <no Python frame>

Root cause

taos_query_a, taos_query_a_with_reqid and taos_fetch_rows_a wrap the Python callback in a ctypes CFUNCTYPE closure that is created inline as a call argument, e.g.:

_libtaos.taos_query_a(connection, c_char_p(sql.encode("utf-8")), async_query_callback_type(callback), param)

These APIs are asynchronous: the native client only stores the function pointer and invokes it later, from a worker thread, when the server responds. But the temporary async_query_callback_type(callback) closure has no remaining Python reference once the wrapper returns, so it can be garbage-collected before the callback fires.

A gdb backtrace shows the crash precisely — the native taskWorkPool thread calls into a freed ctypes closure (callable=0x0):

Thread N "taskWorkPool" received signal SIGSEGV
#0  _CallPythonObject (... callable=0x0, converters=0x0 ...) callbacks.c:151
#1  closure_fcn (libffi)
#4  doRequestCallback        client/src/clientImpl.c:3164
#5  schedulerExecCb          ...

This is a use-after-free, independent of the query data and of the Python version (reproduced on CPython 3.12 with taospy 2.8.9 + native client 3.3.6.0).

Fix

Retain each in-flight callback closure in a module-level registry and release it right after it has been invoked, so the pointer stays valid for the native side while keeping memory usage bounded (the closure is freed once the async callback completes).

Verification

• async_query_example.py now exits 0 and returns rows correctly (previously: segfault / core dumped).
• Added an end-to-end check confirming the registry is empty before and after an async query (inflight before: 0 / inflight after : 0) — no leak.
• python -m py_compile passes; lines stay within the project's black line-length = 119.

Note / out of scope

taos_subscribe (legacy subscription API) uses the same inline-closure pattern (callback = subscribe_callback_type(callback)) and likely has the same latent issue, but its callback lifetime differs (fires repeatedly, tied to the subscription handle) and it is superseded by TMQ, so it is left out of this focused fix.

[gemini-code-assist]

Code Review

This pull request introduces a mechanism to retain references to asynchronous ctypes callbacks to prevent them from being garbage collected before the native client worker thread invokes them, which could lead to segmentation faults. The feedback suggests handling cases where the callback is None to avoid a TypeError when the native library invokes it, providing a code suggestion to return None immediately in such cases.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

If callback is passed as None, the original behavior of the ctypes wrapper was to pass a NULL pointer to the C library (since callback_type(None) evaluates to a NULL pointer).

With the current implementation, passing None will wrap it in wrapper, creating a valid function pointer. When the native library invokes this callback, it will attempt to call None(*args), resulting in a TypeError: 'NoneType' object is not callable inside the callback thread.

To preserve the original behavior and handle None callbacks defensively, we should check if callback is None and return None immediately.

Suggested change

	def _retain_async_callback(callback_type, callback):
	# type: (type, callable) -> object
	def wrapper(*args):
	try:
	callback(*args)
	finally:
	_inflight_async_callbacks.pop(token, None)
	closure = callback_type(wrapper)
	token = id(closure)
	_inflight_async_callbacks[token] = closure
	return closure
	def _retain_async_callback(callback_type, callback):
	# type: (type, callable) -> object
	if callback is None:
	return None
	def wrapper(*args):
	try:
	callback(*args)
	finally:
	_inflight_async_callbacks.pop(token, None)
	closure = callback_type(wrapper)
	token = id(closure)
	_inflight_async_callbacks[token] = closure
	return closure

[codecov-commenter]

Codecov Report

❌ Patch coverage is 16.66667% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.19%. Comparing base (73cd399) to head (01aff0e).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
taos/cinterface.py	16.66%	10 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #390      +/-   ##
==========================================
- Coverage   82.00%   80.19%   -1.81%     
==========================================
  Files          24       24              
  Lines        3717     3727      +10     
==========================================
- Hits         3048     2989      -59     
- Misses        669      738      +69     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.