[PATCH v6] libstdc++: Implement Philox Engine (PR119794)
Jonathan Wakely
jwakely@redhat.com
Mon Sep 8 15:25:54 GMT 2025
On Mon, 08 Sep 2025 at 15:55 +0100, Jonathan Wakely wrote:
>On Tue, 05 Aug 2025 at 09:21 +0000, 1nfocalypse wrote:
>>Implements Philox Engine (P2075R6) and associated tests.
>>
>>Implements additional feedback from v5 from Patrick Palka.
>>Also cut some trailing whitespace from the limb propagation
>>fix in v5.
>>
>>Apologies for the delay from v5 - I had to finish writing some
>>CTF challenges for DEFCON this week. Thank you for the
>>feedback, and please let me know if anything further needs
>>to be changed.
>>
>>Built/tested on x86_64-pc-linux-gnu.
>
>>From 23ffd0ca595c27e8721d6d73ac746293aace7771 Mon Sep 17 00:00:00 2001
>>From: 1nfocalypse <1nfocalypse@protonmail.com>
>>Date: Tue, 5 Aug 2025 01:37:18 +0000
>>Subject: [PATCH] [PATCH v6] libstdc++: Implement Philox Engine (PR119794)
>>
>>Implemented additional changes from Patrick Palka.
>>Also removed some trailing whitespace in random.tcc.
>>
>>replaced alias of __ios_base with ios_base
>>included <iomanip> in random.h
>>altered line number in pr60037-neg.cc to be accurate
>>Refactored iterator/index loops to be range-based for
>>in istream/ostream operator overloads
>>include <random> in philox_engine/cons/seed_seq.cc
>>Conforms with errata LWG4143, LWG4153 for Philox Engine.
>>
>> PR libstdc++/119794
>>---
>>libstdc++-v3/include/bits/random.h | 283 ++++++++++++++++++
>>libstdc++-v3/include/bits/random.tcc | 191 ++++++++++++
>>libstdc++-v3/include/bits/version.def | 9 +
>>libstdc++-v3/include/bits/version.h | 10 +
>>libstdc++-v3/include/std/random | 3 +
>>.../26_numerics/random/philox4x32.cc | 23 ++
>>.../26_numerics/random/philox4x64.cc | 23 ++
>>.../random/philox_engine/cons/119794.cc | 39 +++
>>.../random/philox_engine/cons/copy.cc | 25 ++
>>.../random/philox_engine/cons/default.cc | 27 ++
>>.../random/philox_engine/cons/seed.cc | 20 ++
>>.../random/philox_engine/cons/seed_seq.cc | 24 ++
>>.../random/philox_engine/operators/equal.cc | 30 ++
>>.../random/philox_engine/operators/inequal.cc | 30 ++
>>.../philox_engine/operators/serialize.cc | 49 +++
>>.../philox_engine/requirements/constants.cc | 26 ++
>>.../requirements/constexpr_data.cc | 50 ++++
>>.../requirements/constexpr_functions.cc | 41 +++
>>.../philox_engine/requirements/typedefs.cc | 26 ++
>>.../26_numerics/random/pr60037-neg.cc | 4 +-
>>20 files changed, 931 insertions(+), 2 deletions(-)
>>create mode 100644 libstdc++-v3/testsuite/26_numerics/random/philox4x32.cc
>>create mode 100644 libstdc++-v3/testsuite/26_numerics/random/philox4x64.cc
>>create mode 100644 libstdc++-v3/testsuite/26_numerics/random/philox_engine/cons/119794.cc
>>create mode 100644 libstdc++-v3/testsuite/26_numerics/random/philox_engine/cons/copy.cc
>>create mode 100644 libstdc++-v3/testsuite/26_numerics/random/philox_engine/cons/default.cc
>>create mode 100644 libstdc++-v3/testsuite/26_numerics/random/philox_engine/cons/seed.cc
>>create mode 100644 libstdc++-v3/testsuite/26_numerics/random/philox_engine/cons/seed_seq.cc
>>create mode 100644 libstdc++-v3/testsuite/26_numerics/random/philox_engine/operators/equal.cc
>>create mode 100644 libstdc++-v3/testsuite/26_numerics/random/philox_engine/operators/inequal.cc
>>create mode 100644 libstdc++-v3/testsuite/26_numerics/random/philox_engine/operators/serialize.cc
>>create mode 100644 libstdc++-v3/testsuite/26_numerics/random/philox_engine/requirements/constants.cc
>>create mode 100644 libstdc++-v3/testsuite/26_numerics/random/philox_engine/requirements/constexpr_data.cc
>>create mode 100644 libstdc++-v3/testsuite/26_numerics/random/philox_engine/requirements/constexpr_functions.cc
>>create mode 100644 libstdc++-v3/testsuite/26_numerics/random/philox_engine/requirements/typedefs.cc
>>
>>diff --git a/libstdc++-v3/include/bits/random.h b/libstdc++-v3/include/bits/random.h
>>index 1fdaf51934f..e74b7bd75c0 100644
>>--- a/libstdc++-v3/include/bits/random.h
>>+++ b/libstdc++-v3/include/bits/random.h
>>@@ -33,6 +33,7 @@
>>
>>#include <vector>
>>#include <bits/uniform_int_dist.h>
>>+#include <iomanip>
>>
>>namespace std _GLIBCXX_VISIBILITY(default)
>>{
>>@@ -1688,6 +1689,270 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
>> { return !(__lhs == __rhs); }
>>#endif
>>
>>+#if __cpp_lib_philox_engine
>
>This should check __glibcxx_philox_engine (just in case this code is
>moved to a separate header that ends up being included somewhere
>withou all of <random>).
>
>>+ /**
>>+ * @brief: A discrete pseudorandom number generator based off of weakened
No semi-colon after @brief
>>+ * cryptographic primitives.
>
>Can we say "based on" instead of "based off of" which is an informal
>American English term that sounds wrong to me.
>
>I'm also not sure what this is telling me as a non-export user. Would
>it be clearer to talk about it having weak cryptographic properties,
>rather than being based on weakened cryptographic primitives?
>
>>+ *
>>+ * This algorithm was intended to be used for highly parallel random number
>
>"was intended to be used" sounds like it refers to something in the
>past that is no longer true. Maybe "was designed to be used" instead?
>
>>+ * generation, and is capable of immensely long periods. It provides "Crush-
>
>I was going to ask whether immensely is a bit hyperbolic and could be
>just "very long periods (e.g. ...)" but since we're talking at least
>2^128 I think "immensely" is fine :-)
>
>>+ * resistance", denoting an ability to pass the TestU01 Suite's "Big Crush"
>>+ * test, demonstrating significant apparent entropy. It is not intended for
>>+ * cryptographic use and should not be used for such, despite being based on
>>+ * cryptographic primitives.
>>+ *
>>+ * The two four-word definitions are likely the best use for this algorithm,
>>+ * and are given below as defaults.
>
>Can we refer to those as aliases or typedefs rather than definitions?
>Or specializations?
>
>Maybe even say it like this:
>
> * The typedefs `philox4x32` and `philox4x64` are provided as
> * suitable defaults for most use cases, providing high-quality
> * random numbers at reasonable performance.
>
>
>>+ *
>>+ * This algorithm was created by John Salmon, Mark Moraes, Ron Dror, and
>>+ * David Shaw as a product of D.E. Shaw Research.
>>+ *
>>+ * @tparam __w Word size
>>+ * @tparam __n Buffer size
>>+ * @tparam __r Rounds
>>+ * @tparam __consts Multiplication and round constant pack, ordered as
>>+ * M_{0}, C_{0}, M_{1}, C_{1}, ... , M_{N/2-1}, C_{N/2-1}
>>+ *
>>+ * @headerfile random
>>+ * @since C++26
>>+ */
>>+ template<class _UIntType, size_t __w,
>
>Our convention in libstdc++ code is to type 'typename' for template
>parameters instead of 'class'
>
>>+ size_t __n, size_t __r,
>>+ _UIntType... __consts>
>>+ class philox_engine
>>+ {
>>+ static_assert(__n == 2 || __n == 4,
>>+ "template argument N must be either 2 or 4");
>>+ static_assert(sizeof...(__consts) == __n,
>>+ "length of consts array must match specified N");
>>+ static_assert(0 < __r, "a number of rounds must be specified");
>>+ static_assert((0 < __w && __w <= numeric_limits<_UIntType>::digits),
>>+ "specified bitlength must match input type");
>
>The static assert messages all use the preferred "must" form, thanks!
>
>>+ template<typename _Sseq>
>>+ using _If_seed_seq
>>+ = __detail::_If_seed_seq_for<_Sseq, philox_engine, _UIntType>;
>>+
>>+ private:
>
>This access specifier is redundant because everything above it is
>already private.
>
>>+ // the ordering here is essential to functionality.
>
>Does this refer to the ordering of the _S_popArray member in the
>class, because it needs to be declared before it's used?
>
>If so, I think we can drop the comment. If somebody fails to notice
>that when reading the class definition, they'd find out pretty quickly
>if they tried to reorder it and got errors.
>
>The style recommendations to put private internal members last is not
>a hard requirement, for cases like this where the order is significant
>putting them first is obviously fine (since you have no choice! :-)
>
>>+ /** @brief an internal unpacking function for %philox_engine. */
>
>We don't need a doxygen comment for private member functions, they
>won't get included in the docs anyway.
>
>>+ template <size_t __ind0, size_t __ind1>
>>+ static constexpr
>>+ array<_UIntType, __n / 2>
>>+ _S_popArray()
>>+ {
>>+ if constexpr (__n == 4)
>>+ return {__consts...[__ind0], __consts...[__ind1]};
>>+ else
>>+ return {__consts...[__ind0]};
>>+ }
>>+
>>+ public:
>>+ /** Type of template param. */
>>+ using result_type = _UIntType;
>>+ // public members
>>+ static constexpr size_t word_size = __w;
>>+ static constexpr size_t word_count = __n;
>>+ static constexpr size_t round_count = __r;
>>+ static constexpr array<result_type, __n / 2> multipliers =
>>+ philox_engine::_S_popArray<0,2>();
>>+ static constexpr array<result_type, __n / 2> round_consts =
>>+ philox_engine::_S_popArray<1,3>();
>>+
>>+ /** @brief returns the minimum value possible. */
>>+ static constexpr result_type
>>+ min()
>>+ { return 0; }
>>+
>>+ /** @brief returns the maximum value possible. */
>>+ static constexpr result_type
>>+ max()
>>+ {
>>+ return ((1ull << (__w - 1)) | ((1ull << (__w - 1)) - 1));
>>+ }
>>+ // default key value
>>+ static constexpr result_type default_seed = 20111115u;
>
>I wonder if we have a defect in the C++26 draft here, because
>20111115u won't fit in a 16-bit int. We fixed that for
>std::subtract_with_carry_engine via:
>https://cplusplus.github.io/LWG/issue3809
>and then fixed what I broke via:
>https://cplusplus.github.io/LWG/issue4014
>
>Since the value of default_seed is only used as the argument to the
>default ctor (or the equivalent of calling seed() with no argument)
>and the ctor reduces value by mod 2^w, I think we could define the
>default seed as 20111115u & max().
>
>But let's leave it for now, I'll raise this with LWG.
>
>>+
>>+ // constructors
>>+ philox_engine()
>>+ : philox_engine(default_seed)
>>+ {}
>>+
>>+ explicit
>>+ philox_engine(result_type __value);
>>+
>>+ /** @brief seed sequence constructor for %philox_engine
>>+ *
>>+ * @params __q the seed sequence
This should be @param singular, not plural.
(Doxygen allows either @return or @returns, but only @param)
>>+ */
>>+ template<typename _Sseq, typename = _If_seed_seq<_Sseq>>
>>+ explicit
>>+ philox_engine(_Sseq& __q)
>>+ {
>>+ seed(__q);
>>+ }
>>+
>>+ void
>>+ seed(result_type value = default_seed);
>>+
>>+ /** @brief seeds %philox_engine by seed sequence
>>+ *
>>+ * @params __q the seed sequence
>>+ */
>>+ template<typename _Sseq>
>>+ _If_seed_seq<_Sseq>
>>+ seed(_Sseq& __q);
>>+
>>+ /** @brief sets the internal counter "cleartext"
>>+ *
>>+ * @params __counter std::array of len N
>>+ */
>>+ void
>>+ set_counter(const array<result_type, __n>& __counter);
>>+
>>+ /** @brief compares two %philox_engine objects
>>+ *
>>+ * @params __x A %philox_engine object
>>+ * @params __y A %philox_engine object
>>+ *
>>+ * @returns true if the objects will produce an identical stream, false
>>+ * otherwise
>>+ */
>>+ friend bool
>>+ operator==(const philox_engine& __x, const philox_engine& __y)
>>+ {
>>+ return (std::equal(__x._M_x.begin(), __x._M_x.end(),
>>+ __y._M_x.begin(), __y._M_x.end())
>>+ && std::equal(__x._M_y.begin(), __x._M_y.end(),
>>+ __y._M_y.begin(), __y._M_y.end())
>>+ && std::equal(__x._M_k.begin(), __x._M_k.end(),
>>+ __y._M_k.begin(), __y._M_k.end())
>>+ && __x._M_i == __y._M_i);
I was going to suggest that this could use operator== for std::array
and be:
return __x._M_x == __y._M_x && __x._M_y == __x._M_y
&& __x._M_k == __y._M_k && __x._M_i == __y._M_i;
but then I realised that's exactly what the compiler would do for:
friend bool
operator==(const philox_engine&, const philox_engine&) = default;
Is there any reason not to just define it as defaulted?
If we added new internal non-static data members then we'd need to
define operator== explicitly, so that the new members were ignored ...
but are we likely to do that? The entire state is represented by the
existing data members so I don't see why we'd need to add others.
More information about the Libstdc++
mailing list