Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -1286,6 +1286,10 @@ tree used to make the window queue behind it. `core.pacing.WINDOW` is a gate: `s
loop is about to wait (`aboutToBlock`). Every walk over the tree calls `pacing.give_way()` once per folder
(the scan's workers, `_add_up`, the analysis, clean-up, search, compare, export, each file hashed), which
waits while the gate is closed, at most `PAUSE_LIMIT` (50 ms) and never on the thread that closed it, so
nothing can hang on it. A pass over a list built from the tree paces too, every `node.PACE_EVERY` (256)
entries: `outermost(..., pace=give_way)` and clean-up's emptiness pass held the window 0.3 s (U-20261119-06).
A folder of more than 256 entries is added up, sorted (`scanner._sort_size_first`) and matched by clean-up
a page at a time too: one folder of 41,610 entries took 42 ms to add up and 100 ms to match (U-20261119-07).
nothing can hang on it. Emergency/destruction joins go through `scan_worker.wait_for`, which opens the
gate first. Normal whole-root scan replacement uses `worker_lifecycle.ThreadFence`: GUI-owned timers poll
`QThread.wait(0)` until owned scans/watchers/gentle work have fully joined, then dispatch only the latest
Expand Down Expand Up @@ -1406,6 +1410,9 @@ gives arcs as fractions of the circle, at most `RINGS` rings, arcs thinner than
`core.tree_layout.layout` returns at most 240 folder cards, expands branches and pages wide sibling lists;
the GUI caches that layout and scrolls/zooms it). It shows one at a time, the treemap first
(`charts.DEFAULT_MODE`); the mode and tree direction are saved in `chart_mode` / `tree_orientation`.
Chart tooltips answer Qt's `QEvent.ToolTip` through `chart_tooltip.show_chart_tip`, once the mouse rests;
a `QToolTip.showText` per hover change cost 35-45 ms. The bar chart paints only the exposed lines, repaints
just the changed hover/selection lines and asks the style for its folder icon once (U-20261119-04).
All views offer the same interface (`set_view_root`, `zoom_out`, `set_selected`, `invalidate`,
`node_clicked`, `view_root_changed`, `context_menu_requested`); when one moves to another folder the stack
moves the others and signals the page once, so the results page drives the stack as a single chart.
Expand Down Expand Up @@ -1455,6 +1462,9 @@ entry indexes use their one-based group number, avoiding per-cell Qt objects and
Only requested display/tooltip roles format sizes, dates and paths. Every captured row is immediately
addressable; group headers have no Node role, and entries remain selectable read-only leaves even
when their Nodes represent folders. Resets discard prior groups/icons and clear stale selections.
A view marked with `open_groups_when_shown` (the clean-up list) that is hidden while it is filled
opens its groups when it is next shown: Qt lays out every line of an opened group even in a hidden view,
and 56,321 empty folders took 0.6-0.7 s on the GUI thread while the charts were in use (U-20261119-05).
`fill` configures column geometry before expanding group roots only. For at least 500 groups with
uniform row heights and no supplied icon collection, it schedules one native delayed layout before the ordered root
expansions, so Qt can retain its normal signals while
Expand Down
98 changes: 98 additions & 0 deletions docs/updates/2026-11.md
Original file line number Diff line number Diff line change
Expand Up @@ -597,3 +597,101 @@
- **驗證**:測試在按 Enter 前移除 `activated` 的連線,模擬 macOS 的行為,因此在每個平台都會檢查這條路徑;未修正時本機也會失敗,修正後通過。`test_tree_paging.py`、`test_gui.py`、`test_chart_focus.py`、`test_tree_filter.py`、`test_list_transfer.py`:103 個通過(1 個已知的長路徑測試排除);`ruff check .`。
- **檔案**:`je_file_tree/gui/results_view.py`;`test/test_tree_paging.py`。
- **待辦**:無。

## U-20261119-04 · 2026-11-19 · 長條圖在滑鼠移動與捲動時卡頓 · #perf #gui #fix

- **原因**:使用者回報長條圖檢視仍會卡頓。在同一台機器上用 15 萬個檔案、30 個子資料夾的測試資料,於隱藏視窗中量測:
- 每次滑鼠移到另一列,就呼叫一次 `QToolTip.showText`。單獨量測,每次需要 35–45 ms,與文字內容無關,因為要移動並重畫原生的提示視窗。
- 每次重畫都畫滿全部 100 條長條,不只是畫面上看得到的約 15 條,每次約 19 ms。
- 每一列資料夾都向樣式要一次資料夾圖示(`standardIcon`)。這個呼叫在 Windows 上每次需要 41–52 ms,而且不會快取,所以在子資料夾很多的資料夾裡,每次重畫要花上秒。
- 從圖表點選項目時,檔案樹的 `show_rows_for`(U-20261119-02)就算項目已經在第一頁,也會在其餘 15 萬筆中搜尋一次,每次約 6.5 ms。
- **變更**:
- 新增 `gui/chart_tooltip.py`。四種圖表(矩形圖、長條圖、旭日圖、階層圖)改為回應 Qt 的 `QEvent.ToolTip`:滑鼠停下時才顯示提示,並附上該列或該區塊的範圍,滑鼠離開後由 Qt 自動隱藏。滑鼠移動時只更新醒目標示。
- 長條圖只畫重畫範圍內的列;醒目標示與選取變更時,只重畫有變化的兩列。資料夾圖示只向樣式要一次,樣式變更時才重新取得。每個項目的大小只讀一次。
- `show_rows_for` 先從已顯示的列裡找,只有不在頁面上時才搜尋其餘項目。
- **量測**:同一台機器、同一份測試資料,修正前 → 修正後:

| 操作 | 修正前 | 修正後 |
|---|---|---|
| 在 15 萬個檔案的資料夾上移動滑鼠 60 次 | 1.0–5.4 s | 23–32 ms |
| 點選長條 10 次 | 324–467 ms | 119–131 ms |
| 方向鍵 20 次 | 523–635 ms | 122–203 ms |
| 在 30 個子資料夾的資料夾上移動滑鼠 60 次 | 73 s | 27 ms |
| 在 30 個子資料夾的資料夾上捲動 20 次 | 34 s | 26 ms |
| 開啟 30 個子資料夾的資料夾 | 1.3 s | 16 ms |

- **行為差異**:圖表的提示在滑鼠停下片刻後才出現(Qt 的標準延遲;剛顯示過提示後,再停下只需約 20 ms),不再隨每次移動立即出現。
- **驗證**:新增 `test/test_chart_hover.py`(9 個案例)。未修正時,其中 6 個在本機失敗:移動滑鼠時不呼叫提示、只畫要求的列、圖示只取一次、選取只重畫兩列、矩形圖等待停下、真實提示事件。`test_tree_paging.py` 新增一個案例:頁面上的項目不搜尋其餘項目,未修正時失敗。相關測試共 336 個通過(排除 1 個已知的長路徑測試);`ruff check .` 通過。
- **未驗證**:只在隱藏視窗與測試資料上量測,沒有在回報者的磁碟與螢幕上量測。
- **檔案**:`je_file_tree/gui/chart_tooltip.py`、`bar_chart.py`、`treemap_widget.py`、`sunburst_widget.py`、`tree_diagram.py`、`tree_model.py`;`architecture.md`;`test/test_chart_hover.py`、`test/test_tree_paging.py`。
- **待辦**:無。

## U-20261119-05 · 2026-11-19 · 掃描結束後清理建議出現時,圖表卡住約 0.7 秒 · #perf #gui #fix

- **原因**:使用者回報掃描完瀏覽長條圖仍會卡頓。以真實資料(C:\Windows:20 萬個檔案、17 萬個資料夾;整個 C 槽:137 萬個檔案)在隱藏視窗中瀏覽長條圖,並用監看執行緒取樣主執行緒的呼叫堆疊:
- 0.2.14 的卡頓幾乎都來自 U-20261119-04 修正的問題(每列資料夾都重新取得資料夾圖示等)。在 WinSxS(29,244 個項目)中開啟資料夾要 5.2 秒,移動滑鼠 30 次要 180 秒;`dev` 上分別是 38 ms 與 28 ms。
- `dev` 上只剩一次停頓:掃描結束幾秒後,背景算完的清理建議填入清單,在 GUI 執行緒上停約 0.6–0.8 秒,正好是使用者開始瀏覽圖表的時候。C:\Windows 的「空資料夾」群組有 56,321 個項目;群組展開後,Qt 會為每一列排版,每列約呼叫 Python 模型兩次,即使「清理」分頁沒有顯示也一樣。現有的批次排版(U-20261017-32)只在群組數達 500 個以上時才啟用,這裡只有 3 個群組。
- **變更**:`grouped_list.open_groups_when_shown` 標記一個清單:清單在隱藏時填入,就先不展開群組,等下次顯示時才展開。清理建議清單使用這個標記;重複檔案清單維持原樣。選取、複製與匯出都不受影響:選取不需要展開,複製與匯出只處理目前顯示的分頁。
- **取捨**:等待的時間移到第一次開啟「清理」分頁時(C:\Windows:612 ms);之後切換分頁不會再展開一次。
- **量測**:同一台機器、C:\Windows:

| 項目 | 修正前 | 修正後 |
|---|---|---|
| 掃描結束後 8 秒內的最長停頓 | 660 ms | 60 ms |
| 清理建議填入(分頁隱藏時) | 693–722 ms | 3–5 ms |
| 第一次開啟「清理」分頁 | — | 612 ms |

- **驗證**:新增 `test/test_grouped_list_deferred.py`(4 個案例):有標記且隱藏的清單在顯示前不展開,重新填入時仍等待,顯示後展開且只展開一次;有標記但可見的清單立即展開;沒有標記的清單維持立即展開;清理建議清單有標記。清理、群組清單、重複檔案、複製與 GUI 等相關測試共 337 個通過(排除 1 個已知的長路徑測試,略過 1 個);`ruff check .` 通過。
- **未驗證**:只在隱藏視窗中量測,沒有在使用者的螢幕上量測。空資料夾更多的磁碟,開啟「清理」分頁時等待更久。
- **檔案**:`je_file_tree/gui/grouped_list.py`、`cleanup_panel.py`;`architecture.md`;`test/test_grouped_list_deferred.py`。
- **待辦**:無。

## U-20261119-06 · 2026-11-19 · 只拖動捲軸也會卡頓:清理建議背景工作沒有讓路給視窗 · #perf #gui #fix

- **原因**:使用者回報沒有開啟資料夾、只拖動捲軸也可能卡頓。從掃描開始到結束後 10 秒,每 15 ms 拖動一次捲軸(C:\Windows,20 萬個檔案、17 萬個資料夾),視窗停住超過門檻時,由 `faulthandler` 在 C 執行緒中輸出所有執行緒的呼叫堆疊,不需要取得直譯器鎖:
- **長條圖捲軸**:0.2.14 在 C:\Windows 根目錄(沒有開啟資料夾)每拖動一步要 3.1–4.4 秒,20 分鐘內掃描都沒有完成;原因是 U-20261119-04 修正的資料夾圖示問題,每次重畫都要重新取得圖示。`dev` 上最慢一步 53–65 ms。
- **檔案樹捲軸**:`dev` 上掃描結束後有一步停了 381 ms。當時主執行緒在 Qt 裡重畫,`CleanupWorker` 正在執行 `empty_folders` 的 `outermost`。`empty_folders` 第一次走訪時每個資料夾都會呼叫 `give_way()`,但之後判斷是否為空的那一輪,以及 `outermost` 的兩輪,都沒有讓路。不開視窗量測:172,165 個資料夾中有 121,225 個空資料夾,判斷要 163 ms,`outermost` 要 131 ms。這段時間工作執行緒一直佔用直譯器;視窗重畫時每次呼叫 Python 都要等它讓出直譯器鎖,所以整段時間視窗都停住(`core/pacing.py` 說明的情形)。
- **變更**:
- `node.outermost` 新增 `pace` 參數,兩輪都每 `PACE_EVERY`(256)個項目呼叫一次。
- `empty_folders` 判斷是否為空的那一輪同樣每 256 個資料夾讓路一次,呼叫 `outermost` 時傳入 `pace=give_way`。
- 每 256 個檢查一次:閘門檢查本身幾乎不花時間,兩次讓路之間的工作也只有零點幾毫秒。
- **量測**:同一台機器、C:\Windows,從掃描開始到結束後 10 秒持續拖動檔案樹的捲軸:

| 項目 | 修正前 | 修正後(兩次) |
|---|---|---|
| 掃描結束後最慢一步 | 381 ms | 98–104 ms |
| 掃描中最慢一步 | 155 ms | 34–153 ms |

- **未處理**:仍會偶爾出現約 100–150 ms 的停頓(每次一千多步中出現 1–2 次),發生在掃描收尾的 `_add_up`:WinSxS 有 29,244 個子項目,一次加總並排序,`list.sort` 無法中途讓路;以及清理建議比對檔案的 `file_key`。這兩處都只發生一次,也很短,所以這次不處理。→ 已在 U-20261119-07 處理。
- **驗證**:`test_pacing.py` 新增 2 個案例:`outermost` 兩輪都依 `PACE_EVERY` 呼叫 `pace`,結果不變;`empty_folders` 的走訪與判斷兩輪都會讓路,並經由 `outermost` 讓路。未修正時後者失敗。使用 `outermost` 或清理規則的相關測試共 358 個通過(排除 1 個已知的長路徑測試,略過 8 個);`ruff check .` 通過。
- **未驗證**:只在隱藏視窗中量測,沒有在使用者的螢幕上量測。
- **檔案**:`je_file_tree/core/node.py`、`core/cleanup.py`;`architecture.md`;`test/test_pacing.py`。
- **待辦**:無。

## U-20261119-07 · 2026-11-19 · 大型資料夾的加總、排序與清理比對也分頁讓路給視窗 · #perf #fix

- **原因**:U-20261119-06 留下的兩處偶發停頓(拖動檔案樹捲軸時約 100–150 ms,每次一千多步中出現 1–2 次)。不開視窗量測 C:\Windows 中 41,610 個項目的 `Manifests` 資料夾:
- 掃描收尾的 `_add_up` 每個資料夾讓路一次,但加總這個資料夾要 22 ms,排序要 20 ms,中間都不讓路。
- 清理建議的 `_visit` 同樣每個資料夾讓路一次,但比對這個資料夾的 41,610 個檔案(`file_key`)要 100 ms。
- 視窗同時在等直譯器鎖,所以實際停頓比上述時間更長。
- **變更**:
- `_add_up`:項目超過 `PACE_EVERY`(256)個的資料夾,改成每 256 個加總一次,中間讓路;排序改由 `_sort_size_first` 處理,每 256 個計算一次排序鍵,中間讓路,再依索引做穩定排序,結果與原本的 `list.sort` 相同。256 個以下的資料夾維持原本的做法。
- `_visit`:每比對 256 個項目讓路一次。
- **成本**:C:\Windows 的 172,164 個資料夾,`_add_up` 從 273–298 ms 增加到 334–347 ms(多 47–67 ms,約為掃描時間 6–17 秒的 0.5%)。其中 32 ms 是 60 個大型資料夾(共 187,427 個項目)分頁排序的成本。
- **量測**:同一台機器、C:\Windows,從掃描開始到結束後 10 秒持續拖動檔案樹捲軸,三次:

| 項目 | 修正前(U-20261119-06 後) | 修正後 |
|---|---|---|
| 超過 100 ms 的步數 | 每次 1–2 步(104–155 ms) | 0 |
| 掃描中最慢一步 | 34–153 ms | 85–96 ms |
| 掃描結束後最慢一步 | 98–115 ms | 58–90 ms |

長條圖捲軸:掃描中最慢 74 ms,掃描結束後最慢 29 ms。
- **驗證**:`test_pacing.py` 新增 5 個案例:
- 3、256、257、1000 個項目的資料夾:排序結果與原本相同(包含大小相同、名稱只差大小寫的項目),總計正確,讓路次數符合分頁。
- 1000 個檔案的資料夾,比對時每 256 個讓路一次。
- 未修正時,257、1000 與比對這 3 個案例失敗。
- 掃描器與清理相關的 128 個測試檔案共 1,656 個測試通過(排除 1 個已知的長路徑測試,略過 16 個);`ruff check .` 通過。
- **未驗證**:只在隱藏視窗中量測,沒有在使用者的螢幕上量測。
- **檔案**:`je_file_tree/core/scanner.py`、`core/cleanup.py`;`architecture.md`;`test/test_pacing.py`。
- **待辦**:無。
4 changes: 4 additions & 0 deletions docs/updates/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,10 @@ In the same commit: delete the item from `progress.md`, add a `#done` entry here

| ID | Date | Title | Tags | Batch |
|---|---|---|---|---|
| U-20261119-07 | 2026-11-19 | 大型資料夾的加總、排序與清理比對也分頁讓路給視窗 | #perf #fix | [2026-11](2026-11.md) |
| U-20261119-06 | 2026-11-19 | 只拖動捲軸也會卡頓:清理建議背景工作沒有讓路給視窗 | #perf #gui #fix | [2026-11](2026-11.md) |
| U-20261119-05 | 2026-11-19 | 掃描結束後清理建議出現時,圖表卡住約 0.7 秒 | #perf #gui #fix | [2026-11](2026-11.md) |
| U-20261119-04 | 2026-11-19 | 長條圖在滑鼠移動與捲動時卡頓 | #perf #gui #fix | [2026-11](2026-11.md) |
| U-20261119-03 | 2026-11-19 | macOS 上在「還有更多項目」列按 Enter 沒有反應 | #incident #fix #gui #macos | [2026-11](2026-11.md) |
| U-20261119-02 | 2026-11-19 | 大型資料夾在檔案樹中分頁顯示,展開與更新不再卡頓 | #perf #gui #ux #i18n | [2026-11](2026-11.md) |
| U-20261119-01 | 2026-11-19 | 圖表上切換上下層時按 Enter 會重新掃描整個根目錄 | #done #fix #gui #scan | [2026-11](2026-11.md) |
Expand Down
16 changes: 11 additions & 5 deletions je_file_tree/core/cleanup.py
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@
from typing import TYPE_CHECKING

from je_file_tree.core.coverage import Coverage, coverage_of
from je_file_tree.core.node import Node, outermost
from je_file_tree.core.node import PACE_EVERY, Node, outermost
from je_file_tree.core.pacing import give_way

if TYPE_CHECKING:
Expand Down Expand Up @@ -181,7 +181,9 @@ def _visit(folder: Node, parts: tuple[str, ...], matcher: _Matcher,
"""Put ``folder``'s matching entries in ``found``; returns the subfolders still to look into."""
names = _regular_names(folder)
deeper: list[tuple[Node, tuple[str, ...]]] = []
for child in folder.children:
for count, child in enumerate(folder.children):
if count and count % PACE_EVERY == 0:
give_way() # one folder's 41,610 files took 100 ms to match (U-20261119-07)
if child.is_link or child.error is not None or child in omitted:
continue
if child.is_dir:
Expand Down Expand Up @@ -229,13 +231,17 @@ def empty_folders(root: Node) -> list[Node]:
folder = stack.pop()
order.append(folder)
stack.extend(child for child in folder.children if child.is_dir and not child.is_link)
# Both passes below give way too: unpaced, they held the interpreter for 0.3 s after a scan of
# C:\Windows (172,165 folders) and the folder tree stalled 381 ms while scrolled (U-20261119-06).
empty: set[int] = set()
for folder in reversed(order): # children before their parents
for count, folder in enumerate(reversed(order)): # children before their parents
if count % PACE_EVERY == 0:
give_way()
if folder.error is None and all(child.is_dir and not child.is_link and id(child) in empty
for child in folder.children):
empty.add(id(folder))
return outermost(folder for folder in order if id(folder) in empty and folder is not root
and not (root.path is None and folder.parent is root))
return outermost((folder for folder in order if id(folder) in empty and folder is not root
and not (root.path is None and folder.parent is root)), pace=give_way)


class _Matcher:
Expand Down
18 changes: 13 additions & 5 deletions je_file_tree/core/node.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
from __future__ import annotations

import os
from collections.abc import Iterable, Iterator
from collections.abc import Callable, Iterable, Iterator
from dataclasses import dataclass, field

from je_file_tree.core.snapshot import snapshot_times
Expand Down Expand Up @@ -158,17 +158,25 @@ def replace_with(self, new: Node) -> None:
node = node.parent


def outermost(nodes: Iterable[Node]) -> list[Node]:
PACE_EVERY = 256 # entries between two calls of a ``pace`` step: a fraction of a millisecond of work


def outermost(nodes: Iterable[Node], *, pace: Callable[[], object] | None = None) -> list[Node]:
"""``nodes`` without repeats and without those inside another one of them, in the order given.

Moving or deleting a folder takes everything in it along, so this is the set to act on when
several entries were picked.
several entries were picked. A worker passes ``pace`` (``pacing.give_way``): called every
``PACE_EVERY`` entries, so a long list never holds up the window (U-20261119-06).
"""
chosen: dict[int, Node] = {}
for node in nodes:
for count, node in enumerate(nodes):
if pace is not None and count % PACE_EVERY == 0:
pace()
chosen.setdefault(id(node), node)
kept: list[Node] = []
for node in chosen.values():
for count, node in enumerate(chosen.values()):
if pace is not None and count % PACE_EVERY == 0:
pace()
above = node.parent
while above is not None and id(above) not in chosen:
above = above.parent
Expand Down
Loading
Loading