Converting to draft until #20168 is resolved

Thanks for working on this. A few high level thoughts:

• watchdog.cancellableExecute / CancellableCallThread.execute gain an optional bounded timeout / ccTimeout (default None = existing behaviour, byte-unchanged).

I don't think we should be introducing a configurable timeout here. watchdog is intended to centralise the management of hang detection and dynamically adjusted timeouts.

We deliberately use a longer timeout of 10 seconds (NORMAL_CORE_ALIVE_TIMEOUT) in the first instance because an app can legitimately take some time to respond to a query if it's under heavy load. While a much shorter timeout intuitively seems like it would make things better, it can make things worse on a heavily loaded or low end system if we fire lots of queries, cancel or abandon them before they're complete and then just fire off more queries. We could perhaps discuss changing this to 5 seconds, which I think matches the Windows hung window timeout. However, I think anything less is asking for a whole new class of problems. In addition, I think allowing callers to customise this ultimately increases complexity and introduces inconsistency, and makes problem diagnosis trickier.

Importantly, note that when a user switches apps, we drop the timeout to 0.5 seconds (MIN_CORE_ALIVE_TIMEOUT). Anything that was previously waiting 10 seconds will immediately stop waiting. This means that if a user switches apps in order to interact with another app, we should immediately start responding again, assuming that watchdog supports cancellation of the blocking call. This gives us the best of both worlds: we don't prematurely cancel calls that might just be taking a while, but a user can also get response back immediately when they switch away from the offending app to do something else.

• New dependency-free coreThreadProtection module: a near-zero-cost shared "an app hung recently" signal (noteAppHang / isHungModeActive).

We already have something similar in watchdog.isAttemptingRecovery. I would suggest using that or integrating any new functionality with it.

It's great that calls like UiaHasServerSideProvider are being moved to cancellableExecute. I've long hypothesised that this could improve hangs significantly, since we unfortunately don't have another watchdog mechanism to cancel them. I'm slightly concerned that we could end up growing a whole heap of abandoned background threads, but that should be mitigated somewhat by the fact that we don't execute anything at all if watchdog goes into recovery mode. There are other mitigations we could implement too, but I think it's best to start simpler here and scale up as needed, as increased complexity may introduce new classes of bugs.

• UIAHandler: timedUIAClientCall, a UIA-client jam breaker with exponential backoff (isUIAClientJammed / noteUIAClientJam).

Again, I wonder whether we should just be relying on watchdog here. Rather than introducing new timeouts, we have a simpler rule: execute via watchdog and let watchdog handle the timeouts and cancellation.

There's an assumption here that the response from UiaHasServerSideProvider will never (or rarely) change. That should usually be the case, but I think there might be cases where it isn't quite that clear; e.g. an app might still be initialising. If we do get this wrong, it really isn't great. At the very least, I'd suggest that this should be split out into a separate PR so it can be evaluated separately and reverted if needed.

As a practical example of where a short timeout is not necessarily better, I recall when I was first developing watchdog that I did indeed have it set much shorter. However, it caused problems like the focus not being reported when starting an app because apps are understandably a bit sluggish while they're first loading. IMO, NVDA being unresponsive for a few seconds in an unresponsive app is reasonable, as long as the user can switch apps, including accessing the Windows "not responding" dialog. On the other hand, NVDA failing to report things because it didn't wait long enough is not acceptable.

Thanks @jcsteh — this is really helpful, and I agree with the redirect. The watchdog already centralises this far better than the parallel machinery I had added. Reworking #20170 accordingly:

• Dropping the per-call ccTimeout. Leaning on watchdog's dynamic timeout — especially the drop to MIN_CORE_ALIVE_TIMEOUT on app-switch, which already gives the "user can always escape" guarantee — is the right model. cancellableExecute will be left unchanged.
• Dropping coreThreadProtection in favour of the existing watchdog.isAttemptingRecovery.
• Dropping the UIA jam breaker / exponential backoff — same reasoning: route through cancellableExecute and let watchdog own timeouts and cancellation.
• Keeping the part you were positive about: routing the blocking UIA client calls (UiaHasServerSideProvider, ElementFromHandleBuildCache, etc.) and the Word object-model text call through cancellableExecute so the watchdog can actually cancel them.
• Splitting the UiaHasServerSideProvider result cache into its own PR so it can be evaluated and reverted independently, per your point about the result not always being stable while an app is still initialising.
• In the spirit of "start simpler, scale up as needed", I will also drop the central NVDAObject._getPropertyViaCache guard from this PR — the simple "route blocking calls through watchdog" change stands on its own, and the guard can be revisited later if it proves necessary.

I will force-push the simplified branch to this PR shortly. Thanks again for the watchdog context — the app-switch timeout-drop in particular reframes the whole thing.

Do we have evidence that ElementFromPointBuildCache and getFocusedElementBuildCache do not respect the UIA ConnectionRecoveryBehaviorOptions_Enabled option? UiaHasServerSideProvider can't respect this option because it is a free function, not a method on an IUIAutomation client interface, and I've definitely seen it show up in NVDA frozen stack logs. Have we definitely seen ElementFromPointBuildCache and getFocusedElementBuildCache show up in frozen stacks?

Good question — and checking my own frozen-stack logs from this work, you're right to push back.

Across the debug logs I gathered while reproducing these hangs, the number of times each call appeared in a frozen-stack dump:

But the raw counts aren't really the deciding factor. The more important point is the one you raised: the ElementFrom*BuildCache calls are comtypes COM methods on the IUIAutomation client interface, so the watchdog can already cancel them via CoCancelCall once its timeout elapses. They show up in frozen-stack dumps only because the dump is taken mid-freeze, before the watchdog's timeout fires — not because the watchdog is unable to reach them. UiaHasServerSideProvider, being a free function rather than a client-interface method, is the one case the watchdog genuinely can't otherwise cancel (and, as you note, it can't benefit from ConnectionRecoveryBehavior either). I don't have evidence the *BuildCache methods bypass ConnectionRecoveryBehavior, so wrapping them was redundant.

So I've narrowed the PR accordingly:

• Reverted the kwargsFromSuper changes entirely — NVDAObjects/UIA/__init__.py is no longer touched.
• Kept UiaHasServerSideProvider (UIAHandler) and the Word in-process RPC nvdaInProcUtils_winword_getTextInRange (winword) wrapped. Neither is a UIA client-interface method, so neither benefits from ConnectionRecoveryBehavior or the watchdog's existing CoCancelCall cancellation — both genuinely need cancellableExecute.

This keeps things minimal per your "start simpler, scale up as needed" steer. If ElementFromHandleBuildCache does later prove to need it, that can be a separate, evidence-backed change.

I've also moved the watchdog/exceptions imports to module level per @seanbudd's review.

Across the debug logs I gathered while reproducing these hangs, the number of times each call appeared in a frozen-stack dump:
Call Frozen-stack appearances
UiaHasServerSideProvider 37
ElementFromHandleBuildCache 12
getFocusedElementBuildCache 1
ElementFromPointBuildCache 0

Thanks, that's interesting info to have.

the ElementFrom*BuildCache calls are comtypes COM methods on the IUIAutomation client interface, so the watchdog can already cancel them via CoCancelCall once its timeout elapses.

Actually, I don't think that's true. CoCancelCall can only cancel COM calls for a server which implements a cancellation object. The standard COM marshaler does, so that means you can cancel COM calls to IAccessible, IAccessible2 and friends, Microsoft Office object model, etc. However, UI Automation has separate client and server interfaces and handles the IPC internally via named pipes. From the perspective of COM, UIA client is purely in-process, so it doesn't use the standard COM marshaler and I'm fairly sure it doesn't implement a cancellation object.

All of this is to say that watchdog very likely can't cancel these UIA calls. However, UIA ConnectionRecoveryBehavior should handle this if Microsoft have implemented it correctly. That's the big question: whether they have. Given past UIA core bugs, I don't have high confidence there.

This keeps things minimal per your "start simpler, scale up as needed" steer. If ElementFromHandleBuildCache does later prove to need it, that can be a separate, evidence-backed change.

That may well end up being the case, but yeah, I do believe the start simple, scale up approach is warranted here.

Even without cancellableExecute, there may also be some benefit in adding watchdog.isAttemptingRecovery guards in various places before we call methods. That way, we avoid the overhead of dispatching and then immediately cancelling them (and for UIA, perhaps a timeout, even a short one) when we know the watchdog is going to cancel them anyway. Perhaps we could have a watchdog.executeIfAlive wrapper or similar which immediately raises CallCancelled if isAttemptingRecovery. But again, I would suggest doing any of this in separate, smaller pull requests to mitigate risk and make tracking down any regressions easier (bisection, etc.).

Note that there are several other direct calls to nvdaInProcUtils methods we may also wish to wrap with cancellableExecute, but again, probably best to do this with evidence.

Thanks for the correction on CoCancelCall — you're right, I was conflating standard-marshaler cancellability with UIA's custom IPC (named pipes, not the standard marshaler, no cancellation object). The narrowing still stands on "start simple, scale up with evidence" grounds, and the empirical case for the *BuildCache calls is weak anyway given how rarely they showed up in our frozen stacks. If they do prove to need wrapping later, that can be its own evidence-backed PR.

Noted on the executeIfAlive / pre-dispatch isAttemptingRecovery guard idea — nice optimization to skip the dispatch-then-cancel overhead, and I agree separate small PRs are the safer path for any follow-ups.

Also acknowledged on the other nvdaInProcUtils_* calls — the winword wrap is a good template for them, and I'll watch for which ones actually show up in real hung-app traces before proposing more.

I've also addressed @seanbudd's user-facing changelog rewording and @Copilot's two points on winword.py (the CallCancelled path was indeed re-calling into hung Word via self.text — fixed to return [""] with an explanatory comment; and the log line is now log.debug rather than log.debugWarning to avoid spam during a persistent hang). Pushed as 714ca5d33.

hi @heath-toby
It is recommended to resolve the conflicts?