@@ -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
0 commit comments