Skip to content

Commit 6e4e93a

Browse files
authored
Merge pull request #1258 from dhellmann/docstring-fixes-bootstrapper-performance
docs(bootstrapper): fix docstrings and add test for write-error logging
2 parents 4c18163 + 12315ee commit 6e4e93a

2 files changed

Lines changed: 43 additions & 4 deletions

File tree

‎src/fromager/bootstrapper/_bootstrapper.py‎

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -935,11 +935,12 @@ def add_to_build_order(
935935
prebuilt: bool = False,
936936
constraint: Requirement | None = None,
937937
) -> None:
938-
"""Append a package to the build-order output file if not already present.
938+
"""Append a package to the build-order list if not already present.
939939
940940
Deduplicates by ``(canonicalized_name, version)`` so the same package
941-
is never written twice, regardless of extras. On each new entry, the
942-
full build-order list is written to ``self._build_order_filename``.
941+
is never written twice, regardless of extras. Data is buffered in
942+
memory and written to ``self._build_order_filename`` once during
943+
``finalize()``.
943944
944945
Args:
945946
req: The requirement being added to the build order.
@@ -985,7 +986,12 @@ def _schedule_write(self, path: pathlib.Path, content: str) -> None:
985986
fut.add_done_callback(self._check_write_error)
986987

987988
def _write_graph_async(self) -> None:
988-
"""Serialize the dependency graph on the main thread, write it in background."""
989+
"""Serialize the dependency graph on the main thread, write it in background.
990+
991+
Must only be called from the main thread. Serialization happens
992+
synchronously here so the snapshot is consistent with the caller's
993+
view of the graph; only the file I/O is offloaded to the write pool.
994+
"""
989995
buf = io.StringIO()
990996
self.ctx.dependency_graph.serialize(buf)
991997
self._schedule_write(self.ctx.graph_file, buf.getvalue())
@@ -1269,6 +1275,10 @@ def finalize(self) -> int:
12691275
Reports failed versions in multiple versions mode.
12701276
In test mode, writes failure report and returns non-zero if there were failures.
12711277
1278+
Note: I/O errors from background graph writes are logged at ERROR level
1279+
but are not raised. Check the log for ``"background file write failed"``
1280+
if the on-disk graph file is suspected to be stale.
1281+
12721282
Returns:
12731283
0 if all packages built successfully (or not in test/multiple versions mode)
12741284
1 if any packages failed in test mode
@@ -1334,5 +1344,8 @@ def __exit__(
13341344
self._bg_pool.shutdown(wait=False, cancel_futures=True)
13351345
self._bg_pool = None
13361346
if self._write_pool is not None:
1347+
# Intentionally abandon any pending graph writes on error exit.
1348+
# A crashed or aborted run produces inconsistent state regardless;
1349+
# waiting for writes would only delay propagation of the exception.
13371350
self._write_pool.shutdown(wait=False, cancel_futures=True)
13381351
self._write_pool = None

‎tests/test_bootstrapper.py‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -799,6 +799,12 @@ def test_record_stack_state_throttled_when_called_rapidly(
799799
bt._record_stack_state([_make_resolve_item("pkgc")])
800800
second_mtime = bt._stack_filename.stat().st_mtime
801801

802+
# NOTE: This assertion compares st_mtime values for equality. On filesystems
803+
# with coarse mtime resolution (e.g. 1-second), two calls that span a
804+
# resolution boundary could produce equal mtimes even when the file was
805+
# rewritten, or unequal mtimes when it was not. APFS (nanosecond resolution)
806+
# makes this reliable in practice, but the test is inherently filesystem-
807+
# dependent.
802808
assert first_mtime == second_mtime
803809

804810

@@ -825,6 +831,26 @@ def test_finalize_writes_build_order_and_graph(tmp_context: WorkContext) -> None
825831
assert contents[0]["dist"] == "mypkg"
826832

827833

834+
def test_check_write_error_logs_on_failure(
835+
tmp_context: WorkContext, caplog: pytest.LogCaptureFixture
836+
) -> None:
837+
"""_check_write_error() logs an error when the background write future raises."""
838+
bt = bootstrapper.Bootstrapper(tmp_context)
839+
840+
# Arrange: create a future that has already failed with an OSError
841+
import concurrent.futures
842+
843+
fut: concurrent.futures.Future[int] = concurrent.futures.Future()
844+
fut.set_exception(OSError("disk full"))
845+
846+
# Act
847+
with caplog.at_level(logging.ERROR):
848+
bt._check_write_error(fut)
849+
850+
# Assert: error is logged, not raised
851+
assert any("disk full" in r.message for r in caplog.records)
852+
853+
828854
def test_bootstrap_calls_record_stack_state(tmp_context: WorkContext) -> None:
829855
"""`_record_stack_state` is called at least once during `bootstrap()`."""
830856
bt = bootstrapper.Bootstrapper(tmp_context)

0 commit comments

Comments
 (0)