Skip to content

<algorithm>: Implement batched random integer generation for shuffle()#5932

Merged
StephanTLavavej merged 18 commits intomicrosoft:mainfrom
FranciscoThiesen:FranciscoGeimanThiesen/faster_shuffle_batched_random
Feb 24, 2026
Merged

<algorithm>: Implement batched random integer generation for shuffle()#5932
StephanTLavavej merged 18 commits intomicrosoft:mainfrom
FranciscoThiesen:FranciscoGeimanThiesen/faster_shuffle_batched_random

Conversation

@FranciscoThiesen
Copy link
Contributor

@FranciscoThiesen FranciscoThiesen commented Dec 2, 2025

Summary

  • Implement batched random number generation for shuffle based on Brackett-Rozinsky & Lemire's paper
  • For URNGs with full 64-bit range (like mt19937_64), generate 2 bounded random integers from a single 64-bit random value
  • Uses Lemire's nearly-divisionless algorithm for rejection sampling

Implementation Details

  • Added _Batched_rng_from_urng struct that extracts batches of bounded random integers
  • Added _Random_shuffle_batched function implementing Fisher-Yates with batched RNG
  • Modified shuffle() and ranges::shuffle to use batched version for eligible URNGs
  • Compile-time dispatch based on URNG characteristics (full 64-bit range)

Test Plan

  • Existing shuffle tests pass
  • Added permutation correctness tests for both 64-bit (batched) and 32-bit (non-batched) paths
  • Added edge case tests (empty, single element, 2, 3, 4, and 10000 elements)

Resolves #5736

@FranciscoThiesen
Implement batched random integer generation for shuffle
d1744fa 
Implements the algorithm from Brackett-Rozinsky & Lemire's paper
"Batched Ranged Random Integer Generation" to reduce RNG calls in
std::shuffle and ranges::shuffle for 64-bit URNGs like mt19937_64.

The batched approach extracts multiple bounded random integers from a
single 64-bit random word, using only multiplication (no division) in
the common case. This reduces the number of RNG calls by approximately
half for arrays with fewer than 2^32 elements.

Resolves microsoft#5736
@FranciscoThiesen FranciscoThiesen requested a review from a team as a code owner December 2, 2025 22:28
@github-project-automation github-project-automation bot moved this to Initial Review in STL Code Reviews Dec 2, 2025
frederick-vs-ja
frederick-vs-ja reviewed Dec 2, 2025
View reviewed changes
@FranciscoThiesen
Copy link
Contributor Author

FranciscoThiesen commented Dec 3, 2025

@FranciscoThiesen please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.

@microsoft-github-policy-service agree [company="{your company}"]

Options:

  • (default - no company specified) I have sole ownership of intellectual property rights to my Submissions and I am not making Submissions in the course of work for my employer.
@microsoft-github-policy-service agree
  • (when company given) I am making Submissions in the course of work for my employer (or my employer has intellectual property rights in my Submissions by contract or applicable law). I have permission from my employer to make Submissions and enter into this Agreement on behalf of my employer. By signing below, the defined term “You” includes me and my employer.
@microsoft-github-policy-service agree company="Microsoft"

Contributor License Agreement

@microsoft-github-policy-service agree [company="Microsoft"]

@FranciscoThiesen
Copy link
Contributor Author

FranciscoThiesen commented Dec 3, 2025

@microsoft-github-policy-service agree company="Microsoft"

@FranciscoThiesen
Address review feedback: extract URNG range check to variable template
3df8856 
Move _Has_full_64bit_range check out of _Batched_rng_from_urng class
to reduce template instantiation overhead. Use is_same_v and _Max_limit
as suggested by reviewer.
@FranciscoThiesen
Apply clang-format
8aa184a
@StephanTLavavej StephanTLavavej added the performance Must go faster label Dec 4, 2025
@StephanTLavavej StephanTLavavej changed the title Implement batched random integer generation for shuffle <algorithm>: Implement batched random integer generation for shuffle() Dec 6, 2025
@StephanTLavavej
Merge branch 'main' into FranciscoGeimanThiesen/faster_shuffle_batche…
3a8bff6 
…d_random
@StephanTLavavej
Naming: _B1 => _Bx1, _B2 => _Bx2
b838edc
@StephanTLavavej
Scope _Diff more tightly.
3091d9d
@StephanTLavavej
Add const to _UFirst.
9c63953
@StephanTLavavej
Drop unnecessary static_cast<uint64_t> for _Ref(), add internal s…
bbad415 
…tatic assertion.
@StephanTLavavej
Add const to _Bound, _Bound1, _Bound2 params.
592335d
@StephanTLavavej
_Batch_2() should take a reference-to-array.
d9c6d6b
@StephanTLavavej
Extract static_cast<uint64_t>(_Bound) as _Bx.
0b9e0ce
@StephanTLavavej
Drop unused bounds, some with mathematically incorrect comments.
6706d3b
@StephanTLavavej
Comment nitpicks: RNGs => URNGs, RNG => URNG
1655958
@StephanTLavavej
Extract original, add const.
c5019c5
@StephanTLavavej
Avoid unnecessary sorted_v copy.
318f186
@StephanTLavavej
Repeat comments for clarity.
237cf7b
@StephanTLavavej
Condense code to make the pattern clearer on a single screen.
dfbba0e
@StephanTLavavej
Extract shuffle_is_a_permutation(), test a large odd size (1729).
82d9e67
StephanTLavavej
StephanTLavavej reviewed Feb 21, 2026
View reviewed changes
@StephanTLavavej StephanTLavavej moved this from Initial Review to Ready To Merge in STL Code Reviews Feb 21, 2026
@StephanTLavavej StephanTLavavej moved this from Ready To Merge to Merging in STL Code Reviews Feb 23, 2026
@StephanTLavavej
Copy link
Member

StephanTLavavej commented Feb 23, 2026

I'm mirroring this to the MSVC-internal repo. Please notify me if any further changes are pushed, otherwise no action is required.

@StephanTLavavej StephanTLavavej merged commit 333b1df into microsoft:main Feb 24, 2026
45 checks passed
@github-project-automation github-project-automation bot moved this from Merging to Done in STL Code Reviews Feb 24, 2026
@StephanTLavavej
Copy link
Member

StephanTLavavej commented Feb 24, 2026

🚀 🎲 😻

@lemire
Copy link

lemire commented Feb 24, 2026

@StephanTLavavej My employer had be take a training course where we were told that emojis are unprofessional and should be avoided.

🔥 🚀 Go!

This was referenced Feb 25, 2026
Closed
Merged
FranciscoThiesen added a commit to FranciscoThiesen/STL that referenced this pull request Feb 27, 2026
@FranciscoThiesen @claude
<algorithm>: Fix batched random integer generation for shuffle()
74fda0f 
Fix two bugs in the batched shuffle implementation from PR microsoft#5932:

1. `_Unsigned128` brace-initialization zeroed the high word of the
   multiplication result (the random index), making all indices 0 and
   shuffle deterministic. Replace with separate `uint64_t` variables
   for high and low words in both `_Single_bounded` and `_Batch_2`.

2. Loop advancement in `_Random_shuffle_batched` and
   `_Shuffle_unchecked_batched` had extra `++_UTarget` increments
   causing elements to be skipped. Restructure to `for` loops matching
   the original `_Random_shuffle1` pattern.

Add regression test for microsoftGH-6112 and shuffle quality tests adapted from
Lemire's cpp_batched_random test suite (uniformity, coverage, pair
distribution at start/end positions).

Co-Authored-By: Claude <noreply@anthropic.com>
@FranciscoThiesen FranciscoThiesen mentioned this pull request Feb 28, 2026
Open
FranciscoThiesen added a commit to FranciscoThiesen/STL that referenced this pull request Feb 28, 2026
@FranciscoThiesen @claude
<algorithm>: Fix batched random integer generation for shuffle()
86c0c0a 
Fix two bugs in the batched shuffle implementation from PR microsoft#5932:

1. `_Unsigned128` brace-initialization zeroed the high word of the
   multiplication result (the random index), making all indices 0 and
   shuffle deterministic. Replace with separate `uint64_t` variables
   for high and low words in both `_Single_bounded` and `_Batch_2`.

2. Loop advancement in `_Random_shuffle_batched` and
   `_Shuffle_unchecked_batched` had extra `++_UTarget` increments
   causing elements to be skipped. Restructure to `for` loops matching
   the original `_Random_shuffle1` pattern.

Add regression test for microsoftGH-6112 and shuffle quality tests adapted from
Lemire's cpp_batched_random test suite (uniformity, coverage, pair
distribution at start/end positions).

Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@StephanTLavavej StephanTLavavej StephanTLavavej approved these changes

@frederick-vs-ja frederick-vs-ja Awaiting requested review from frederick-vs-ja

Assignees

No one assigned

Labels

performance Must go faster

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

<algorithm>: Investigate further optimizations for shuffle() and sample()

4 participants

@FranciscoThiesen @StephanTLavavej @lemire @frederick-vs-ja