From ccd837ee648514044275c7577c5e1b81844fef13 Mon Sep 17 00:00:00 2001 From: JeffreyChen Date: Thu, 19 Nov 2026 19:36:27 +0800 Subject: [PATCH 1/4] Keep the charts responsive while the mouse moves over them Chart tooltips now wait for Qt's tooltip event instead of a showText call per hover change (35-45 ms each). The bar chart paints only the exposed lines, repaints just the lines a hover or selection changes, and asks the style for its folder icon once (41-52 ms per call on Windows). Selecting an entry already on a tree page no longer searches the rest of its folder. --- architecture.md | 3 + docs/updates/2026-11.md | 28 +++++ docs/updates/README.md | 1 + je_file_tree/gui/bar_chart.py | 78 +++++++++---- je_file_tree/gui/chart_tooltip.py | 24 ++++ je_file_tree/gui/sunburst_widget.py | 18 ++- je_file_tree/gui/tree_diagram.py | 33 ++++-- je_file_tree/gui/tree_model.py | 7 +- je_file_tree/gui/treemap_widget.py | 20 +++- test/test_chart_hover.py | 174 ++++++++++++++++++++++++++++ test/test_tree_paging.py | 14 +++ 11 files changed, 353 insertions(+), 47 deletions(-) create mode 100644 je_file_tree/gui/chart_tooltip.py create mode 100644 test/test_chart_hover.py diff --git a/architecture.md b/architecture.md index 4a336cd9..1631965f 100644 --- a/architecture.md +++ b/architecture.md @@ -1406,6 +1406,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. diff --git a/docs/updates/2026-11.md b/docs/updates/2026-11.md index 5fc2c6c9..b36588cb 100644 --- a/docs/updates/2026-11.md +++ b/docs/updates/2026-11.md @@ -597,3 +597,31 @@ - **驗證**:測試在按 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`。 +- **待辦**:無。 diff --git a/docs/updates/README.md b/docs/updates/README.md index 66f51d8a..61ad598e 100644 --- a/docs/updates/README.md +++ b/docs/updates/README.md @@ -70,6 +70,7 @@ In the same commit: delete the item from `progress.md`, add a `#done` entry here | ID | Date | Title | Tags | Batch | |---|---|---|---|---| +| 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) | diff --git a/je_file_tree/gui/bar_chart.py b/je_file_tree/gui/bar_chart.py index e25bcf9f..e7deb1fb 100644 --- a/je_file_tree/gui/bar_chart.py +++ b/je_file_tree/gui/bar_chart.py @@ -3,6 +3,10 @@ Easier to read exactly than the treemap: every entry has its name, its size and its share of the folder in plain text, and the bars are scaled to the largest entry so small differences show. Only the ``MAX_BARS`` largest entries get a bar; the rest share one line. + +Only the lines on screen are drawn, and a hover change repaints just the two lines it changes: with +every line drawn, each repaint took about 19 ms (measured 2026-11-19, 100 bars, U-20261119-04). The +folder icon is asked of the style once: each ``standardIcon`` call took 41-52 ms on Windows, per folder line. """ from __future__ import annotations @@ -10,12 +14,13 @@ import heapq from PySide6.QtCore import QEvent, QPoint, QRectF, QSize, Qt, Signal -from PySide6.QtGui import QColor, QContextMenuEvent, QMouseEvent, QPainter, QPaintEvent -from PySide6.QtWidgets import QStyle, QToolTip, QWidget +from PySide6.QtGui import QColor, QContextMenuEvent, QHelpEvent, QIcon, QMouseEvent, QPainter, QPaintEvent +from PySide6.QtWidgets import QStyle, QWidget from je_file_tree.core.analysis import category_of, extension_of from je_file_tree.core.formatting import AUTO_UNIT, format_count, format_share, format_size from je_file_tree.core.node import Node +from je_file_tree.gui.chart_tooltip import show_chart_tip from je_file_tree.gui.i18n import tr from je_file_tree.gui.treemap_widget import CATEGORY_COLOURS @@ -51,6 +56,7 @@ def __init__(self, parent: QWidget | None = None) -> None: self._rest: tuple[int, int] = (0, 0) # entries without a bar: count, size self._hover: int | None = None self._selected: Node | None = None + self._folder_icon: QIcon | None = None # the style's, asked for once (it is slow) # --- the same interface as the treemap -------------------------------- @@ -75,8 +81,15 @@ def zoom_out(self) -> None: def set_selected(self, node: Node | None) -> None: """Outline ``node`` when it has a bar.""" + if node is self._selected: + return + if self._rows is not None: + for old in (self._selected, node): + if old is not None and old in self._rows: + self._update_line(self._rows.index(old)) + else: + self.update() self._selected = node - self.update() def invalidate(self) -> None: """Read the folder again (after a scan step, a deletion or a rescan).""" @@ -114,30 +127,38 @@ def paintEvent(self, event: QPaintEvent) -> None: painter.drawText(self.rect(), Qt.AlignmentFlag.AlignCenter, tr("bars_empty_folder")) return largest = max(rows[0].accounted_size, 1) - for index, node in enumerate(rows): + height = self._row_height() + first = max(event.rect().top() // height, 0) + last = event.rect().bottom() // height + for index in range(first, min(last + 1, len(rows))): + node = rows[index] self._draw_row(painter, index, node, node.accounted_size / largest, root.accounted_size) count, size = self._rest - if count: + if count and first <= len(rows) <= last: label = tr("bars_more", count=format_count(count), size=format_size(size, self.unit)) self._draw_line(painter, len(rows), label, None, min(size / largest, 1.0), size, root.accounted_size) + def event(self, event: QEvent) -> bool: + """Qt: describe the bar under the mouse once it rests (``chart_tooltip``); a new style, a new icon.""" + if event.type() == QEvent.Type.StyleChange: + self._folder_icon = None + if event.type() == QEvent.Type.ToolTip and isinstance(event, QHelpEvent): + node = self.node_at(event.pos().y()) + if node is None: + return show_chart_tip(self, event, None) + index = int(event.pos().y() // self._row_height()) + return show_chart_tip(self, event, self._describe(node), self._line_rect(index).toRect()) + return super().event(event) + def mouseMoveEvent(self, event: QMouseEvent) -> None: - """Qt: highlight the bar under the mouse and describe it in a tooltip.""" + """Qt: highlight the bar under the mouse.""" node = self.node_at(event.position().y()) - index = None if node is None else int(event.position().y() // self._row_height()) - if index != self._hover: - self._hover = index - self.update() - if node is None: - QToolTip.hideText() - else: - QToolTip.showText(event.globalPosition().toPoint(), self._describe(node), self) + self._set_hover(None if node is None else int(event.position().y() // self._row_height())) super().mouseMoveEvent(event) def leaveEvent(self, event: QEvent) -> None: """Qt: drop the highlight when the mouse leaves.""" - self._hover = None - self.update() + self._set_hover(None) def mousePressEvent(self, event: QMouseEvent) -> None: """Qt: a left click selects the entry.""" @@ -160,6 +181,16 @@ def contextMenuEvent(self, event: QContextMenuEvent) -> None: # --- drawing ----------------------------------------------------------- + def _set_hover(self, index: int | None) -> None: + if index != self._hover: + for line in (self._hover, index): + if line is not None: + self._update_line(line) + self._hover = index + + def _update_line(self, index: int) -> None: + self.update(self._line_rect(index).toAlignedRect()) + def _row_height(self) -> int: return self.fontMetrics().height() + 10 @@ -167,10 +198,11 @@ def _current_rows(self) -> list[Node]: """The entries with a bar, the largest first (read from the folder when it changed).""" if self._rows is None: children = list(self._view_root.children) if self._view_root is not None else [] - self._rows = heapq.nlargest(MAX_BARS, children, key=lambda node: node.accounted_size) - rest = len(children) - len(self._rows) - total = sum(node.accounted_size for node in children) - self._rest = (rest, total - sum(node.accounted_size for node in self._rows)) + sizes = [node.accounted_size for node in children] # each size read once: a property call + largest = heapq.nlargest(MAX_BARS, range(len(children)), key=sizes.__getitem__) + self._rows = [children[index] for index in largest] + shown = sum(sizes[index] for index in largest) + self._rest = (len(children) - len(largest), sum(sizes) - shown) return self._rows def _draw_row(self, painter: QPainter, index: int, node: Node, fraction: float, total: int) -> None: @@ -190,8 +222,10 @@ def _draw_line(self, painter: QPainter, index: int, label: str, node: Node | Non icon_size = self.fontMetrics().height() text_colour = self.palette().text().color() if node is not None and node.is_dir: - icon = self.style().standardIcon(QStyle.StandardPixmap.SP_DirIcon) - icon.paint(painter, int(line.x() + 4), int(line.y() + (height - icon_size) / 2), icon_size, icon_size) + if self._folder_icon is None: + self._folder_icon = self.style().standardIcon(QStyle.StandardPixmap.SP_DirIcon) + self._folder_icon.paint(painter, int(line.x() + 4), int(line.y() + (height - icon_size) / 2), + icon_size, icon_size) name_rect = QRectF(line.x() + icon_size + 8, line.y(), name_width - icon_size - 8, height) painter.setPen(text_colour) align = Qt.AlignmentFlag.AlignVCenter diff --git a/je_file_tree/gui/chart_tooltip.py b/je_file_tree/gui/chart_tooltip.py new file mode 100644 index 00000000..f0fbcb86 --- /dev/null +++ b/je_file_tree/gui/chart_tooltip.py @@ -0,0 +1,24 @@ +"""Chart tooltips, shown through Qt's own tooltip event once the mouse rests (U-20261119-04). + +Measured 2026-11-19 on the development machine: one ``QToolTip.showText`` costs 35-45 ms, whatever +the text, because it moves and repaints the native tooltip window. The charts used to call it on +every hover change, so moving across the bar chart stalled about 90 ms per row. Qt sends +``QEvent.ToolTip`` only after the mouse rests (briefly once a tooltip has just been shown), so each +chart answers that event instead and the hover highlight alone follows the mouse. +""" + +from __future__ import annotations + +from PySide6.QtCore import QRect +from PySide6.QtGui import QHelpEvent +from PySide6.QtWidgets import QToolTip, QWidget + + +def show_chart_tip(widget: QWidget, event: QHelpEvent, text: str | None, area: QRect | None = None) -> bool: + """Answer a tooltip event: show ``text`` (hidden once the mouse leaves ``area``), or hide it for None.""" + if text is None: + QToolTip.hideText() + event.ignore() + else: + QToolTip.showText(event.globalPos(), text, widget, area if area is not None else QRect()) + return True diff --git a/je_file_tree/gui/sunburst_widget.py b/je_file_tree/gui/sunburst_widget.py index 3907766d..f951ec1c 100644 --- a/je_file_tree/gui/sunburst_widget.py +++ b/je_file_tree/gui/sunburst_widget.py @@ -14,6 +14,7 @@ from PySide6.QtGui import ( QColor, QContextMenuEvent, + QHelpEvent, QMouseEvent, QPainter, QPainterPath, @@ -22,12 +23,13 @@ QPixmap, QResizeEvent, ) -from PySide6.QtWidgets import QToolTip, QWidget +from PySide6.QtWidgets import QWidget from je_file_tree.core.formatting import AUTO_UNIT, format_share, format_size from je_file_tree.core.node import Node from je_file_tree.gui.node_text import node_name, node_path from je_file_tree.core.sunburst import Segment, layout, segment_at +from je_file_tree.gui.chart_tooltip import show_chart_tip from je_file_tree.gui.i18n import tr from je_file_tree.gui.age_colours import age_colour from je_file_tree.gui.colours import readable_ink @@ -145,17 +147,21 @@ def paintEvent(self, event: QPaintEvent) -> None: painter.setPen(pen) painter.drawPath(self._path(segment)) + def event(self, event: QEvent) -> bool: + """Qt: describe the arc under the mouse once it rests (``chart_tooltip``).""" + if event.type() == QEvent.Type.ToolTip and isinstance(event, QHelpEvent): + found = self.hit(event.pos().x(), event.pos().y()) + text = self._describe(found.node) if isinstance(found, Segment) else None + return show_chart_tip(self, event, text) + return super().event(event) + def mouseMoveEvent(self, event: QMouseEvent) -> None: - """Qt: highlight the arc under the mouse and describe it in a tooltip.""" + """Qt: highlight the arc under the mouse.""" found = self.hit(event.position().x(), event.position().y()) segment = found if isinstance(found, Segment) else None if segment is not self._hover: self._hover = segment self.update() - if segment is None: - QToolTip.hideText() - else: - QToolTip.showText(event.globalPosition().toPoint(), self._describe(segment.node), self) super().mouseMoveEvent(event) def leaveEvent(self, event: QEvent) -> None: diff --git a/je_file_tree/gui/tree_diagram.py b/je_file_tree/gui/tree_diagram.py index 178d531f..995093c7 100644 --- a/je_file_tree/gui/tree_diagram.py +++ b/je_file_tree/gui/tree_diagram.py @@ -4,14 +4,24 @@ import html -from PySide6.QtCore import QLineF, QPoint, QPointF, QRectF, QSize, Qt, Signal -from PySide6.QtGui import QContextMenuEvent, QKeyEvent, QMouseEvent, QPainter, QPaintEvent, QPen, QWheelEvent -from PySide6.QtWidgets import QToolTip, QWidget +from PySide6.QtCore import QEvent, QLineF, QPoint, QPointF, QRectF, QSize, Qt, Signal +from PySide6.QtGui import ( + QContextMenuEvent, + QHelpEvent, + QKeyEvent, + QMouseEvent, + QPainter, + QPaintEvent, + QPen, + QWheelEvent, +) +from PySide6.QtWidgets import QWidget from je_file_tree.core.formatting import AUTO_UNIT, format_count, format_share, format_size from je_file_tree.core.node import Node from je_file_tree.gui.node_text import node_name, node_path from je_file_tree.core.tree_layout import MAX_VISIBLE, PAGE_SIZE, DiagramItem, layout +from je_file_tree.gui.chart_tooltip import show_chart_tip from je_file_tree.gui.i18n import tr @@ -158,14 +168,15 @@ def mouseDoubleClickEvent(self, event: QMouseEvent) -> None: if item is not None and item.node is not None and item.node.is_dir: self.set_view_root(item.node) - def mouseMoveEvent(self, event: QMouseEvent) -> None: - """Describe the card under the mouse without reading file contents.""" - item = self.item_at(event.position().x(), event.position().y()) - if item is None: - QToolTip.hideText() - elif item.node is not None: - QToolTip.showText(event.globalPosition().toPoint(), html.escape(node_path(item.node)), self) - super().mouseMoveEvent(event) + def event(self, event: QEvent) -> bool: + """Qt: describe the card under the mouse once it rests (``chart_tooltip``), without reading files.""" + if event.type() == QEvent.Type.ToolTip and isinstance(event, QHelpEvent): + item = self.item_at(event.pos().x(), event.pos().y()) + if item is None or item.node is None: + return show_chart_tip(self, event, None) + return show_chart_tip(self, event, html.escape(node_path(item.node)), + self.card_rect(item).toAlignedRect()) + return super().event(event) def wheelEvent(self, event: QWheelEvent) -> None: """Ctrl+wheel zooms; plain wheel remains scroll-area panning.""" diff --git a/je_file_tree/gui/tree_model.py b/je_file_tree/gui/tree_model.py index 22a6f0cb..74458025 100644 --- a/je_file_tree/gui/tree_model.py +++ b/je_file_tree/gui/tree_model.py @@ -329,8 +329,11 @@ def show_rows_for(self, node: Node) -> None: child = node while child is not self._root and child.parent is not None: parent = child.parent - ordered, shown = self._ordered(parent), len(self._shown_rows(parent)) - 1 - if self.hidden_rows(parent): + rows = self._shown_rows(parent) + # A child already on a page is found among the shown rows; only one past them is searched + # for in the rest (U-20261119-04: searching every selection cost 6.5 ms per 150,000 entries). + if rows and isinstance(rows[-1], MoreRows) and self._row_of(child) < 0: + shown, ordered = len(rows) - 1, self._ordered(parent) try: position = ordered.index(child, shown) except ValueError: diff --git a/je_file_tree/gui/treemap_widget.py b/je_file_tree/gui/treemap_widget.py index 34ddc143..2f7b43e6 100644 --- a/je_file_tree/gui/treemap_widget.py +++ b/je_file_tree/gui/treemap_widget.py @@ -22,6 +22,7 @@ QBrush, QColor, QContextMenuEvent, + QHelpEvent, QMouseEvent, QPainter, QPaintEvent, @@ -30,13 +31,14 @@ QPixmap, QResizeEvent, ) -from PySide6.QtWidgets import QApplication, QToolTip, QWidget +from PySide6.QtWidgets import QApplication, QWidget from je_file_tree.core.analysis import category_of, extension_of from je_file_tree.core.formatting import AUTO_UNIT, format_count, format_share, format_size from je_file_tree.core.node import Node from je_file_tree.gui.node_text import node_name, node_path from je_file_tree.core.treemap import Rect, Tile, layout +from je_file_tree.gui.chart_tooltip import show_chart_tip from je_file_tree.gui.i18n import tr from je_file_tree.gui.age_colours import age_colour from je_file_tree.gui.colours import blend, readable_ink @@ -201,17 +203,23 @@ def paintEvent(self, event: QPaintEvent) -> None: self._outline(painter, selected, QColor("#000000"), 1) self._outline(painter, self._hover, QColor(self.palette().highlight().color()), 2) + def event(self, event: QEvent) -> bool: + """Qt: describe the tile under the mouse once it rests (``chart_tooltip``).""" + if event.type() == QEvent.Type.ToolTip and isinstance(event, QHelpEvent): + tile = self.tile_at(event.pos().x(), event.pos().y()) + if tile is None: + return show_chart_tip(self, event, None) + area = QRectF(tile.rect.x, tile.rect.y, tile.rect.width, tile.rect.height).toAlignedRect() + return show_chart_tip(self, event, self._describe(tile), area) + return super().event(event) + def mouseMoveEvent(self, event: QMouseEvent) -> None: - """Qt: highlight the tile under the mouse and describe it in a tooltip.""" + """Qt: highlight the tile under the mouse.""" point = event.position() tile = self.tile_at(point.x(), point.y()) if tile is not self._hover: self._hover = tile self.update() - if tile is None: - QToolTip.hideText() - else: - QToolTip.showText(event.globalPosition().toPoint(), self._describe(tile), self) super().mouseMoveEvent(event) def leaveEvent(self, event: QEvent) -> None: diff --git a/test/test_chart_hover.py b/test/test_chart_hover.py new file mode 100644 index 00000000..0e2d091f --- /dev/null +++ b/test/test_chart_hover.py @@ -0,0 +1,174 @@ +"""Moving the mouse over a chart stays cheap: tooltips wait for Qt's tooltip event (U-20261119-04).""" + +from __future__ import annotations + +from pathlib import Path + +import pytest +from PySide6.QtCore import QEvent, QPoint, QPointF, QRect, Qt +from PySide6.QtGui import QHelpEvent, QMouseEvent, QPixmap, QRegion +from PySide6.QtWidgets import QApplication, QProxyStyle, QStyle, QToolTip, QWidget + +from je_file_tree.core.scanner import scan +from je_file_tree.gui import bar_chart, chart_tooltip +from je_file_tree.gui.bar_chart import BarChartWidget +from je_file_tree.gui.sunburst_widget import SunburstWidget +from je_file_tree.gui.tree_diagram import TreeDiagramWidget +from je_file_tree.gui.treemap_widget import TreemapWidget + + +@pytest.fixture +def tips(monkeypatch: pytest.MonkeyPatch) -> list[tuple[str, QWidget, QRect]]: + """Every tooltip a chart asks for, instead of a real one (each costs tens of milliseconds).""" + shown: list[tuple[str, QWidget, QRect]] = [] + monkeypatch.setattr(chart_tooltip.QToolTip, "showText", + lambda _position, text, widget, area: shown.append((text, widget, area))) + monkeypatch.setattr(chart_tooltip.QToolTip, "hideText", lambda: shown.append(("", None, QRect()))) + return shown + + +def _move(widget: QWidget, point: QPoint) -> None: + QApplication.sendEvent(widget, QMouseEvent( + QEvent.Type.MouseMove, QPointF(point), QPointF(widget.mapToGlobal(point)), Qt.MouseButton.NoButton, + Qt.MouseButton.NoButton, Qt.KeyboardModifier.NoModifier)) + + +def _rest(widget: QWidget, point: QPoint) -> None: + QApplication.sendEvent(widget, QHelpEvent(QEvent.Type.ToolTip, point, widget.mapToGlobal(point))) + + +def _bars(sample_tree: Path) -> BarChartWidget: + chart = BarChartWidget() + chart.resize(500, 300) + chart.set_view_root(scan(sample_tree).root) + chart.grab() + return chart + + +def test_moving_over_the_bars_shows_no_tooltip_until_the_mouse_rests(qapp, sample_tree, tips): + chart = _bars(sample_tree) + line = chart._row_height() + for row in range(4): + _move(chart, QPoint(100, line * row + 3)) + assert tips == [], "a tooltip per hover change cost 35-45 ms" + assert chart._hover == 3 + _rest(chart, QPoint(100, line + 3)) + text, widget, area = tips[-1] + assert "photos" in text and widget is chart + assert area == chart._line_rect(1).toRect(), "Qt hides it once the mouse leaves the bar" + _rest(chart, QPoint(100, line * 30)) + assert tips[-1][0] == "", "below the bars the tooltip goes away" + chart.deleteLater() + + +def test_the_bars_draw_only_the_lines_asked_for(qapp, sample_tree, monkeypatch): + chart = _bars(sample_tree) + drawn: list[int] = [] + original = BarChartWidget._draw_row + + def counted(self, painter, index, *rest): + drawn.append(index) + original(self, painter, index, *rest) + monkeypatch.setattr(BarChartWidget, "_draw_row", counted) + line = chart._row_height() + picture = QPixmap(chart.size()) + chart.render(picture, QPoint(), QRegion(0, line, 500, line)) + assert drawn == [1], "a hover change repaints its own line, not all of them" + drawn.clear() + chart.render(picture) + assert drawn == [0, 1, 2, 3] + chart.deleteLater() + + +class _CountingStyle(QProxyStyle): + def __init__(self) -> None: + super().__init__("Fusion") + self.asked = 0 + + def standardIcon(self, icon, option=None, widget=None): # noqa: N802 - Qt override + if icon == QStyle.StandardPixmap.SP_DirIcon: + self.asked += 1 + return super().standardIcon(icon, option, widget) + + +def test_the_folder_icon_is_asked_of_the_style_once(qapp, sample_tree): + chart = _bars(sample_tree) + style = _CountingStyle() + chart.setStyle(style) + for _ in range(3): + chart.grab() + assert style.asked == 1, "each standardIcon call took 41-52 ms on Windows, per folder line and paint" + other = _CountingStyle() + chart.setStyle(other) + chart.grab() + assert other.asked == 1, "a new style draws its own icon" + chart.deleteLater() + + +def test_the_bar_selection_repaints_only_its_lines(qapp, sample_tree, monkeypatch): + chart = _bars(sample_tree) + asked: list[QRect] = [] + monkeypatch.setattr(BarChartWidget, "update", lambda self, *area: asked.append(area[0] if area else None)) + rows = chart._current_rows() + chart.set_selected(rows[1]) + chart.set_selected(rows[2]) + chart.set_selected(rows[2]) + assert asked == [chart._line_rect(1).toAlignedRect(), chart._line_rect(1).toAlignedRect(), + chart._line_rect(2).toAlignedRect()] + chart.deleteLater() + + +def test_the_bars_rest_line_still_counts_the_entries_without_a_bar(qapp, sample_tree, monkeypatch): + monkeypatch.setattr(bar_chart, "MAX_BARS", 2) + chart = _bars(sample_tree) + assert [node.name for node in chart._current_rows()] == ["big.bin", "photos"] + assert chart._rest == (2, 250), "code (150 bytes) and notes.txt (100)" + chart.deleteLater() + + +def _treemap(root) -> tuple[QWidget, QPoint]: + widget = TreemapWidget() + widget.resize(400, 300) + widget.set_view_root(root) + widget.grab() + tile = next(tile for tile in widget._tiles if not tile.grouped and tile.node.name == "big.bin") + return widget, QPoint(round(tile.rect.x + tile.rect.width / 2), round(tile.rect.y + tile.rect.height / 2)) + + +def _sunburst(root) -> tuple[QWidget, QPoint]: + widget = SunburstWidget() + widget.resize(400, 400) + widget.set_view_root(root) + widget.grab() + inner, ring = widget._radii() + return widget, QPoint(200, round(200 - inner - ring / 2)) + + +def _diagram(root) -> tuple[QWidget, QPoint]: + widget = TreeDiagramWidget() + widget.set_view_root(root) + widget.resize(widget.sizeHint()) + widget.grab() + return widget, widget.card_rect(widget.rows()[0]).center().toPoint() + + +@pytest.mark.parametrize("make", [_treemap, _sunburst, _diagram]) +def test_the_other_charts_wait_for_the_mouse_to_rest_too(qapp, sample_tree, tips, make): + widget, point = make(scan(sample_tree).root) + for offset in range(5): + _move(widget, point + QPoint(offset, 0)) + assert tips == [] + _rest(widget, point) + assert tips and tips[-1][0] and tips[-1][1] is widget + _rest(widget, QPoint(-50, -50)) + assert tips[-1][0] == "" + widget.deleteLater() + + +def test_a_real_tooltip_event_reaches_the_qt_tooltip(qapp, sample_tree): + chart = _bars(sample_tree) + chart.show() + _rest(chart, QPoint(100, 3)) + assert "big.bin" in QToolTip.text() + QToolTip.hideText() + chart.deleteLater() diff --git a/test/test_tree_paging.py b/test/test_tree_paging.py index e1324ebb..765fd93d 100644 --- a/test/test_tree_paging.py +++ b/test/test_tree_paging.py @@ -93,6 +93,20 @@ def test_show_rows_for_extends_every_paged_folder_above_the_node(model): assert model.rowCount(model.index_for(folder)) == 2 * PAGE + 1, "pages up to the target, then the last row" +class _Unsearched(list): + def index(self, *_args): + raise AssertionError("an entry already on a page is never searched for in the rest") + + +def test_show_rows_for_an_entry_on_a_page_searches_nothing(model, monkeypatch): + root = _root(8) + model.set_root(root) + ordered = _Unsearched(model._ordered(root)) + monkeypatch.setattr(model, "_ordered", lambda folder: ordered if folder is root else []) + model.show_rows_for(root.children[1]) # each chart click asked this: 6.5 ms per 150,000 entries + assert model.rowCount(model.index_for(root)) == PAGE + 1 + + def test_sorting_keeps_the_pages_shown_in_the_new_order(model): root = _root(8) model.set_root(root) From 9c4100c6528adf9a21d66f523b922216dfb00491 Mon Sep 17 00:00:00 2001 From: JeffreyChen Date: Thu, 19 Nov 2026 21:24:59 +0800 Subject: [PATCH 2/4] Open the hidden clean-up list's groups when it is shown Qt lays out every line of an opened group even while its tab is hidden. When the clean-up suggestions arrived after a scan, 56,321 empty folders held the GUI thread for 0.6-0.7 s while the charts were in use. A marked grouped list filled while hidden now opens its groups when it is next shown; the wait moves to the first visit of the Clean-up tab. --- architecture.md | 3 ++ docs/updates/2026-11.md | 20 +++++++ docs/updates/README.md | 1 + je_file_tree/gui/cleanup_panel.py | 1 + je_file_tree/gui/grouped_list.py | 49 +++++++++++++++-- test/test_grouped_list_deferred.py | 86 ++++++++++++++++++++++++++++++ 6 files changed, 157 insertions(+), 3 deletions(-) create mode 100644 test/test_grouped_list_deferred.py diff --git a/architecture.md b/architecture.md index 1631965f..64bf4fe9 100644 --- a/architecture.md +++ b/architecture.md @@ -1458,6 +1458,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 diff --git a/docs/updates/2026-11.md b/docs/updates/2026-11.md index b36588cb..d068f328 100644 --- a/docs/updates/2026-11.md +++ b/docs/updates/2026-11.md @@ -625,3 +625,23 @@ - **未驗證**:只在隱藏視窗與測試資料上量測,沒有在回報者的磁碟與螢幕上量測。 - **檔案**:`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`。 +- **待辦**:無。 diff --git a/docs/updates/README.md b/docs/updates/README.md index 61ad598e..91ad3fba 100644 --- a/docs/updates/README.md +++ b/docs/updates/README.md @@ -70,6 +70,7 @@ In the same commit: delete the item from `progress.md`, add a `#done` entry here | ID | Date | Title | Tags | Batch | |---|---|---|---|---| +| 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) | diff --git a/je_file_tree/gui/cleanup_panel.py b/je_file_tree/gui/cleanup_panel.py index b844d0f3..76a9024f 100644 --- a/je_file_tree/gui/cleanup_panel.py +++ b/je_file_tree/gui/cleanup_panel.py @@ -36,6 +36,7 @@ def __init__(self, parent: QWidget | None = None) -> None: self.unit = AUTO_UNIT self.model = grouped_list.GroupedListModel(self) self.view = grouped_list.build_view(self.model) + grouped_list.open_groups_when_shown(self.view) # the tab is usually hidden when suggestions arrive self.status = QLabel() self.status.setWordWrap(True) # a long line would otherwise claim its whole width and squeeze the folder tree beside the tabs diff --git a/je_file_tree/gui/grouped_list.py b/je_file_tree/gui/grouped_list.py index 9accaaa0..68e5dd66 100644 --- a/je_file_tree/gui/grouped_list.py +++ b/je_file_tree/gui/grouped_list.py @@ -12,7 +12,7 @@ from typing import Any from PySide6.QtCore import ( - QAbstractItemModel, QAbstractTableModel, QItemSelection, QItemSelectionModel, QModelIndex, QObject, + QAbstractItemModel, QAbstractTableModel, QEvent, QItemSelection, QItemSelectionModel, QModelIndex, QObject, QPersistentModelIndex, Qt, ) from PySide6.QtGui import QFont, QIcon @@ -317,17 +317,60 @@ def build_view(model: GroupedListModel) -> QTreeView: return view +class _ExpandWhenShown(QObject): + """Opens the groups of a view filled while hidden, the first time it is shown (U-20261119-05). + + Qt lays out every line of an opened group even in a hidden view, about two calls into the Python + model per line: measured 2026-11-19, 56,321 empty folders (a scan of the Windows folder) took 0.6-0.7 s + on the GUI thread the moment the clean-up suggestions arrived, while the charts were being used. + """ + + def __init__(self, view: QTreeView) -> None: + super().__init__(view) + self.view = view + self.pending = False + self.icons = False # whether the groups waiting to open show thumbnails + view.installEventFilter(self) + + def eventFilter(self, watched: QObject, event: QEvent) -> bool: + """Qt: open the groups once the view is shown.""" + if watched is self.view and event.type() == QEvent.Type.Show and self.pending: + self.pending = False + model = self.view.model() + if isinstance(model, GroupedListModel): + _expand_groups(model, self.view, icons=self.icons) + return False + + def fill(model: GroupedListModel, view: QTreeView, groups: Sequence[tuple[str, Sequence[Node]]], unit: str, *, tips: Sequence[str] | None = None, keepers: Sequence[Node | None] | None = None, icons: Mapping[Node, QIcon] | None = None) -> None: - """Show ``groups`` (a title and its entries, in the order given), all opened; ``tips``: one tooltip per group.""" + """Show ``groups`` (a title and its entries, in the order given), all opened; ``tips``: one tooltip per group. + + A view marked with ``open_groups_when_shown`` that is hidden opens its groups when it is next shown. + """ model.set_groups(groups, unit, tips=tips, keepers=keepers, icons=icons) for row in range(model.rowCount()): view.setFirstColumnSpanned(row, QModelIndex(), True) # a group's line runs across the columns for column, width in _COLUMN_WIDTHS.items(): view.setColumnWidth(column, width) view.header().setSectionResizeMode(_FOLDER_COLUMN, QHeaderView.ResizeMode.Stretch) - if icons is None and view.uniformRowHeights() and model.rowCount() >= _BATCHED_EXPANSION_MINIMUM: + waiting = view.findChild(_ExpandWhenShown) + if waiting is not None: + waiting.pending, waiting.icons = not view.isVisible(), icons is not None + if waiting.pending: + return + _expand_groups(model, view, icons=icons is not None) + + +def open_groups_when_shown(view: QTreeView) -> None: + """Let ``fill`` leave the groups of ``view`` closed while it is hidden, opening them when it is shown.""" + if view.findChild(_ExpandWhenShown) is None: + _ExpandWhenShown(view) + + +def _expand_groups(model: GroupedListModel, view: QTreeView, *, icons: bool) -> None: + if not icons and view.uniformRowHeights() and model.rowCount() >= _BATCHED_EXPANSION_MINIMUM: view.scheduleDelayedItemsLayout() for row in range(model.rowCount()): view.expand(model.index(row, 0)) diff --git a/test/test_grouped_list_deferred.py b/test/test_grouped_list_deferred.py new file mode 100644 index 00000000..3242a4fa --- /dev/null +++ b/test/test_grouped_list_deferred.py @@ -0,0 +1,86 @@ +"""A hidden clean-up list opens its groups when it is shown, not when suggestions arrive (U-20261119-05).""" + +from __future__ import annotations + +from PySide6.QtWidgets import QTabWidget, QWidget + +from je_file_tree.core.node import Node +from je_file_tree.gui import grouped_list +from je_file_tree.gui.cleanup_panel import CleanupPanel +from je_file_tree.gui.grouped_list import GroupedListModel +from je_file_tree.gui.tree_model import NODE_ROLE + + +def _tabs(view): + """The view on a second tab, hidden behind the first like the Clean-up tab during charting.""" + tabs = QTabWidget() + tabs.addTab(QWidget(), "charts") + tabs.addTab(view, "clean-up") + tabs.resize(500, 400) + tabs.show() + return tabs + + +def _groups(count: int): + nodes = [Node(f"empty-{row}", True) for row in range(count)] + return nodes, [("empty folders", nodes[:count - 2]), ("temporary", nodes[count - 2:])] + + +def test_a_marked_hidden_view_opens_its_groups_only_when_shown(qapp, monkeypatch): + model = GroupedListModel() + view = grouped_list.build_view(model) + grouped_list.open_groups_when_shown(view) + grouped_list.open_groups_when_shown(view) # marking twice keeps one watcher + tabs = _tabs(view) + expanded = [] + original = type(view).expand + monkeypatch.setattr(type(view), "expand", lambda self, index: (expanded.append(index.row()), original(self, index))) + nodes, groups = _groups(10) + grouped_list.fill(model, view, groups, "auto") + assert expanded == [], "the hidden list lays out nothing yet: 56,321 lines took 0.6-0.7 s" + assert not view.isExpanded(model.index(0, 0)) + grouped_list.fill(model, view, groups, "auto") # refilled while still hidden: still waiting + assert expanded == [] + tabs.setCurrentIndex(1) + assert view.isVisible() + assert view.isExpanded(model.index(0, 0)) and view.isExpanded(model.index(1, 0)) + assert expanded == [0, 1] + grouped_list.select_group(model, view, 1) + assert [index.data(NODE_ROLE) for index in view.selectionModel().selectedRows()] == nodes[8:] + tabs.setCurrentIndex(0) + tabs.setCurrentIndex(1) + assert expanded == [0, 1], "shown again: nothing to open twice" + assert len(view.findChildren(grouped_list._ExpandWhenShown)) == 1 + tabs.deleteLater() + + +def test_a_marked_visible_view_opens_its_groups_at_once(qapp): + model = GroupedListModel() + view = grouped_list.build_view(model) + grouped_list.open_groups_when_shown(view) + tabs = _tabs(view) + tabs.setCurrentIndex(1) + _nodes, groups = _groups(5) + grouped_list.fill(model, view, groups, "auto") + assert view.isExpanded(model.index(0, 0)) and view.isExpanded(model.index(1, 0)) + tabs.setCurrentIndex(0) + grouped_list.fill(model, view, groups[:1], "auto") + tabs.setCurrentIndex(1) + assert view.isExpanded(model.index(0, 0)), "a later hidden fill still opens when shown" + tabs.deleteLater() + + +def test_an_unmarked_hidden_view_still_opens_its_groups_at_once(qapp): + model = GroupedListModel() + view = grouped_list.build_view(model) + tabs = _tabs(view) + _nodes, groups = _groups(5) + grouped_list.fill(model, view, groups, "auto") + assert view.isExpanded(model.index(0, 0)) and view.isExpanded(model.index(1, 0)) + tabs.deleteLater() + + +def test_the_clean_up_list_is_marked(qapp): + panel = CleanupPanel() + assert panel.view.findChild(grouped_list._ExpandWhenShown) is not None + panel.deleteLater() From 186456f9911a36b0dca6597f37be9046f1d7e759 Mon Sep 17 00:00:00 2001 From: JeffreyChen Date: Thu, 19 Nov 2026 22:00:55 +0800 Subject: [PATCH 3/4] Give way to the window in every pass of the empty-folder search After a scan, the clean-up worker's emptiness pass and outermost() ran over every folder without giving way: 0.3 s on C:\Windows during which each call the window made into Python waited for the worker, and the folder tree stalled 381 ms while its scrollbar was dragged. Both passes now check the pacing gate every 256 entries. --- architecture.md | 2 ++ docs/updates/2026-11.md | 22 ++++++++++++++++++ docs/updates/README.md | 1 + je_file_tree/core/cleanup.py | 12 ++++++---- je_file_tree/core/node.py | 18 +++++++++++---- test/test_pacing.py | 45 +++++++++++++++++++++++++++++++++++- 6 files changed, 90 insertions(+), 10 deletions(-) diff --git a/architecture.md b/architecture.md index 64bf4fe9..1d276d79 100644 --- a/architecture.md +++ b/architecture.md @@ -1286,6 +1286,8 @@ 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). 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 diff --git a/docs/updates/2026-11.md b/docs/updates/2026-11.md index d068f328..b184bf3b 100644 --- a/docs/updates/2026-11.md +++ b/docs/updates/2026-11.md @@ -645,3 +645,25 @@ - **未驗證**:只在隱藏視窗中量測,沒有在使用者的螢幕上量測。空資料夾更多的磁碟,開啟「清理」分頁時等待更久。 - **檔案**:`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`。這兩處都只發生一次,也很短,所以這次不處理。 +- **驗證**:`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`。 +- **待辦**:無。 diff --git a/docs/updates/README.md b/docs/updates/README.md index 91ad3fba..ec76c4d0 100644 --- a/docs/updates/README.md +++ b/docs/updates/README.md @@ -70,6 +70,7 @@ In the same commit: delete the item from `progress.md`, add a `#done` entry here | ID | Date | Title | Tags | Batch | |---|---|---|---|---| +| 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) | diff --git a/je_file_tree/core/cleanup.py b/je_file_tree/core/cleanup.py index d8d5602d..fe2d26bd 100644 --- a/je_file_tree/core/cleanup.py +++ b/je_file_tree/core/cleanup.py @@ -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: @@ -229,13 +229,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: diff --git a/je_file_tree/core/node.py b/je_file_tree/core/node.py index feaa8fbb..54d40501 100644 --- a/je_file_tree/core/node.py +++ b/je_file_tree/core/node.py @@ -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 @@ -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 diff --git a/test/test_pacing.py b/test/test_pacing.py index 7130e91b..b477b793 100644 --- a/test/test_pacing.py +++ b/test/test_pacing.py @@ -2,12 +2,16 @@ from __future__ import annotations +import inspect +import math +import sys import threading import time import pytest -from je_file_tree.core import pacing +from je_file_tree.core import cleanup, pacing +from je_file_tree.core.node import PACE_EVERY, Node, outermost from je_file_tree.core.pacing import Gate @@ -55,3 +59,42 @@ def test_the_thread_that_closed_the_gate_never_waits_at_it(monkeypatch: pytest.M started = time.perf_counter() gate.give_way() # the window running core code itself (a synchronous scan, say) must not stall assert time.perf_counter() - started < 0.1 + + +def _chain(count: int) -> Node: + """A root holding ``count`` empty folders, each also holding an empty folder.""" + root = Node("root", True, children=[]) + for number in range(count): + outer = Node(f"outer-{number}", True, children=[], parent=root) + outer.children.append(Node("inner", True, children=[], parent=outer)) + root.children.append(outer) + return root + + +def test_outermost_paces_both_of_its_passes(): + root = _chain(600) + nodes = [*root.children, *(child.children[0] for child in root.children)] + paced = [] + kept = outermost(nodes, pace=lambda: paced.append(1)) + assert kept == root.children, "pacing never changes the answer" + assert len(paced) == 2 * math.ceil(len(nodes) / PACE_EVERY), "every PACE_EVERY entries, in each pass" + assert outermost(nodes) == kept + + +def test_empty_folders_gives_way_in_every_pass(monkeypatch): + root = _chain(600) + callers: set[tuple[str, int]] = set() + monkeypatch.setattr(cleanup, "give_way", lambda: callers.add((sys._getframe(1).f_code.co_name, + sys._getframe(1).f_lineno))) + found = cleanup.empty_folders(root) + assert len(found) == 600 and {id(node) for node in found} == {id(node) for node in root.children} + assert ("outermost", _line_of(outermost, "pace()", 1)) in callers + assert ("outermost", _line_of(outermost, "pace()", 2)) in callers + lines = {line for name, line in callers if name == "empty_folders"} + assert len(lines) == 2, "the walk and the emptiness pass: unpaced, they held the window 0.3 s" + + +def _line_of(function, text: str, occurrence: int) -> int: + lines, first = inspect.getsourcelines(function) + found = [first + offset for offset, line in enumerate(lines) if line.strip() == text] + return found[occurrence - 1] From 52a18b5d7c9dc36b260bf665f17543f86c7dcabb Mon Sep 17 00:00:00 2001 From: JeffreyChen Date: Thu, 19 Nov 2026 22:21:23 +0800 Subject: [PATCH 4/4] Give way between pages of a large folder's entries The scan's add-up and sort and the clean-up rule matching gave way once per folder; one folder of 41,610 entries took 42 ms to add up and sort and 100 ms to match, and dragging the folder tree's scrollbar still stalled 104-155 ms now and then. Folders of more than 256 entries are now handled a page at a time, giving way between pages, with the same stable order as before. --- architecture.md | 2 ++ docs/updates/2026-11.md | 30 ++++++++++++++++++++++++- docs/updates/README.md | 1 + je_file_tree/core/cleanup.py | 4 +++- je_file_tree/core/scanner.py | 43 +++++++++++++++++++++++++++--------- test/test_pacing.py | 36 +++++++++++++++++++++++++++++- 6 files changed, 103 insertions(+), 13 deletions(-) diff --git a/architecture.md b/architecture.md index 1d276d79..1b173f96 100644 --- a/architecture.md +++ b/architecture.md @@ -1288,6 +1288,8 @@ loop is about to wait (`aboutToBlock`). Every walk over the tree calls `pacing.g 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 diff --git a/docs/updates/2026-11.md b/docs/updates/2026-11.md index b184bf3b..ae6f52fd 100644 --- a/docs/updates/2026-11.md +++ b/docs/updates/2026-11.md @@ -662,8 +662,36 @@ | 掃描結束後最慢一步 | 381 ms | 98–104 ms | | 掃描中最慢一步 | 155 ms | 34–153 ms | -- **未處理**:仍會偶爾出現約 100–150 ms 的停頓(每次一千多步中出現 1–2 次),發生在掃描收尾的 `_add_up`:WinSxS 有 29,244 個子項目,一次加總並排序,`list.sort` 無法中途讓路;以及清理建議比對檔案的 `file_key`。這兩處都只發生一次,也很短,所以這次不處理。 +- **未處理**:仍會偶爾出現約 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`。 +- **待辦**:無。 diff --git a/docs/updates/README.md b/docs/updates/README.md index ec76c4d0..bac1d136 100644 --- a/docs/updates/README.md +++ b/docs/updates/README.md @@ -70,6 +70,7 @@ 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) | diff --git a/je_file_tree/core/cleanup.py b/je_file_tree/core/cleanup.py index fe2d26bd..611d2c37 100644 --- a/je_file_tree/core/cleanup.py +++ b/je_file_tree/core/cleanup.py @@ -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: diff --git a/je_file_tree/core/scanner.py b/je_file_tree/core/scanner.py index ad2f552d..8bb61a11 100644 --- a/je_file_tree/core/scanner.py +++ b/je_file_tree/core/scanner.py @@ -30,7 +30,7 @@ from je_file_tree.core.allocation import Allocation, OrdinaryAllocation, allocation_for, ordinary_allocation from je_file_tree.core.cpu_load import WorkerGovernor from je_file_tree.core.exclusions import Excluded, exclusion_test -from je_file_tree.core.node import Node +from je_file_tree.core.node import PACE_EVERY, Node from je_file_tree.core.hard_links import HardLinkAccounting, account_hard_links from je_file_tree.core.owner_id import file_owner from je_file_tree.core.mounts import MOUNT_BOUNDARY, MountChangedError, MountSurvey, boundary_path, mount_points @@ -764,24 +764,47 @@ def _size_first(node: Node) -> tuple[int, str]: def _add_up(folders: list[Node]) -> None: """Fill in folder totals, deepest folders first, and sort each folder's children largest first. - ``folders`` must list every folder after its parent. + ``folders`` must list every folder after its parent. A folder of more than ``PACE_EVERY`` entries + gives way between pages of them: adding up and sorting the 41,610 entries of one folder in + the Windows folder took 42 ms in one go, and up to 150 ms with the window waiting on it (U-20261119-07). """ for folder in reversed(folders): give_way() size = allocated = files = subfolders = 0 newest = folder.modified children = folder.children - for child in children: - size += child.size - allocated += child.allocated - files += child.file_count - if child.is_dir and not child.is_link and child.error != EXCLUDED: - subfolders += 1 + child.dir_count - newest = max(newest, child.modified) + for page in (children,) if len(children) <= PACE_EVERY else _pages(children): + for child in page: + size += child.size + allocated += child.allocated + files += child.file_count + if child.is_dir and not child.is_link and child.error != EXCLUDED: + subfolders += 1 + child.dir_count + newest = max(newest, child.modified) folder.size = size folder.allocated = allocated folder.file_count = files folder.dir_count = subfolders folder.modified = newest - if isinstance(children, list) and len(children) > 1: + if isinstance(children, list) and len(children) > PACE_EVERY: + _sort_size_first(children) + elif isinstance(children, list) and len(children) > 1: children.sort(key=_size_first) + + +def _pages(children: list[Node]) -> Iterator[list[Node]]: + """``children`` ``PACE_EVERY`` at a time, giving way before every page but the first.""" + for start in range(0, len(children), PACE_EVERY): + if start: + give_way() + yield children[start:start + PACE_EVERY] + + +def _sort_size_first(children: list[Node]) -> None: + """Largest first, by name among equals: a long list's keys are made a page at a time, giving way between.""" + keys: list[tuple[int, str]] = [] + for start in range(0, len(children), PACE_EVERY): + give_way() + keys.extend(_size_first(child) for child in children[start:start + PACE_EVERY]) + order = sorted(range(len(children)), key=keys.__getitem__) # stable, like list.sort + children[:] = [children[index] for index in order] diff --git a/test/test_pacing.py b/test/test_pacing.py index b477b793..528a8f41 100644 --- a/test/test_pacing.py +++ b/test/test_pacing.py @@ -10,7 +10,7 @@ import pytest -from je_file_tree.core import cleanup, pacing +from je_file_tree.core import cleanup, pacing, scanner from je_file_tree.core.node import PACE_EVERY, Node, outermost from je_file_tree.core.pacing import Gate @@ -98,3 +98,37 @@ def _line_of(function, text: str, occurrence: int) -> int: lines, first = inspect.getsourcelines(function) found = [first + offset for offset, line in enumerate(lines) if line.strip() == text] return found[occurrence - 1] + + +def _flat(count: int) -> Node: + """A folder of ``count`` files with repeated sizes and names differing in case: ties must keep the order.""" + folder = Node("flat", True, children=[]) + folder.children.extend(Node(f"{'F' if number % 3 else 'f'}ile-{number % 50}", False, size=number % 7, + allocated=number, file_count=1, modified=float(number), parent=folder) + for number in range(count)) + return folder + + +@pytest.mark.parametrize("count", [3, PACE_EVERY, PACE_EVERY + 1, 1000]) +def test_a_large_folder_is_added_up_and_sorted_a_page_at_a_time(monkeypatch, count): + folder = _flat(count) + expected = sorted(folder.children, key=scanner._size_first) + paced = [] + monkeypatch.setattr(scanner, "give_way", lambda: paced.append(1)) + scanner._add_up([folder]) + assert [id(child) for child in folder.children] == [id(child) for child in expected], "the same order as before" + assert folder.size == sum(number % 7 for number in range(count)) and folder.file_count == count + assert folder.allocated == sum(range(count)) and folder.modified == float(count - 1) + pages = math.ceil(count / PACE_EVERY) + # one per folder, one between pages of the totals, one per page of sort keys + assert len(paced) == (2 * pages if count > PACE_EVERY else 1), "41,610 entries took 42 ms in one go" + + +def test_matching_a_large_folder_gives_way_between_pages(monkeypatch): + folder = _flat(1000) + folder.name = "C:\flat" # an absolute path: a root the clean-up rules can look into + paced = [] + monkeypatch.setattr(cleanup, "give_way", lambda: paced.append(1)) + cleanup._visit(folder, (folder.name.casefold(),), cleanup._Matcher(cleanup.RULES, time.time()), + {}, cleanup.coverage_of(folder), set(), set()) + assert len(paced) == (1000 - 1) // PACE_EVERY, "one folder's 41,610 files took 100 ms to match"