Skip to content

[ISSUE #12706]✨Add an opt-in x86-64 level build argument for the Broker in the service image - #12707

Merged
mxsm merged 1 commit into
mainfrom
issue-12706-broker-target-cpu
Nov 16, 2026
Merged

mxsm merged 1 commit into
mainfrom
issue-12706-broker-target-cpu

Conversation

@mxsm

@mxsm mxsm commented Nov 16, 2026

Copy link
Copy Markdown
Owner

Which Issue(s) This PR Fixes(Closes)

Brief Description

Adds an opt-in build argument that builds the Broker for a newer x86-64 microarchitecture level. The default stays the toolchain baseline, so the published images do not change.

  • docker/Dockerfile.base (service-builder stage):
    • New ARG ROCKETMQ_BROKER_TARGET_CPU=, next to ROCKETMQ_BROKER_PGO and ROCKETMQ_BROKER_BOLT.
    • x86-64-v2, x86-64-v3 or x86-64-v4 add -C target-cpu=<level> to the Broker build: both PGO builds, and the plain build when PGO is off. Empty keeps the baseline; any other value, such as the non-portable native, fails the build with a message.
    • The NameServer, Controller and Proxy keep the baseline. They are not on the message path, and librocksdb-sys in the Controller does not compile with -C target-cpu=x86-64-v3 alone: its build script then enables the CRC32C path that needs PCLMUL, which that level does not include. A real image build found this.
  • rocketmq-website/docs/deployment/containers.md and its zh-CN translation: the argument, its hardware requirement (AVX2, BMI2 and FMA: Intel Haswell, AMD Zen or newer) and the measured effect.

A separate x86-64-v3 image in the publish pipeline is not added: about 2% to 5% of Broker CPU does not justify building and maintaining a second image. A Broker built for x86-64-v3 stops with an illegal-instruction error on older CPUs.

How Did You Test This Change?

  • Real image builds from a clean origin/main archive with this Dockerfile (docker buildx build --target service-builder):
    • --build-arg ROCKETMQ_BROKER_TARGET_CPU=native fails at once with ROCKETMQ_BROKER_TARGET_CPU must be empty, x86-64-v2, x86-64-v3 or x86-64-v4.
    • --build-arg ROCKETMQ_BROKER_TARGET_CPU=x86-64-v3 with the default PGO and BOLT builds all four services. In the result the Broker has about 200k AVX ymm instructions (the baseline Broker about 30k, from runtime-dispatched code), the other services stay at the baseline, and rocketmq-broker-rust --help runs.
  • npm run build in rocketmq-website: both locales build and render the new text.
  • Linux A/B in Docker on the same Broker source, Broker pinned to 8 CPUs and the client to 8 others, store on disk, three alternating rounds, 6 runs per cell (lite-pull 6 to 9), 0 failures:
Load PGO + BOLT: user cycles per message PGO + BOLT: Broker CPU per message PGO + BOLT: throughput Plain build: user instructions / cycles
sync -7.2% -2.7% +2.0% -3.3% / -0.4%
async, 1 connection x 256 -5.8% -5.1% +5.8% -3.8% / -1.7%
async, 4 connections x 64 -3.5% -1.8% -1.5% (mixed) -3.8% / -1.7%
async, 16 connections x 16 -4.4% -2.5% +0.7% -3.8% / -2.2%
lite-pull n/a -1.7% 0.0% n/a
  • The plain builds have no profile-training variance; between two separately trained PGO builds of the same code, cycles differed by up to about 2%. Building the C code (mimalloc) for x86-64-v3 as well added nothing.

🤖 Generated with Claude Code

@mxsm
mxsm merged commit aec8280 into main Nov 16, 2026
10 checks passed
@rocketmq-rust-bot

Copy link
Copy Markdown
Collaborator

🔊@mxsm 🚀Thanks for your contribution🎉!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Enhancement✨] Add an opt-in x86-64 level build argument for the Broker in the service image

3 participants