DOCS: Editorial updates to multiplex workers
RELNOTES: None
PiperOrigin-RevId: 319876304
diff --git a/site/docs/multiplex-worker.md b/site/docs/multiplex-worker.md
index 8d62154..4556ee4 100644
--- a/site/docs/multiplex-worker.md
+++ b/site/docs/multiplex-worker.md
@@ -1,13 +1,15 @@
---
layout: documentation
-title: Multiplex Workers
+title: Multiplex workers
---
-# Multiplex Workers (experimental feature)
+# Multiplex workers (experimental feature)
-Multiplex Workers allow Bazel to handle multiple requests with a single worker
-process. For multi-threaded workers, Bazel is able to use less resources to
-achieve the same, or even better performance. For example, instead of having one
+**Caution:** Experimental features are subject to change at any time.
+
+_Multiplex workers_ allow Bazel to handle multiple requests with a single worker
+process. For multi-threaded workers, Bazel can use fewer resources to
+achieve the same, or better performance. For example, instead of having one
worker process per worker, Bazel can have four multiplexed workers talking to
the same worker process, which can then handle requests in parallel. For
languages like Java and Scala, this saves JVM warm-up time and JIT compilation
@@ -15,12 +17,12 @@
## Contents
-* [Multiplex Workers Overview](#multiplex-workers-overview)
-* [A Guide to Write a Multiplex-Compatible Ruleset](#a-guide-to-write-a-multiplex-compatible-ruleset)
-* [Enable Multiplex Workers](#enable-multiplex-workers)
+* [Overview](#overview)
+* [Writing multiplex-compatible rules](#writing-multiplex-compatible-rules)
+* [Enabling multiplex workers](#enabling-multiplex-workers)
* [WARNING](#warning)
-## Multiplex Workers Overview
+## Overview
We add two layers between the Bazel server and the worker process. For certain
mnemonics that can run processes in parallel, Bazel gets a `WorkerProxy` from
@@ -31,8 +33,8 @@
back to the correct `WorkerProxy`. Just as with non-multiplexed workers, all
communication is done over standard in/out.
-Each worker has a key. Bazel uses the hash code (composed of environment
-variables, the execution root, and the mnemonic) of the key to determine which
+Each worker has a key. Bazel uses the key's hash code (composed of environment
+variables, the execution root, and the mnemonic) to determine which
`WorkerMultiplexer` to use. `WorkerProxy`s communicate with the same
`WorkerMultiplexer` if they have the same hash code. Therefore, assuming
environment variables and the execution root are the same in a single Bazel
@@ -40,39 +42,38 @@
worker process. The total number of workers, including regular workers and
`WorkerProxy`s, is still limited by `--worker_max_instances`.
-## A Guide to Write a Multiplex-Compatible Ruleset
+## Writing multiplex-compatible rules
The rule's worker process should be multi-threaded to take advantage of
-Multiplex Workers. Protobuf allows a ruleset to parse a single request even
+multiplex workers. Protobuf allows a ruleset to parse a single request even
though there might be multiple requests piling up in the stream. Whenever the
worker process parses a request from the stream, it should handle the request in
-a new thread. Since different thread could complete and write to the stream at
+a new thread. Because different thread could complete and write to the stream at
the same time, the worker process needs to make sure the responses are written
atomically (i.e. messages don't overlap). Responses must contain the
`request_id` of the request they're handling.
-## Enable Multiplex Workers
+## Enabling multiplex workers
-Multiplex workers are not enabled by default. A ruleset can turn on Multiplex
-Workers by using the `supports-multiplex-workers` tag in the
+Multiplex workers are not enabled by default. A ruleset can turn on multiplex
+workers by using the `supports-multiplex-workers` tag in the
`execution_requirements` of an action (just like the `supports-workers` tag
enables regular workers). As is the case when using regular workers, a worker
-strategy needs to be specified, either at the ruleset level, eg.
-`--strategy=[some_mnemonic]=worker`, or generally at the strategy level, eg.
-`--dynamic_local_strategy=worker,standalone`. No additional flags are
+strategy needs to be specified, either at the ruleset level (for example,
+`--strategy=[some_mnemonic]=worker`) or generally at the strategy level (for
+example, `--dynamic_local_strategy=worker,standalone`.) No additional flags are
necessary, and `supports-multiplex-workers` takes precedence over
-`supports-workers`, if both are set. A ruleset is encouraged to use Multiplex
-Workers if possible, since this will improve performance.
+`supports-workers`, if both are set. A ruleset is encouraged to use multiplex
+workers if possible, to improve performance.
### WARNING
-Due to a rare bug, Multiplex Workers are currently unstable. Occasionally, you
-might see Bazel hanging at the execution phase. We believe this happens because
-Multiplex Workers are waiting for responses from the worker process which never
-comes. Bazel will hang indefinitely. If you see this behavior, stop the Bazel
-server and rerun. It is not expected to happen often. We are actively working on
-a fix.
+Due to a rare bug, multiplex workers are currently unstable. Occasionally,
+Bazel hangs indefinitely at the execution phase. If you see this behavior,
+stop the Bazel server and rerun. This delay is probably caused by
-There is also a chance that the issue lies in the ruleset worker implementation.
-It is possible a thread dies or a race condition occurs. Make sure the worker
-process always returns responses in all circumstances.
+ * Multiplex workers waiting for responses from the worker process that never
+ comes.
+ * Incorrectly configured ruleset worker implementation where a thread dies or
+ a race condition occurs. To counteract this, ensure the worker process
+ returns responses in all circumstances.
