fix(windows): reinstall low level keyboard hook if it gets removed by mcdurdin · Pull Request #15179 · keymanapp/keyman

mcdurdin · 2025-11-17T15:41:55Z

This change improves the stability of Keyman for Windows by monitoring the health of the low level keyboard hook. If keyman.exe is unresponsive at any time, Windows can silently uninstall its low level keyboard hook, which results in (at least) two problems:

Keyman's hotkeys stop working
A modifier key can become stuck, if it was pressed around the time Keyman became unresponsive.

The most common scenario in which Keyman can become unresponsive is high system load, e.g. rendering graphics, videoconference calls, compiling software.

Restarting Keyman always resolved both of these two issues in the past, but with this patch, I hope that this will no longer be necessary.

A related 'fakefreeze' project is included for simulating a keyman.exe hang by posting a wm_keyman_control:KMC_WATCHDOG_FAKEFREEZE message to it, which keyman.exe responds to by Sleep()ing for 5 seconds. While keyman.exe is freezing, any keystroke will cause the low level hook to be uninstalled by Windows.

Logging has been updated; look for "LowLevelHookWatchDog" in the log for related events.

One final small change in keyman32.cpp, as I refactored the WH_KEYBOARD_LL hook installation/uninstallation, was to always clear out hook variables when uninstalling a hook, because if the hook fails to uninstall, there's really nothing we can do about it anyway, and we probably shouldn't be trying again.

User Testing

TEST_KEYMAN: Please run through a basic test of Keyman keyboard input. Swap keyboards, type text, swap applications, verify that Keyman continues to run robustly. Confirm that modifier keys do not become 'stuck' while you are running tests. Please run this test for at least 5 minutes of normal usage.

TEST_FREEZE: Download and unzip the attached fakefreeze.zip. Setup hotkeys in Keyman (e.g. to show/hide On Screen Keyboard). Run fakefreeze.exe, and while the 5 second timer it shows is running, press any of the Keyman hotkeys. Note that the hotkey has no effect. After the timer finishes, press the hotkey again and verify that it now works again. (Note that by design, you may need to press another key before pressing the hotkey, after a freeze, as the first time you press a key, Keyman will detect that it needs to heal itself.)

fakefreeze.zip

This change improves the stability of Keyman for Windows by monitoring the health of the low level keyboard hook. If keyman.exe is unresponsive at any time, Windows can silently uninstall its low level keyboard hook, which results in (at least) two problems: * Keyman's hotkeys stop working * A modifier key can become stuck, if it was pressed around the time Keyman became unresponsive. The most common scenario in which Keyman can become unresponsive is high system load, e.g. rendering graphics, videoconference calls, compiling software. Restarting Keyman always resolved both of these two issues in the past, but with this patch, I hope that this will no longer be necessary. A related 'fakefreeze' project is included for simulating a keyman.exe hang by posting a `wm_keyman_control:KMC_WATCHDOG_FAKEFREEZE` message to it, which keyman.exe responds to by `Sleep()`ing for 5 seconds. While keyman.exe is freezing, any keystroke will cause the low level hook to be uninstalled by Windows. Logging has been updated; look for "LowLevelHookWatchDog" in the log for related events. One final small change in keyman32.cpp, as I refactored the WH_KEYBOARD_LL hook installation/uninstallation, was to always clear out hook variables when uninstalling a hook, because if the hook fails to uninstall, there's really nothing we can do about it anyway, and we probably shouldn't be trying again. Fixes: #8064

keymanapp-test-bot · 2025-11-17T15:42:28Z

User Test Results

Test specification and instructions

✅ TEST_KEYMAN (PASSED) (notes)
✅ TEST_FREEZE (PASSED) (notes)

Test Artifacts

Windows

mcdurdin · 2025-11-17T15:46:25Z

windows/src/engine/keyman32/LowLevelHookWatchDog.cpp

+void LowLevelHookWatchDog::HookIsAlive() {
+  // ULONGLONG Previous = LastLowLevelEventTick;
+  LastLowLevelEventTick = GetTickCount64();
+  // SendDebugMessageFormat("LowLevelHookWatchDog::HookIsAlive currentLL=%llu currentGM=%llu (lastLL=%llu)", LastLowLevelEventTick, LastGetMessageEventTick, Previous);


Leaving these debug messages in, but commented out, on purpose.

mcdurdin · 2025-11-17T15:48:24Z

windows/src/engine/keyman32/keymancontrol.h


 #define KMC_PROFILECHANGED  18  // 9.0.426.0   // I3933

+#define KMC_HINTRESPONSE        19       // 14.0 HIWORD(wParam) = ModalResult, lParam = hint enum


This line just to match KeymanControlMessages.pas

rc-swag

lgtm

I was initally thinking a in memory total freeze count might be useful for anaylytics and we could post to sentry if we reached a threshold. It might help see a patern.
However, reading the stackoverflow and the frequency you see hotkeys stop working it is not really needed.

mcdurdin · 2025-11-18T09:49:24Z

I was initally thinking a in memory total freeze count might be useful for anaylytics and we could post to sentry if we reached a threshold.

Yes, it would be a good idea to record an event on sentry in the event of a freeze. That would give us real world frequency. I will look at adding that as a follow-up to this PR.

Meng-Heng · 2025-11-19T06:39:01Z

Test Specifications

MacBook Bootcamp Windows 10
Applications: Notepad, Google Docs, and Chrome.

Prerequisites

Uninstall Keyman & Restart machine
Download & Install Keyman 19.0.163-alpha-test-15179

Test Results

TEST_KEYMAN (PASSED):

Launch Keyman and install 6 keyboards
- GFF Amharic
- IPA (SIL)
- US Basic
- Khmer Basic
- Ezidi
- Korean Dubeolsik
Open Keyman Configuration to set hotkeys for keyboard swap
Open Google Docs & Notepad
Start typing and switching to all of the keyboards while the OSK is open
The US Basic Keyman keyboard is selected during windows switching
Verified: Test type in Google Docs, Notepad, Chrome URL work as expected
Verified: The modifier keys do not become 'stuck' after a press and switch back to the default layer
Verified: Swap keyboards through hotkeys, shortcut key, and click work as expected
Verified: OSK appears correctly on key presses, layers switches, and keyboard swaps
Verified: IPA (SIL) keyboard's options for before and after work as expected.

TEST_FREEZE (PASSED):

Install and Run fakefreeze.exe
The timer runs 5s
Verifiedː The following keys does not work
- Shift + Alt + K (Switch ON/OFF OSK)
- Shift + Ctrl + E (Switch to US Basic keyboard)
- Shift + Ctrl + K (Switch to Khmer Basic keyboard)
After the timer ends
Verified: No additional key press is needed, the hotkeys & shortcut keys work immediately
- Shift + Alt + K (Switch ON/OFF OSK)
- Shift + Ctrl + E (Switch to US Basic keyboard)
- Shift + Ctrl + K (Switch to Khmer Basic keyboard)
- Win + Space
Verified:
- IPA Options setting remains the same
- Type in Notepad and Google Docs work as expected.

This change improves the stability of Keyman for Windows by monitoring the health of the low level keyboard hook. If keyman.exe is unresponsive at any time, Windows can silently uninstall its low level keyboard hook, which results in (at least) two problems: * Keyman's hotkeys stop working * A modifier key can become stuck, if it was pressed around the time Keyman became unresponsive. The most common scenario in which Keyman can become unresponsive is high system load, e.g. rendering graphics, videoconference calls, compiling software. Restarting Keyman always resolved both of these two issues in the past, but with this patch, I hope that this will no longer be necessary. A related 'fakefreeze' project is not included in this cherry-pick; see PR #15179 for this. Logging has been updated; look for "LowLevelHookWatchDog" in the log for related events. One final small change in keyman32.cpp, as I refactored the WH_KEYBOARD_LL hook installation/uninstallation, was to always clear out hook variables when uninstalling a hook, because if the hook fails to uninstall, there's really nothing we can do about it anyway, and we probably shouldn't be trying again. Fixes: #8064 Cherry-pick-of: #15179 Test-bot: skip Build-bot: skip

keyman-server · 2025-11-21T18:01:46Z

Changes in this pull request will be available for download in Keyman version 19.0.165-alpha

github-project-automation bot added this to Keyman Nov 17, 2025

github-project-automation bot moved this to Todo in Keyman Nov 17, 2025

github-actions bot added windows/ windows/engine/ fix labels Nov 17, 2025

keymanapp-test-bot bot added has-user-test user-test-required User tests have not been completed labels Nov 17, 2025

keymanapp-test-bot bot added this to the A19S16 milestone Nov 17, 2025

mcdurdin commented Nov 17, 2025

View reviewed changes

mcdurdin requested a review from rc-swag November 17, 2025 15:49

Merge branch 'master' into fix/windows/8064-low-level-hook-watch-dog

ef64af0

rc-swag approved these changes Nov 18, 2025

View reviewed changes

Meng-Heng self-assigned this Nov 19, 2025

chore(windows): use MultiThreaded library for fakefreeze

c391592

keymanapp-test-bot bot removed the user-test-required User tests have not been completed label Nov 19, 2025

mcdurdin mentioned this pull request Nov 21, 2025

feat(windows): record a sentry event when Keyman lowlevel hook is reinstalled #15218

Closed

mcdurdin merged commit 32db754 into master Nov 21, 2025
8 checks passed

mcdurdin deleted the fix/windows/8064-low-level-hook-watch-dog branch November 21, 2025 09:40

github-project-automation bot moved this from Todo to Done in Keyman Nov 21, 2025

mcdurdin mentioned this pull request Nov 21, 2025

fix(windows): reinstall low level keyboard hook if it gets removed 🍒 🏠 #15219

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(windows): reinstall low level keyboard hook if it gets removed#15179

fix(windows): reinstall low level keyboard hook if it gets removed#15179
mcdurdin merged 3 commits intomasterfrom
fix/windows/8064-low-level-hook-watch-dog

mcdurdin commented Nov 17, 2025 •

edited

Loading

Uh oh!

keymanapp-test-bot bot commented Nov 17, 2025 •

edited

Loading

Uh oh!

mcdurdin Nov 17, 2025

Uh oh!

mcdurdin Nov 17, 2025

Uh oh!

rc-swag left a comment

Uh oh!

mcdurdin commented Nov 18, 2025

Uh oh!

Meng-Heng commented Nov 19, 2025

Uh oh!

Uh oh!

keyman-server commented Nov 21, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		#define KMC_PROFILECHANGED 18 // 9.0.426.0 // I3933

		#define KMC_HINTRESPONSE 19 // 14.0 HIWORD(wParam) = ModalResult, lParam = hint enum

Uh oh!

Conversation

mcdurdin commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User Testing

Uh oh!

keymanapp-test-bot bot commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User Test Results

Test Artifacts

Uh oh!

mcdurdin Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

mcdurdin Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

rc-swag left a comment

Choose a reason for hiding this comment

Uh oh!

mcdurdin commented Nov 18, 2025

Uh oh!

Meng-Heng commented Nov 19, 2025

Test Specifications

Prerequisites

Test Results

Uh oh!

Uh oh!

keyman-server commented Nov 21, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mcdurdin commented Nov 17, 2025 •

edited

Loading

keymanapp-test-bot bot commented Nov 17, 2025 •

edited

Loading