# macOS: external display hotplug wedges the render thread in CVDisplayLinkStop

[cattyhouse]

Issue Description

this is an extended discussion of closed #14150 , the issue was not fully fixed by the mentioned PR #14171

macOS: external display hotplug wedges the render thread in CVDisplayLinkStop

Environment

• macOS 27.2, arm64 (Apple Silicon)
• Ghostty main at b40acce58, Metal renderer, vsync default (on)
• Two displays attached (built-in + external)

Repro

1. Open a window with a shell running.
2. Disconnect the external display, reconnect it.
3. Repeat. Occasionally close or switch tabs/windows in between.

No sleep/wake involved. It does not happen on the first toggle; it takes a few
rounds, and once it happens it is permanent.

Symptoms

• The window is dead: no redraw, the cursor stops blinking, and keyboard input
  is accepted by the app but never reaches the surface.
• The app is otherwise alive: the main thread runs its event loop normally
  (~97% of samples in mach_msg waiting for events).
• ~0% CPU, no crash report, macOS never offers a force-quit dialog. Only kill
  recovers.
• The render thread is at 100% of samples in CVDisplayLinkStop (two samples
  3 minutes apart):

renderer/Thread.zig threadMain
xev.Loop.run (kqueue callback dispatch)
...
syncDisplayLink                      (src/renderer/generic.zig)
CVDisplayLink::stop() + 148
  _pthread_cond_wait -> __psynch_cvwait

• Every other thread is idle, including both CVDisplayLink IO threads, which
  sit in CVDisplayLink::waitUntil (99.9% of samples). The blockage is not our
  output callback failing to return, and it is not the main thread.

Root cause: CVDisplayLinkStop never returns

From the disassembly of CoreVideo's CVDisplayLink::stop():

ldrb w8, [x19, #0x1d0]      ; running flag
cmp  w8, #1
b.ne <return -6672>         ; not running
strb wzr, [x19, #0x1d0]     ; clear running
...
blraa x8, x16               ; internal stop hook
ldr  x8, [x19, #0x128]      ; the link's IO thread
cmp  x0, x8                 ; is the caller the IO thread?
b.eq <done>
add  x0, x19, #0x88         ; condvar
add  x1, x19, #0x18         ; mutex
bl   _pthread_cond_wait     ; waits exactly once
b    <done>                 ; no loop, no predicate re-check

stop() signals the link's IO thread and then waits once, with no predicate
re-check, for the acknowledgement. Measured while wedged: the render thread
waits on a condvar at one address, while both CVDisplayLink IO threads wait
on a condvar at a different address and stay in waitUntil. The handshake
never completes, so the call never returns.

The link is created with CVDisplayLinkCreateWithActiveCGDisplays(), and there
is one IO thread per active display, which is why display hotplug is what
triggers it.

How it reaches that call, and why the timing looks random

A display change sends the new display id to the render thread
(windowDidChangeScreen -> ghostty_surface_set_display_id ->
.macos_display_id mailbox message -> setMacOSDisplayID ->
syncDisplayLink). syncDisplayLink stops the display link on any frame with
nothing to draw, so the stop is a routine idle-path call, not a teardown-only
one.

Surface teardown is deferred, which decouples the freeze from the display
change: closing a tab registers an undo that strongly captures the tab's
SplitTree<Ghostty.SurfaceView> and releases it from a main-runloop Timer
after undo-timeout (default 5s, src/config/Config.zig). So the destruction
that ends up waiting on the wedge can land seconds after the hotplug, from an
unrelated timer.

One wedge is fatal for the surface because the call is on the render thread:
the thread never returns, so the surface never redraws and never drains the
mailbox messages that carry input.

This looks like a CoreVideo defect on this OS build rather than something
Ghostty can fix directly; the accompanying patch makes Ghostty stop depending
on CVDisplayLinkStop returning.

attached files

patch.md
reproduce.md

proposed fix , tested:

patch : main...cattyhouse:ghostty:patch/bound-surface-join

app : https://github.com/cattyhouse/ghostty/releases

Expected Behavior

see Issue Description

Actual Behavior

see Issue Description

Reproduction Steps

see Issue Description

Ghostty Logs

No response

Ghostty Version

see `Issue Description`

OS Version Information

see Issue Description

(Linux only) Display Server

None

(Linux only) Desktop Environment/Window Manager

No response

Minimal Ghostty Configuration

see `Issue Description`

Additional Relevant Configuration

No response

I acknowledge that:

• I have reviewed the FAQ and confirm that my issue is NOT among them.
• I have searched the Ghostty documentation and confirm there doesn't exist a configuration option that solves my issue.
• I have searched the Ghostty repository (both open and closed Discussions and Issues) and confirm this is not a duplicate of an existing issue or discussion.
• I have checked the "Preview" tab on all text fields to ensure that everything looks right, and have wrapped all configuration and code in code blocks with a group of three backticks (```) on separate lines.

[dwlf]

Another data point, on a build that includes #14171 but not #14691. This one is a whole-app hang, and the entry point is a window-occlusion change rather than focus, surface free or display ID.

Environment

• Ghostty 0081d4530 (build 18035), macOS 27.0.1 (26A434), Apple Silicon
• One display: Studio Display (5K)
• ~30 tabs, mostly long-running TUIs
• Last full wake from sleep at 14:16:49; hang noticed ~15:18. I don't know exactly when the renderer got stuck.

Symptoms: whole app frozen, 0% CPU, macOS never offered a force-quit dialog, kill was the only way out.

sample, 2 s, every thread pinned in 1173/1173 samples:

Main thread, blocked inside an occlusion notification:

_windowBecameOccluded (AppKit)
  -[NSWindow _setOcclusionStateIsVisible:]
    ... NSNotificationCenter post
      BaseTerminalController.windowDidChangeOcclusionState(_:)
        ghostty_surface_set_occlusion
          ??? (ghostty + 0x7982b0)
            ??? (ghostty + 0x53f818)
              __ulock_wait2

One renderer thread out of 36, stuck in CoreVideo:

renderer
  ??? (ghostty + 0x80cc68)
    ??? (ghostty + 0x7b27d8)
      ??? (ghostty + 0x83ad0c)
        ??? (ghostty + 0x811f1c)
          ??? (ghostty + 0x7e325c)
            ??? (ghostty + 0x7e4438)
              CVDisplayLink::stop() + 148
                _pthread_cond_wait -> __psynch_cvwait

Every io-reader thread (one per surface) also sat in __ulock_wait2 for the whole sample. The other renderers were idle in kevent64.

The binary has no symbols, so I can't prove which lock the main thread is waiting on. The shape matches the "renderer stuck in CVDisplayLinkStop → main thread blocks on its next message to that surface" pattern in #14361. The difference is that the triggering message here is .visible from ghostty_surface_set_occlusion. So occlusion is one more way into this, alongside set_focus, surface_free and macos_display_id. Any fix that keeps the main thread from blocking on a stuck renderer has to cover this path too.

Diagnosis and write-up were done with help from Claude (AI).

[cattyhouse]

confirm fixed by #14691