Prevent dynamic kernel construction during pending async work

[shreyaskommuri]

Summary

Fixes the minimum failure mode from #4359 by guarding `cudaq.make_kernel()` while async `sample_async` or `observe_async` work is pending. Instead of allowing unsafe concurrent access to the process-wide MLIR context and risking a segfault, CUDA-Q now raises an actionable `RuntimeError`.

This does not make dynamic kernel construction fully thread-safe; it documents and enforces the current constraint.

Changes

`python/cudaq/kernel/utils.py`

• Adds `_active_async_work_count` (protected by `threading.Lock`) and three helpers: `register_async_work`, `unregister_async_work`, `check_no_active_async_work`.

`python/cudaq/kernel/kernel_builder.py`

• `make_kernel()` calls `check_no_active_async_work()` before touching the global MLIR context.
• Adds a constraint note to the docstring.

`python/cudaq/runtime/sample.py`

• `AsyncSampleResult` now accepts `async_work_registered` to avoid double-counting when constructed from `sample_async`.
• `get()` unregisters async work in a `finally` block (correct even when `impl.get()` throws).
• `del` unregisters async work when the result is discarded without calling `get()`, preventing the counter from leaking and permanently blocking `make_kernel()`.
• `sample_async` registers before the async launch and unregisters on exception.

`python/cudaq/runtime/observe.py`

• Adds `_AsyncObserveResult` wrapping the C++ future with the same register/unregister lifecycle as `AsyncSampleResult`, including `del`.
• `observe_async` now returns `_AsyncObserveResult` instead of the raw C++ future.

`docs/sphinx/using/examples/multi_gpu_workflows.rst`

• Adds a `.. note::` documenting the build-before-dispatch constraint for `make_kernel`.

Testing

• `python3 -m py_compile` across all changed Python files — passes.
• `git diff --check` — no whitespace errors.
• Two new unit tests in `python/tests/builder/test_kernel_builder.py`:
  • `test_make_kernel_rejects_pending_async_work` — verifies `make_kernel` raises while an `AsyncSampleResult` is live, then succeeds after `get()`.
  • `test_make_kernel_allowed_after_gc_of_async_result` — verifies `make_kernel` succeeds after the result is dropped (`del`) without calling `get()`, exercising the `del` path.

Not tested

• Targeted pytest, because local Python 3.14 environment does not have `pytest` installed.
• GPU/mqpu reproducer, because this host is macOS CPU-only.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[shreyaskommuri]

Follow-up fixes on top of the original guard

After reviewing the initial implementation, I found two correctness bugs and one missing test case. These are now fixed in the same commit.

---

Bug 1 — `AsyncSampleResult.del` leaked the async-work count

Problem: If a caller discards an `AsyncSampleResult` without ever calling `.get()` (e.g. fire-and-forget, or an exception skips the call), `_active_async_work_count` stays > 0 permanently. Every subsequent `cudaq.make_kernel()` call in that process raises `RuntimeError`, which is worse than the segfault the guard was meant to prevent.

Fix: `del` now calls `unregister_async_work()` when `_async_work_registered` is still `True`. `unregister_async_work` already guards against going below zero, so a double-decrement is impossible.

---

Bug 2 — `_AsyncObserveResult` had no `del`

Problem: Same permanent-blockage issue on the observe path. The new `_AsyncObserveResult` class had `get()` correctly unregistering via `finally`, but nothing handled the GC path.

Fix: Added `del` with the same pattern as the sample fix.

---

New test — GC path

Added `test_make_kernel_allowed_after_gc_of_async_result` to `test_kernel_builder.py`. The existing `test_make_kernel_rejects_pending_async_work` only exercised the `.get()` path; this new test uses `del future` to exercise `del` directly.