random: Optimize data flow for the generate function of native engines (#13043)

Instead of returning the generated `uint64_t` and providing the size (i.e. the
number of bytes of the generated value) out-of-band via the
`last_generated_size` member of the `php_random_status` struct, the `generate`
function is now expected to return a new `php_random_result` struct containing
both the `size` and the `result`.

This has two benefits, one for the developer:

It's no longer possible to forget setting `last_generated_size` to the correct
value, because it now happens at the time of returning from the function.

and the other benefit is for performance:

The `php_random_result` struct will be returned as a register pair, thus the
`size` will be directly available without reloading it from main memory.

Checking a simplified version of `php_random_range64()` on Compiler Explorer
(“Godbolt”) with clang 17 shows a single change in the resulting assembly
showcasing the improvement (https://godbolt.org/z/G4WjdYxqx):

    - add     rbp, qword ptr [r14]
    + add     rbp, rdx

Empirical testing confirms a measurable performance increase for the
`Randomizer::getBytes()` method:

    <?php
    $e = new Random\Engine\Xoshiro256StarStar(0);
    $r = new Random\Randomizer($e);

    var_dump(strlen($r->getBytes(100000000)));

goes from 250ms (before the change) to 220ms (after the change). While
generating 100 MB of random data certainly is not the most common use case, it
confirms the theoretical improvement in practice.

Author: TimWolla

UPGRADING.INTERNALS

@@ -47,6 +47,10 @@ PHP 8.4 INTERNALS UPGRADE NOTES
    - The macro RAND_RANGE_BADSCALING() has been removed. The implementation
      should either be inlined and undefined behavior fixed or it should be
      replaced by a non-biased scaler.
+   - The generate member of a php_random_algo is now expected to return
+     the new php_random_result struct, replacing the last_generated_size
+     member of the php_random_status struct and the generate_size member of
+     the php_random_algo struct.
 
  c. ext/xsl
    - The function php_xsl_create_object() was removed as it was not used

ext/random/engine_combinedlcg.c

@@ -40,7 +40,7 @@ static void seed(php_random_status *status, uint64_t seed)
 	s->state[1] = seed >> 32;
 }
 
-static uint64_t generate(php_random_status *status)
+static php_random_result generate(php_random_status *status)
 {
 	php_random_status_state_combinedlcg *s = status->state;
 	int32_t q, z;
@@ -53,7 +53,10 @@ static uint64_t generate(php_random_status *status)
 		z += 2147483562;
 	}
 
-	return (uint64_t) z;
+	return (php_random_result){
+		.size = sizeof(uint32_t),
+		.result = (uint64_t) z,
+	};
 }
 
 static zend_long range(php_random_status *status, zend_long min, zend_long max)
@@ -93,7 +96,6 @@ static bool unserialize(php_random_status *status, HashTable *data)
 }
 
 const php_random_algo php_random_algo_combinedlcg = {
-	sizeof(uint32_t),
 	sizeof(php_random_status_state_combinedlcg),
 	seed,
 	generate,

ext/random/engine_mt19937.c

@@ -143,7 +143,7 @@ static void seed(php_random_status *status, uint64_t seed)
 	mt19937_seed_state(status->state, seed);
 }
 
-static uint64_t generate(php_random_status *status)
+static php_random_result generate(php_random_status *status)
 {
 	php_random_status_state_mt19937 *s = status->state;
 	uint32_t s1;
@@ -157,7 +157,10 @@ static uint64_t generate(php_random_status *status)
 	s1 ^= (s1 << 7) & 0x9d2c5680U;
 	s1 ^= (s1 << 15) & 0xefc60000U;
 
-	return (uint64_t) (s1 ^ (s1 >> 18));
+	return (php_random_result){
+		.size = sizeof(uint32_t),
+		.result = (uint64_t) (s1 ^ (s1 >> 18)),
+	};
 }
 
 static zend_long range(php_random_status *status, zend_long min, zend_long max)
@@ -223,7 +226,6 @@ static bool unserialize(php_random_status *status, HashTable *data)
 }
 
 const php_random_algo php_random_algo_mt19937 = {
-	sizeof(uint32_t),
 	sizeof(php_random_status_state_mt19937),
 	seed,
 	generate,
@@ -288,25 +290,22 @@ PHP_METHOD(Random_Engine_Mt19937, __construct)
 PHP_METHOD(Random_Engine_Mt19937, generate)
 {
 	php_random_engine *engine = Z_RANDOM_ENGINE_P(ZEND_THIS);
-	uint64_t generated;
-	size_t size;
 	zend_string *bytes;
 
 	ZEND_PARSE_PARAMETERS_NONE();
 
-	generated = engine->algo->generate(engine->status);
-	size = engine->status->last_generated_size;
+	php_random_result generated = engine->algo->generate(engine->status);
 	if (EG(exception)) {
 		RETURN_THROWS();
 	}
 
-	bytes = zend_string_alloc(size, false);
+	bytes = zend_string_alloc(generated.size, false);
 
 	/* Endianness safe copy */
-	for (size_t i = 0; i < size; i++) {
-		ZSTR_VAL(bytes)[i] = (generated >> (i * 8)) & 0xff;
+	for (size_t i = 0; i < generated.size; i++) {
+		ZSTR_VAL(bytes)[i] = (generated.result >> (i * 8)) & 0xff;
 	}
-	ZSTR_VAL(bytes)[size] = '\0';
+	ZSTR_VAL(bytes)[generated.size] = '\0';
 
 	RETURN_STR(bytes);
 }

ext/random/engine_pcgoneseq128xslrr64.c

@@ -47,12 +47,16 @@ static void seed(php_random_status *status, uint64_t seed)
 	seed128(status, php_random_uint128_constant(0ULL, seed));
 }
 
-static uint64_t generate(php_random_status *status)
+static php_random_result generate(php_random_status *status)
 {
 	php_random_status_state_pcgoneseq128xslrr64 *s = status->state;
 
 	step(s);
-	return php_random_pcgoneseq128xslrr64_rotr64(s->state);
+
+	return (php_random_result){
+		.size = sizeof(uint64_t),
+		.result = php_random_pcgoneseq128xslrr64_rotr64(s->state),
+	};
 }
 
 static zend_long range(php_random_status *status, zend_long min, zend_long max)
@@ -103,7 +107,6 @@ static bool unserialize(php_random_status *status, HashTable *data)
 }
 
 const php_random_algo php_random_algo_pcgoneseq128xslrr64 = {
-	sizeof(uint64_t),
 	sizeof(php_random_status_state_pcgoneseq128xslrr64),
 	seed,
 	generate,

ext/random/engine_secure.c

@@ -24,13 +24,16 @@
 
 #include "Zend/zend_exceptions.h"
 
-static uint64_t generate(php_random_status *status)
+static php_random_result generate(php_random_status *status)
 {
 	zend_ulong r = 0;
 
 	php_random_bytes_throw(&r, sizeof(zend_ulong));
 
-	return r;
+	return (php_random_result){
+		.size = sizeof(zend_ulong),
+		.result = r,
+	};
 }
 
 static zend_long range(php_random_status *status, zend_long min, zend_long max)
@@ -43,7 +46,6 @@ static zend_long range(php_random_status *status, zend_long min, zend_long max)
 }
 
 const php_random_algo php_random_algo_secure = {
-	sizeof(zend_ulong),
 	0,
 	NULL,
 	generate,

ext/random/engine_user.c

@@ -21,7 +21,7 @@
 #include "php.h"
 #include "php_random.h"
 
-static uint64_t generate(php_random_status *status)
+static php_random_result generate(php_random_status *status)
 {
 	php_random_status_state_user *s = status->state;
 	uint64_t result = 0;
@@ -31,17 +31,18 @@ static uint64_t generate(php_random_status *status)
 	zend_call_known_instance_method_with_0_params(s->generate_method, s->object, &retval);
 
 	if (EG(exception)) {
-		return 0;
+		return (php_random_result){
+			.size = sizeof(uint64_t),
+			.result = 0,
+		};
 	}
 
-	/* Store generated size in a state */
 	size = Z_STRLEN(retval);
 
 	/* Guard for over 64-bit results */
 	if (size > sizeof(uint64_t)) {
 		size = sizeof(uint64_t);
 	}
-	status->last_generated_size = size;
 
 	if (size > 0) {
 		/* Endianness safe copy */
@@ -50,12 +51,18 @@ static uint64_t generate(php_random_status *status)
 		}
 	} else {
 		zend_throw_error(random_ce_Random_BrokenRandomEngineError, "A random engine must return a non-empty string");
-		return 0;
+		return (php_random_result){
+			.size = sizeof(uint64_t),
+			.result = 0,
+		};
 	}
 
 	zval_ptr_dtor(&retval);
 
-	return result;
+	return (php_random_result){
+		.size = size,
+		.result = result,
+	};
 }
 
 static zend_long range(php_random_status *status, zend_long min, zend_long max)
@@ -64,7 +71,6 @@ static zend_long range(php_random_status *status, zend_long min, zend_long max)
 }
 
 const php_random_algo php_random_algo_user = {
-	0,
 	sizeof(php_random_status_state_user),
 	NULL,
 	generate,

ext/random/engine_xoshiro256starstar.c

@@ -103,9 +103,12 @@ static void seed(php_random_status *status, uint64_t seed)
 	seed256(status, s[0], s[1], s[2], s[3]);
 }
 
-static uint64_t generate(php_random_status *status)
+static php_random_result generate(php_random_status *status)
 {
-	return generate_state(status->state);
+	return (php_random_result){
+		.size = sizeof(uint64_t),
+		.result = generate_state(status->state),
+	};
 }
 
 static zend_long range(php_random_status *status, zend_long min, zend_long max)
@@ -150,7 +153,6 @@ static bool unserialize(php_random_status *status, HashTable *data)
 }
 
 const php_random_algo php_random_algo_xoshiro256starstar = {
-	sizeof(uint64_t),
 	sizeof(php_random_status_state_xoshiro256starstar),
 	seed,
 	generate,

ext/random/php_random.h

@@ -191,7 +191,6 @@ static inline zend_result php_random_int_silent(zend_long min, zend_long max, ze
 }
 
 typedef struct _php_random_status_ {
-	size_t last_generated_size;
 	void *state;
 } php_random_status;
 
@@ -218,11 +217,15 @@ typedef struct _php_random_status_state_user {
 	zend_function *generate_method;
 } php_random_status_state_user;
 
+typedef struct _php_random_result {
+	const uint64_t result;
+	const size_t size;
+} php_random_result;
+
 typedef struct _php_random_algo {
-	const size_t generate_size;
 	const size_t state_size;
 	void (*seed)(php_random_status *status, uint64_t seed);
-	uint64_t (*generate)(php_random_status *status);
+	php_random_result (*generate)(php_random_status *status);
 	zend_long (*range)(php_random_status *status, zend_long min, zend_long max);
 	bool (*serialize)(php_random_status *status, HashTable *data);
 	bool (*unserialize)(php_random_status *status, HashTable *data);

ext/random/random.c

@@ -82,9 +82,9 @@ PHPAPI uint32_t php_random_range32(const php_random_algo *algo, php_random_statu
 	result = 0;
 	total_size = 0;
 	do {
-		uint32_t r = algo->generate(status);
-		result = result | (r << (total_size * 8));
-		total_size += status->last_generated_size;
+		php_random_result r = algo->generate(status);
+		result = result | (((uint32_t) r.result) << (total_size * 8));
+		total_size += r.size;
 		if (EG(exception)) {
 			return 0;
 		}
@@ -117,9 +117,9 @@ PHPAPI uint32_t php_random_range32(const php_random_algo *algo, php_random_statu
 		result = 0;
 		total_size = 0;
 		do {
-			uint32_t r = algo->generate(status);
-			result = result | (r << (total_size * 8));
-			total_size += status->last_generated_size;
+			php_random_result r = algo->generate(status);
+			result = result | (((uint32_t) r.result) << (total_size * 8));
+			total_size += r.size;
 			if (EG(exception)) {
 				return 0;
 			}
@@ -138,9 +138,9 @@ PHPAPI uint64_t php_random_range64(const php_random_algo *algo, php_random_statu
 	result = 0;
 	total_size = 0;
 	do {
-		uint64_t r = algo->generate(status);
-		result = result | (r << (total_size * 8));
-		total_size += status->last_generated_size;
+		php_random_result r = algo->generate(status);
+		result = result | (r.result << (total_size * 8));
+		total_size += r.size;
 		if (EG(exception)) {
 			return 0;
 		}
@@ -173,9 +173,9 @@ PHPAPI uint64_t php_random_range64(const php_random_algo *algo, php_random_statu
 		result = 0;
 		total_size = 0;
 		do {
-			uint64_t r = algo->generate(status);
-			result = result | (r << (total_size * 8));
-			total_size += status->last_generated_size;
+			php_random_result r = algo->generate(status);
+			result = result | (r.result << (total_size * 8));
+			total_size += r.size;
 			if (EG(exception)) {
 				return 0;
 			}
@@ -229,15 +229,13 @@ PHPAPI php_random_status *php_random_status_alloc(const php_random_algo *algo, c
 {
 	php_random_status *status = pecalloc(1, sizeof(php_random_status), persistent);
 
-	status->last_generated_size = algo->generate_size;
 	status->state = algo->state_size > 0 ? pecalloc(1, algo->state_size, persistent) : NULL;
 
 	return status;
 }
 
 PHPAPI php_random_status *php_random_status_copy(const php_random_algo *algo, php_random_status *old_status, php_random_status *new_status)
 {
-	new_status->last_generated_size = old_status->last_generated_size;
 	new_status->state = memcpy(new_status->state, old_status->state, algo->state_size);
 
 	return new_status;
@@ -400,7 +398,7 @@ PHPAPI double php_combined_lcg(void)
 		RANDOM_G(combined_lcg_seeded) = true;
 	}
 
-	return php_random_algo_combinedlcg.generate(status) * 4.656613e-10;
+	return php_random_algo_combinedlcg.generate(status).result * 4.656613e-10;
 }
 /* }}} */
 
@@ -415,7 +413,7 @@ PHPAPI void php_mt_srand(uint32_t seed)
 /* {{{ php_mt_rand */
 PHPAPI uint32_t php_mt_rand(void)
 {
-	return (uint32_t) php_random_algo_mt19937.generate(php_random_default_status());
+	return (uint32_t) php_random_algo_mt19937.generate(php_random_default_status()).result;
 }
 /* }}} */
 
@@ -437,7 +435,7 @@ PHPAPI zend_long php_mt_rand_common(zend_long min, zend_long max)
 		return php_mt_rand_range(min, max);
 	}
 
-	uint64_t r = php_random_algo_mt19937.generate(php_random_default_status()) >> 1;
+	uint64_t r = php_random_algo_mt19937.generate(php_random_default_status()).result >> 1;
 
 	/* This is an inlined version of the RAND_RANGE_BADSCALING macro that does not invoke UB when encountering
 	 * (max - min) > ZEND_LONG_MAX.