Open Bug 2084074 Opened 1 month ago Updated 17 days ago

Speed up the source docs build

Categories

(Developer Infrastructure :: Source Documentation, task)

task

Tracking

(firefox161 affected)

REOPENED
161 Branch
Tracking Status
firefox161 --- affected

People

(Reporter: Sylvestre, Assigned: Sylvestre)

References

Details

(Keywords: leave-open)

Attachments

(4 external files)

Expected performance wins (clean ./mach doc -j 4, 3 runs each):

  • Overall: 115 s → 47 s, about 2.5x faster.
  • Pickling fix: 124 s → 67 s. Doctrees no longer each carry a copy of the build environment
    (490 MB → 96 MB).
  • Garbage collector off during the build: 67 s → 47 s. Peak memory rises from 0.84 to 1.41 GiB,
    still below the 1.12 GiB baseline before the performance work.
  • Parallel read: on its own it adds 7 s, but it's what the other two fixes build on. With them
    in place, switching back to a serial read costs 85 s instead of 47 s and uses more memory
    (2.48 GiB).
Depends on: 2084089

MyST parses each eval-rst block into a temporary document that shares the
original settings object, and the nodes it moves into the page keep pointing at
it. Sphinx only clears settings.env on a copy of the settings before pickling,
so every such doctree carried a full copy of the BuildEnvironment.

Reattaching those nodes to their doctree shrinks the doctrees from 490 MB to
96 MB. Loading them back in the main process during the write phase drops from
61 s to 6.5 s, and a clean -j 4 build goes from 116 s to 102 s with the same
HTML output.

Assignee: nobody → sledru
Status: NEW → ASSIGNED

mozbuild.sphinx, bzlink and sphinx-js did not declare whether they are safe for parallel reading, so Sphinx fell back to a serial read. None of them keep per-document state.

A clean -j 4 build goes from 102 s to 71 s.

A CodSpeed walltime profile of a full build showed the main process spending
most of its own time in libpython, which gc.callbacks timing confirmed to be
garbage collection: about 18 s at -j 4, nearly all in full collections over
the growing environment and doctrees. Worker processes forked from it pay the
same cost.

Turn the collector off once reading starts, collect once after the parallel
reads are merged, and turn it back on when the build finishes. A clean -j 4
build goes from 70 s to 51 s, with peak resident memory going from 0.84 GB to
1.41 GB.

Collect and gc.freeze() when reading and writing start, so the objects that
already exist stay out of later collections and their memory stays shared with
the forked workers. On top of disabling automatic collection this is a small
gain: a clean -j 4 build goes from 54 s to 52 s with the same peak memory.

Pushed by sledru@mozilla.com: https://github.com/mozilla-firefox/firefox/commit/a9f26a0686e8 https://hg.mozilla.org/integration/autoland/rev/e2dbda1f3b25 Stop pickling the build environment into doctrees with eval-rst blocks r=firefox-source-docs-reviewers,ahal https://github.com/mozilla-firefox/firefox/commit/c23b742eb7b6 https://hg.mozilla.org/integration/autoland/rev/301ed54c913a Let Sphinx read the docs in parallel r=firefox-source-docs-reviewers,ahal
Status: ASSIGNED → RESOLVED
Closed: 23 days ago
Resolution: --- → FIXED
Target Milestone: --- → 161 Branch
Pushed by sledru@mozilla.com: https://github.com/mozilla-firefox/firefox/commit/a6037dfd1582 https://hg.mozilla.org/integration/autoland/rev/c4e4452193ba Disable the cyclic garbage collector while building the docs r=firefox-source-docs-reviewers,ahal DONTBUILD https://github.com/mozilla-firefox/firefox/commit/54e6c7c3d4de https://hg.mozilla.org/integration/autoland/rev/3bb0ee63b578 Freeze the long-lived objects before Sphinx forks its docs workers r=firefox-source-docs-reviewers,ahal DONTBUILD
Status: RESOLVED → REOPENED
Keywords: leave-open
Resolution: FIXED → ---
Regressions: 2088449
You need to log in before you can comment on or make changes to this bug.

Attachment

General

Created:
Updated:
Size: