Skip to content

Commit 3b8c269

Browse files
committed
test(v3/systray): reproduce macOS tray updates stalling while the menu is open
1 parent 4b1f348 commit 3b8c269

12 files changed

Lines changed: 1499 additions & 0 deletions

File tree

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# macOS: system tray icon and label updates are not delivered while the menu is open
2+
3+
A menu tray whose menu was opened through `ShowMenu()` / `OpenMenu()` stops
4+
updating. Every `SetIcon`, `SetTemplateIcon` and `SetLabel` call issued while
5+
the menu is open is delivered only after the menu is dismissed, and then all at
6+
once.
7+
8+
Tested on macOS 27.0 (26A428), arm64, against `v3` at `master` (`4b1f3484`).
9+
10+
## Run it
11+
12+
```
13+
go run . -interval 250ms -quit-after 12s -dismiss-after 6s
14+
```
15+
16+
The app builds against the checked out `v3` tree through the `replace`
17+
directive in `go.mod`. It needs no bundle and no permissions.
18+
19+
It creates a menu tray, alternates a circle and a square template icon plus a
20+
`tick N` label every interval, opens its own menu after `-open-menu-after`, and
21+
dismisses it with a posted Escape after `-dismiss-after`. Use
22+
`-open-menu-after 0 -quit-after 60s` to click the tray by hand instead.
23+
24+
Every tick also schedules two probe blocks on the main thread, one through
25+
`dispatch_async(dispatch_get_main_queue(), ...)` (what `systemtray_darwin.m`
26+
uses) and one through `CFRunLoopPerformBlock(kCFRunLoopCommonModes)` (what
27+
`mainthread_darwin.go` uses since #6026), and logs the current main run loop
28+
mode. The mode line proves a nested tracking loop was really active.
29+
30+
`-observe-title` reads the status item button title back from the main thread.
31+
It shows the visible label going stale, but walking `[NSApp windows]` during
32+
tracking often ends tracking after a second, so it is off by default.
33+
34+
## Result
35+
36+
Native menu tracking is entered from a main queue drain, so the queue is not
37+
drained again until the menu closes:
38+
39+
```
40+
trace showMenu enqueued on the main queue
41+
trace showMenu block started draining on the main queue
42+
trace showMenu entering mouseDown: (blocks for the menu lifetime)
43+
```
44+
45+
While that block sits in `mouseDown:`, run loop blocks keep arriving on time
46+
and queue blocks do not arrive at all:
47+
48+
```
49+
T+ 3.286s mode main run loop is in NSEventTrackingRunLoopMode at tick 13
50+
T+ 3.290s ran CFRunLoopPerformBlock(common) scheduled with tick 13, 0.004s late
51+
...
52+
T+ 8.293s ran CFRunLoopPerformBlock(common) scheduled with tick 33, 0.005s late
53+
trace menuDidClose:
54+
trace showMenu mouseDown: returned, menu dismissed
55+
trace systemTraySetIcon block ran
56+
trace systemTraySetLabel block ran
57+
T+ 8.321s ran dispatch_async(main queue) scheduled with tick 13, 5.029s late
58+
trace systemTraySetIcon block ran
59+
trace systemTraySetLabel block ran
60+
T+ 8.326s ran dispatch_async(main queue) scheduled with tick 14, 4.791s late
61+
```
62+
63+
Every `systemTraySetIcon` and `systemTraySetLabel` block for the tracking
64+
window runs in that burst. The visible icon and label are frozen for the whole
65+
time the menu is open, then jump to the newest value.
66+
67+
Expected: updates issued while the menu is open reach the tray while it is
68+
open, the way main thread work dispatched from Go does since #6026.
69+
70+
Full transcripts are in `logs/`.
71+
72+
## Variants
73+
74+
`trace.patch` adds the `trace` lines above to
75+
`v3/pkg/application/systemtray_darwin.m`. Apply it, rebuild, and the ordering
76+
of the click path is visible in the log.
77+
78+
`cfrunloop-fix.patch` routes all five `dispatch_async(dispatch_get_main_queue())`
79+
sites in `systemtray_darwin.m` through `CFRunLoopPerformBlock` plus
80+
`CFRunLoopWakeUp`, like `dispatchOnMainThread`. With it applied the stall is
81+
gone: during `NSEventTrackingRunLoopMode` the tray keeps counting and the title
82+
read-back follows the tick (`logs/patched-all-sites.log`).
83+
84+
Patching `showMenu` alone is not enough, and is worse: tracking then starts
85+
inside a run loop block callout, and blocks added afterwards do not run until
86+
that callout returns, so the Go caller blocks in `SetTemplateIcon` for the whole
87+
menu lifetime (`logs/patched-showmenu-only.log`). The all-sites patch is
88+
reported as data, not as a proposed fix.
89+
90+
## Not answered here
91+
92+
Whether a real mouse click starves the queue the same way. On macOS 27 the
93+
local event monitor added for #5919 can assign `statusItem.menu` directly, in
94+
which case AppKit may enter tracking from the event loop rather than from
95+
`showMenu`'s queue block. Run the traced build with `-open-menu-after 0`, click
96+
the tray by hand, hold the menu open a few seconds, and compare the trace order.
Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
diff --git a/v3/pkg/application/systemtray_darwin.m b/v3/pkg/application/systemtray_darwin.m
2+
index 3f0d8f6885..479f3bcaaf 100644
3+
--- a/v3/pkg/application/systemtray_darwin.m
4+
+++ b/v3/pkg/application/systemtray_darwin.m
5+
@@ -4,6 +4,16 @@
6+
#include "menuitem_darwin.h"
7+
#include "systemtray_darwin.h"
8+
9+
+// AppKit drains the main queue from the outermost run loop only, so anything
10+
+// dispatched there waits for a nested menu tracking or modal loop to finish.
11+
+// Scheduling on the run loop in common modes reaches the main thread either
12+
+// way, matching dispatchOnMainThread in mainthread_darwin.go.
13+
+static void systemTrayOnMainThread(dispatch_block_t block) {
14+
+ CFRunLoopRef loop = CFRunLoopGetMain();
15+
+ CFRunLoopPerformBlock(loop, kCFRunLoopCommonModes, block);
16+
+ CFRunLoopWakeUp(loop);
17+
+}
18+
+
19+
extern void systrayClickCallback(long, int);
20+
extern int systrayPreClickCallback(long, int);
21+
22+
@@ -76,7 +86,7 @@
23+
return;
24+
}
25+
// Set the label on the main thread
26+
- dispatch_async(dispatch_get_main_queue(), ^{
27+
+ systemTrayOnMainThread(^{
28+
NSStatusItem *statusItem = (NSStatusItem *)nsStatusItem;
29+
statusItem.button.title = [NSString stringWithUTF8String:label];
30+
free(label);
31+
@@ -91,7 +101,7 @@
32+
NSMutableAttributedString* attributedString = (NSMutableAttributedString*) label;
33+
34+
// Set the label on the main thread.
35+
- dispatch_async(dispatch_get_main_queue(), ^{
36+
+ systemTrayOnMainThread(^{
37+
// setAttributedTitle: copies the string, so drop the owning
38+
// reference we accumulated while building it.
39+
NSStatusItem *statusItem = (NSStatusItem *)nsStatusItem;
40+
@@ -167,7 +177,7 @@
41+
// Set the icon on the system tray
42+
void systemTraySetIcon(void* nsStatusItem, void* nsImage, int position, bool isTemplate) {
43+
// Set the icon on the main thread
44+
- dispatch_async(dispatch_get_main_queue(), ^{
45+
+ systemTrayOnMainThread(^{
46+
NSStatusItem *statusItem = (NSStatusItem *)nsStatusItem;
47+
NSImage *image = (NSImage *)nsImage;
48+
49+
@@ -185,7 +195,7 @@
50+
// Destroy system tray
51+
void systemTrayDestroy(void* nsStatusItem) {
52+
// Remove the status item from the status bar and its associated menu
53+
- dispatch_async(dispatch_get_main_queue(), ^{
54+
+ systemTrayOnMainThread(^{
55+
NSStatusItem *statusItem = (NSStatusItem *)nsStatusItem;
56+
StatusItemController *controller = (StatusItemController *)[statusItem target];
57+
if (controller.eventMonitor) {
58+
@@ -201,7 +211,7 @@
59+
// showMenu is used for programmatic OpenMenu() calls. Click-triggered
60+
// menus are handled by the event monitor installed in systemTrayNew.
61+
void showMenu(void* nsStatusItem, void *nsMenu) {
62+
- dispatch_async(dispatch_get_main_queue(), ^{
63+
+ systemTrayOnMainThread(^{
64+
NSStatusItem *statusItem = (NSStatusItem *)nsStatusItem;
65+
NSMenu *menu = (NSMenu *)nsMenu;
66+
StatusItemController *controller = (StatusItemController *)[statusItem target];
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
module systray-menu-tracking-repro
2+
3+
go 1.25.0
4+
5+
require github.com/wailsapp/wails/v3 v3.0.0
6+
7+
require (
8+
github.com/adrg/xdg v0.5.3 // indirect
9+
github.com/coder/websocket v1.8.14 // indirect
10+
github.com/go-ole/go-ole v1.3.0 // indirect
11+
github.com/godbus/dbus/v5 v5.2.2 // indirect
12+
github.com/mattn/go-colorable v0.1.14 // indirect
13+
github.com/mattn/go-isatty v0.0.20 // indirect
14+
golang.org/x/sys v0.46.0 // indirect
15+
)
16+
17+
replace github.com/wailsapp/wails/v3 => ../../v3
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
github.com/adrg/xdg v0.5.3 h1:xRnxJXne7+oWDatRhR1JLnvuccuIeCoBu2rtuLqQB78=
2+
github.com/adrg/xdg v0.5.3/go.mod h1:nlTsY+NNiCBGCK2tpm09vRqfVzrc2fLmXGpBLF0zlTQ=
3+
github.com/coder/websocket v1.8.14 h1:9L0p0iKiNOibykf283eHkKUHHrpG7f65OE3BhhO7v9g=
4+
github.com/coder/websocket v1.8.14/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg=
5+
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
6+
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
7+
github.com/go-json-experiment/json v0.0.0-20251027170946-4849db3c2f7e h1:Lf/gRkoycfOBPa42vU2bbgPurFong6zXeFtPoxholzU=
8+
github.com/go-json-experiment/json v0.0.0-20251027170946-4849db3c2f7e/go.mod h1:uNVvRXArCGbZ508SxYYTC5v1JWoz2voff5pm25jU1Ok=
9+
github.com/go-ole/go-ole v1.3.0 h1:Dt6ye7+vXGIKZ7Xtk4s6/xVdGDQynvom7xCFEdWr6uE=
10+
github.com/go-ole/go-ole v1.3.0/go.mod h1:5LS6F96DhAwUc7C+1HLexzMXY1xGRSryjyPPKW6zv78=
11+
github.com/godbus/dbus/v5 v5.2.2 h1:TUR3TgtSVDmjiXOgAAyaZbYmIeP3DPkld3jgKGV8mXQ=
12+
github.com/godbus/dbus/v5 v5.2.2/go.mod h1:3AAv2+hPq5rdnr5txxxRwiGjPXamgoIHgz9FPBfOp3c=
13+
github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
14+
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
15+
github.com/matryer/is v1.4.1 h1:55ehd8zaGABKLXQUe2awZ99BD/PTc2ls+KV/dXphgEQ=
16+
github.com/matryer/is v1.4.1/go.mod h1:8I/i5uYgLzgsgEloJE1U6xx5HkBQpAZvepWuujKwMRU=
17+
github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
18+
github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
19+
github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
20+
github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
21+
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
22+
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
23+
github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
24+
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
25+
golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
26+
golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
27+
golang.org/x/sys v0.46.0 h1:noSf2Fq6F8DBgS+LysIkx7rIExoNHJsxOAtPp4rthXw=
28+
golang.org/x/sys v0.46.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
29+
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
30+
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
## Wails version family
2+
3+
v3
4+
5+
## Exact Wails version
6+
7+
`master` at 4b1f3484 (v3.0.0-beta.24 plus #6026 and #5919)
8+
9+
## Operating System
10+
11+
macOS 27.0 (26A428), arm64
12+
13+
## Description
14+
15+
`systemtray_darwin.m` hops to the main thread with `dispatch_async(dispatch_get_main_queue(), ...)` in five places: `systemTraySetLabel` (:79), `systemTraySetANSILabel` (:94), `systemTraySetIcon` (:170), `systemTrayDestroy` (:188) and `showMenu` (:204).
16+
17+
`showMenu`'s block blocks in `[statusItem.button mouseDown:event]` for the whole lifetime of the menu. Because it blocks inside a main queue drain, the queue is not drained again until the menu is dismissed. Every tray update issued in that window therefore sits in the queue and is applied all at once at dismissal. The tray icon and label are frozen while the menu is open.
18+
19+
This is the same class of problem #6026 fixed for Go dispatched main thread work. `dispatchOnMainThread` now uses `CFRunLoopPerformBlock(kCFRunLoopCommonModes)` exactly because the main queue is not serviced during a nested loop. `SetIcon` takes two hops and only the first one was fixed: `setTemplateIcon` (systemtray_darwin.go:233) -> `dispatchOnMainThread` (delivered) -> `C.systemTraySetIcon` -> `dispatch_async` (starved).
20+
21+
`applySmartDefaults` (systemtray.go:143-154) installs `ShowMenu` as the right click handler for every menu tray, so this path is the normal one, not an edge case.
22+
23+
## To Reproduce
24+
25+
A self contained reproduction is available here:
26+
27+
REPRO_URL
28+
29+
```
30+
go run . -interval 250ms -quit-after 12s -dismiss-after 6s
31+
```
32+
33+
It creates a menu tray, alternates two template icons and a `tick N` label every 250 ms, opens its own menu through `OpenMenu()` after 3 s, and dismisses it with a posted Escape. Each tick also schedules one block through `dispatch_async(dispatch_get_main_queue(), ...)` and one through `CFRunLoopPerformBlock(kCFRunLoopCommonModes)`, and logs the current main run loop mode.
34+
35+
With the traced build (`trace.patch`), the essential failure is:
36+
37+
```console
38+
T+ 3.051s ran dispatch_async(main queue) scheduled with tick 12, 0.015s late
39+
trace showMenu enqueued on the main queue
40+
trace showMenu block started draining on the main queue
41+
trace showMenu entering mouseDown: (blocks for the menu lifetime)
42+
T+ 3.293s mode main run loop is in NSEventTrackingRunLoopMode at tick 13
43+
T+ 3.297s ran CFRunLoopPerformBlock(common) scheduled with tick 13, 0.005s late
44+
T+ 8.288s mode main run loop is in NSEventTrackingRunLoopMode at tick 33
45+
T+ 8.293s ran CFRunLoopPerformBlock(common) scheduled with tick 33, 0.005s late
46+
trace menuDidClose:
47+
trace showMenu mouseDown: returned, menu dismissed
48+
trace systemTraySetIcon block ran
49+
trace systemTraySetLabel block ran
50+
T+ 8.321s ran dispatch_async(main queue) scheduled with tick 13, 5.029s late
51+
trace systemTraySetIcon block ran
52+
trace systemTraySetLabel block ran
53+
T+ 8.326s ran dispatch_async(main queue) scheduled with tick 14, 4.791s late
54+
```
55+
56+
Between tick 13 and tick 33 the run loop blocks are delivered within 5 ms each, and not one queue block, `systemTraySetIcon` or `systemTraySetLabel` runs. All 21 of them run in a burst within 40 ms of dismissal.
57+
58+
Without the trace patch, the same run shows 26 queue blocks landing at dismissal, the oldest 6.2 s late:
59+
60+
```console
61+
T+ 9.296s ran dispatch_async(main queue) scheduled with tick 12, 6.208s late
62+
T+ 9.301s ran dispatch_async(main queue) scheduled with tick 13, 6.006s late
63+
...
64+
T+ 9.436s ran dispatch_async(main queue) scheduled with tick 33, 1.132s late
65+
```
66+
67+
Visually: the counter in the menu bar froze at 11 and jumped to 38 when the menu closed.
68+
69+
## Expected behaviour
70+
71+
`SetIcon`, `SetTemplateIcon` and `SetLabel` should reach the tray while its menu is open, the way main thread work dispatched from Go does since #6026. A tray that shows connection state or a live counter should not freeze for as long as the user keeps the menu open.
72+
73+
## Attempted Fixes
74+
75+
Routing all five sites in `systemtray_darwin.m` through `CFRunLoopPerformBlock(kCFRunLoopCommonModes)` plus `CFRunLoopWakeUp`, mirroring `dispatchOnMainThread`, removes the stall in our measurements: during `NSEventTrackingRunLoopMode` the tray keeps counting and a read back of `statusItem.button.title` follows the tick. The patch is included in the repro as `cfrunloop-fix.patch`.
76+
77+
We are not confident it is the right fix. Patching `showMenu` alone is worse: tracking then starts inside a run loop block callout, blocks added afterwards do not run until that callout returns, and the Go caller blocks in `SetTemplateIcon` for the whole menu lifetime. Transcripts for both variants are in the repro under `logs/`.
78+
79+
One question we could not settle: whether a real mouse click reaches tracking the same way. The local event monitor added in #5919 can assign `statusItem.menu` directly, in which case AppKit may enter tracking from the event loop rather than from `showMenu`'s queue block, and only the `ShowMenu()`/`OpenMenu()` path would stall. Our measurements cover the `OpenMenu()` path, which is also what the default right click handler calls.

0 commit comments

Comments
 (0)