Skip to content

Improve the documentation of concurrency in BuildGrid

Adam Coldrick requested to merge sotk/documentation/concurrency-updates into master

Before raising this MR, consider whether the following are required, and complete if so:

  • Unit tests
  • Metrics
  • Documentation update(s)

No unit tests or metrics, this is just a documentation update.

Description

The documentation has a diagram showing the different threads and coroutines used in BuildGrid. However, in the time since this diagram was made we've made a few changes to BuildGrid without remembering to update it, which means it no longer matches reality.

This MR updates the diagram to reflect the changes that have occurred since it was made.

The diagram also contains a lot of thread names etc. that aren't necessarily understandable without context, and the choice of concurrency approach is important information which isn't in the diagram. This MR also adds a section documenting each of the Python threads/coroutines/subprocesses used in BuildGrid, describing their purpose and reasoning for the approach where applicable.

Changes proposed in this merge request:

  • Update the threading model diagram to match current reality
  • Add documentation of the various threads/coroutines/subprocesses in BuildGrid

Validation

Build the docs and take a look in your browser,

tox -e docs && cd docs/build/html && python -m http.server && cd -

Then go to http://localhost:8000/developer/architecture_overview.html#the-flow-of-buildgrid-requests in your browser.

Edited by Adam Coldrick

Merge request reports