Skip to content

Give folder listings their own thread pool - #116

Merged
omarchybot merged 5 commits into
omacom:mainfrom
OmarGonD:fix-listing-pool-and-showitem
Nov 16, 2026
Merged

omarchybot merged 5 commits into
omacom:mainfrom
OmarGonD:fix-listing-pool-and-showitem

Conversation

@OmarGonD

@OmarGonD OmarGonD commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Sometimes clicking a folder shows nothing, and the contents only appear after several more clicks (seen in large trees such as ~/Projects).

Folder listings, folder counts, previews and descriptions all ran on the global thread pool. Counting huge or slow subfolders can occupy every thread and queue the listing of the folder just opened behind them. Further clicks bump the generation and overtake the stuck work, which is why retrying eventually works.

Changes

  • Folder listings run on their own pool of 8 threads, FolderModel::listingPool(). Folder counts, previews and descriptions stay on the global pool.
  • The pool is never deleted, so a listing hung on a dead mount can't stop Folio quitting. A qAddPostRoutine gives running listings up to a second to finish at quit; one stuck longer can still reach destroyed statics.
  • Tests: folderModelListsWhileOtherWorkIsStuck fails with listings back on the global pool or without the fixed 8 threads. folderModelStopsReadingWhatsBeenOvertaken now constrains the listing pool, so it fails again if overtaken reads never stop.

The Q_INVOKABLE fix for Backend::showItem that was part of the first version landed separately in #136.

Testing

  • The full test suite passes.
  • The hang is intermittent and I haven't reproduced it deterministically with seconds-long counts (network mounts, cold disks), so the pool change rests on reading the code and on tests that hold the global pool.

🤖 Generated with Claude Code

Listings, folder counts, previews and descriptions all ran on the global
thread pool. Counting huge or slow subfolders could occupy every thread and
queue the listing of a folder just opened behind them, so clicks seemed to
do nothing until a few retries overtook the stuck work.

Listings now run on a dedicated pool, and folder counts on a small separate
one.

Backend::showItem was missing Q_INVOKABLE, so clicking a file in the columns
view threw "Property 'showItem' ... is not a function".

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@greptile-apps

greptile-apps Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge; the previous browsing blocker is fixed.

Summary

Folder reads use a dedicated pool with eight threads.

  • Folder listings keep working when other background jobs are busy.

No new actionable issues were found. The previous finding is fixed.

Reviews (4) · Last reviewed commit: "Say the listing pool's quit wait is a gr..." · Reviewed by Greptile

Comment thread src/foldermodel.cpp Resolved
@omarchybot omarchybot added the bug Something isn't working label Nov 15, 2026
@omarchybot

Copy link
Copy Markdown
Contributor

Thanks for this, @OmarGonD. Reviewed at 17abb37. Both bugs are real, still present on main, and fixed by this branch. It needs main brought in before it can go further, and there are a few smaller points below.

It conflicts with main. 274a2aa (#132, the file chooser) added filter to the capture list of the QtConcurrent::run call in FolderModel::reload(), the same line this branch moves onto listingPool(). src/backend.h merges cleanly. I haven't resolved the conflict; that's left to you. Neither fix has landed on main since this was opened: showItem is still not invokable at bb94499, and listings and counts still run on the global pool.

What was run, on a disposable Omarchy VM:

  • bin/build and bin/test at 17abb37: the suite passes.
  • showItem. In the real app on Hyprland, in columns view, clicking a file in the column that shows what's inside the selected folder does nothing on main, and the journal logs qrc:/FolderColumns.qml:224: TypeError: Property 'showItem' of object Backend is not a function. On this branch the same click opens that folder with the file selected. An offscreen test that calls backend.showItem(path) from QML fails on main, passes here, and fails again with only the Q_INVOKABLE taken out.
  • Listings. With every thread of the global pool held (4 on that VM), a FolderModel listing never arrived within 3 s on main. Here it arrived at once, and it got stuck again with only the listing moved back to the global pool. I also tried it with real work: after clicking through four folders that each hold a 600k-entry subfolder, the next listing waited about 60 ms on main for the leftover counts, and 0 ms here. On a local disk that's a short wait, so the multi-click hang from the description needs counts that take seconds, such as network mounts or cold disks. I couldn't reproduce that case on the VM.

Before (main): a click on x.txt in the right-hand column leaves the window on demo116 with alpha selected
After (this branch): the same click opens alpha with x.txt selected

Findings

  • tests/folio_tests.cpp, folderModelStopsReadingWhatsBeenOvertaken: this test shrinks QThreadPool::globalInstance() to one thread to prove an overtaken read stops. Listings no longer run on that pool, so it now passes even when reads never stop. With overtaken forced to false it still passes on this branch, while on main it fails. Stopping overtaken reads still matters here, because eight of them would fill the new pool too. The test needs to constrain the listing pool, which means making that pool reachable from the test (for example a static accessor on FolderModel). How to expose it is your call, so I haven't pushed anything.
  • Scope. These are two unrelated fixes. The Q_INVOKABLE is a one-line fix to a bug anyone hits in the default view, and it could land on its own today. The pool change is a design decision about threading. The two would be easier to review and land as separate pull requests. Neither one adds a test. The existing backendShowItemSelectsTheFile calls showItem from C++, so it passed while every click from QML failed. A check through QMetaObject::invokeMethod or QML would catch it.
  • The 2-thread counting pool isn't needed for the listing fix, which only needs listings moved off the global pool. It also caps folder counts for the whole process, in every window and every column, at two threads. A count blocked in readdir on a dead network mount now takes half that capacity for the rest of the session. Two such counts and no folder anywhere shows counts again, and Stop obsolete folder counts during directory traversal #119's predicate can't interrupt a read that's stuck in the kernel. On main it takes as many hung counts as there are cores. Leaving counts on the global pool, or sizing their pool like Thumbnails does (qBound(2, idealThreadCount() / 2, 6)), would avoid that.
  • Comments. The comment above listingPool() says counts stay "on the global one", but this same diff moves them to countingPool(). The comment in Backend::describe() (src/backend.cpp, "the threads the next folder is listed on") and the one on folderModelStopsReadingWhatsBeenOvertaken ("the next listing, the folder counts and file transfers all wait for") become stale too.
  • Exit. The new pools are never deleted or waited on. That follows Places::refreshDevices(), which does the same on purpose so a hung mount can't hold up a quit, and it does mean a quit no longer waits on a stuck listing. The difference is what the work touches. A listing still running at quit, for example one blocked on a slow mount that wakes up during teardown, goes on into kindForMime(), and the function-local static const QMimeDatabase there (src/foldermodel.cpp:238) is destroyed with the other statics. On main that can't happen, because ~QCoreApplication waits for the global pool. It's a narrow race and I didn't reproduce a crash, but the trade should at least be written down beside the pools, the way places.cpp explains its own.

Related. #119 stops a folder count partway through a folder once it has been overtaken. It shortens how long counts hold a thread and complements this branch rather than competing with it. #128 adds a D-Bus activation file so a cold Show in folder request starts Folio. That's a different failure: its path calls showItem from C++, which works without Q_INVOKABLE. #121's new test fills the global pool to keep a column listing waiting, so its meaning would change if this lands first.

Second opinion. Codex at medium effort and muse-wonder (via pi, thinking high) each reviewed the diff read-only. Both reached the same findings on scope, the counting pool, the neutralized test and the stale comments. They had the same brief, and the reviewers could read this session's notes, so that agreement isn't independent confirmation. muse-wonder found something new: the concrete teardown path through kindForMime()'s static QMimeDatabase, which I then checked against the source. It also pointed out that backendShowItemSelectsTheFile bypasses the meta-object system. Both also note that the fixed 8 listing threads aren't derived from the core count, and that eight blocked listings can still fill the new pool. Neither found a defect in the Q_INVOKABLE change.

Next step is yours: bring in main, and update the overtaken-read test. Splitting the two fixes is worth considering. After that it goes to the maintainer.

Listings stay on their own pool, now reachable as FolderModel::listingPool()
so the overtaken-read test can constrain it. The showItem Q_INVOKABLE moves
to its own pull request.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@OmarGonD OmarGonD changed the title Give folder listings their own thread pool; make showItem invokable Give folder listings their own thread pool Nov 15, 2026
@OmarGonD

Copy link
Copy Markdown
Contributor Author

Thanks for the review. Pushed:

  • Merged main (kept filter from Be other apps' Open and Save dialogs #132 on the listing call).
  • Counts are back on the global pool; the counting pool is gone.
  • FolderModel::listingPool() is now a public static, and folderModelStopsReadingWhatsBeenOvertaken constrains that pool. With overtaken forced to false it fails; before it passed.
  • New folderModelListsWhileTheGlobalPoolIsHeld: fails with listings moved back to the global pool, passes here.
  • Stale comments fixed, and the quit trade-off (no wait on a stuck listing; kindForMime()'s static QMimeDatabase) is written beside the pool.
  • The Q_INVOKABLE fix moved to Make Backend::showItem invokable from QML #136, with a test through QMetaObject::invokeMethod.

Not changed: the 8 listing threads are still a fixed number. Full suite passes.

The pool is still never deleted, so a listing hung on a dead mount can't stop Folio quitting, but a post routine now gives one that is just finishing a second before the statics it uses (QMimeDatabase) are destroyed. Once its model is gone a listing stops at the next entry, so that second covers everything but a hung read.

The pool takes Qt's default thread count instead of a fixed 8, the trade-off comment the post routine replaces is gone, and listingPool()'s declaration moves out of the middle of list()'s comment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread src/foldermodel.cpp Resolved
@omarchybot

Copy link
Copy Markdown
Contributor

Thanks, @OmarGonD. I re-reviewed 7b2bd9b and, at the maintainer's request to keep bug fixes as simple as they can be, pushed one commit on top: 6043f49.

Since my last comment. The main merge resolved the conflict and kept filter on the listing call. This branch also merges cleanly with today's main (bed490b, which includes #119). The counting pool is gone. folderModelStopsReadingWhatsBeenOvertaken constrains the listing pool again. The stale comments are fixed, and showItem now lives in #136. The diff no longer touches backend.h.

What 6043f49 changes:

  • The pool takes Qt's default thread count instead of a fixed 8. Neither number was measured, so this drops the magic number.
  • The five-line trade-off comment is replaced by code. A qAddPostRoutine gives a listing that's still finishing up to a second at quit, before statics such as kindForMime()'s QMimeDatabase are destroyed. Every model is gone by then, so a listing stops at its next entry. The pool is still never deleted, so a listing hung on a dead mount can't stop Folio quitting.
  • listingPool()'s declaration moved out of the middle of list()'s comment, and the comments are down to two lines each.

Against the branch's base, src/ goes from +24/-2 to +18/-2, and tests/ from +25/-4 to +24/-6.

What was run, on a disposable Omarchy VM:

  • bin/build and bin/test pass at 6043f49, and again with main (bed490b) merged in.
  • Each kept test fails without what it guards. With the listing put back on the global pool, folderModelListsWhileTheGlobalPoolIsHeld fails. With overtaken forced to false, folderModelStopsReadingWhatsBeenOvertaken fails. Both pass as pushed.
  • The post routine has no test. A teardown ordering can't be exercised from inside the test binary's own application.

Second opinion. Codex at medium effort and muse-wonder (via pi, thinking high) reviewed the simplified diff read-only. Both confirm the earlier findings are fixed or moot and the two tests are the shortest that bite. Both point out that the one-second wait narrows the teardown race but doesn't close it: a listing stalled for over a second that wakes during static teardown can still reach those statics. The only full fix is waiting indefinitely at quit, which brings back the hang on dead mounts, so the narrower race is the trade this branch takes. They could read this session's notes, so their agreement isn't independent confirmation.

Still open:

  • The pull request description still describes the first version: the 8 and 2 thread counts, the counting pool, and the showItem change. Please update it to match the branch.
  • The Test workflow on this branch is waiting for a maintainer to approve the run. It hasn't run yet.

dhh and others added 2 commits November 16, 2026 12:12
Without a set count the pool sizes itself to the CPU count, so on a one-CPU machine a single listing stuck in a filesystem call on a dead mount holds the only thread and every later listing, local folders included, waits behind it; changing folders can't interrupt a thread inside a syscall. The fixed 8 is what lets browsing survive a few stuck mounts. The test now also holds seven listing threads, and fails at a pool sized to fewer than 8 CPUs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A listing stuck past the one-second wait can still reach statics such as kindForMime()'s QMimeDatabase once they are destroyed; the comment said only that one just finishing gets a second, losing the caveat the author had written down. The stuck-work test also drains the listing pool first, so a leftover listing can't take the slot it relies on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Codex Medium <noreply@openai.com>
@omarchybot

Copy link
Copy Markdown
Contributor

Greptile's P1 on src/foldermodel.cpp:49 was right, and the regression was ours. My simplification in 6043f49 removed your setMaxThreadCount(8), so the listing pool sized itself to the CPU count. On a one-CPU machine, or a VM or cgroup limited to one, a single listing stuck in a filesystem call on a dead mount then holds the only thread. Every later listing waits behind it, local folders included, and changing folders can't interrupt a thread inside a syscall. Your fixed 8 is what kept browsing alive past a few stuck mounts, and two commits put it back:

  • b247370 restores setMaxThreadCount(8). folderModelListsWhileOtherWorkIsStuck (renamed from folderModelListsWhileTheGlobalPoolIsHeld) now also holds seven listing threads and checks that another listing still loads.
  • 0cfff70 restores the caveat from your comment that 6043f49 dropped: the one-second wait at quit is a grace period, and a listing stuck longer can still reach destroyed statics. It also has the test drain the listing pool before it starts.

What was run, on a disposable Omarchy VM with 4 CPUs:

  • bin/build and bin/test pass at 0cfff70.
  • The stuck-work test fails with the setMaxThreadCount(8) line removed, and again with the listing put back on the global pool.
  • folderModelStopsReadingWhatsBeenOvertaken still fails with overtaken forced to false.
  • The branch merges cleanly with today's main, which now includes Make Backend::showItem invokable from QML #136.

Second opinion. Codex at medium effort and muse-wonder (via pi, thinking high) reviewed the fix read-only. I asked them specifically whether any other part of 6043f49 weakened your design the same way. Both found that the dropped teardown caveat was the only reasoning lost, and it's now restored. Otherwise they found nothing. They agreed the fixed 8 is a better choice than scaling with the CPU count, since listings wait on filesystems rather than on CPUs. The one remaining difference from your version is that quitting can now take up to a second longer while a listing is stuck. A second round on 0cfff70 found nothing left to act on. They could read this session's notes, so their agreement isn't independent confirmation.

Still open:

  • The pull request description still describes the first version: the 2-thread counting pool and the showItem change, which has since landed as Make Backend::showItem invokable from QML #136. Please update it to match the branch.
  • The Test workflow on this branch needs a maintainer to approve the run.

@omarchybot
omarchybot merged commit 0b2636b into omacom:main Nov 16, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working ready verified

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants