[RFC] Object-scoped RNG implementation

ext/reflection/tests/ReflectionExtension_getClassNames_basic.phpt

@@ -7,14 +7,22 @@ Felix De Vliegher <felix.devliegher@gmail.com>
 $standard = new ReflectionExtension('standard');
 var_dump($standard->getClassNames());
 ?>
---EXPECT--
-array(4) {
+--EXPECTF--
+array(8) {
   [0]=>
-  string(22) "__PHP_Incomplete_Class"
+  %s(22) "__PHP_Incomplete_Class"
   [1]=>
-  string(14) "AssertionError"
+  %s(14) "AssertionError"
   [2]=>
-  string(15) "php_user_filter"
+  %s(15) "php_user_filter"
   [3]=>
-  string(9) "Directory"
+  %s(9) "Directory"
+  [4]=>
+  %s(16) "RNG\RNGInterface"
+  [5]=>
+  %s(19) "RNG\XorShift128Plus"
+  [6]=>
+  %s(11) "RNG\MT19937"
+  [7]=>
+  %s(6) "RNG\OS"
 }

ext/standard/array.c

@@ -42,6 +42,7 @@
 #include "zend_bitset.h"
 #include "zend_exceptions.h"
 #include "ext/spl/spl_array.h"
+#include "php_rng.h"
 
 /* {{{ defines */
 #define EXTR_OVERWRITE			0
@@ -2828,7 +2829,7 @@ PHP_FUNCTION(range)
 #undef RANGE_CHECK_DOUBLE_INIT_ARRAY
 #undef RANGE_CHECK_LONG_INIT_ARRAY
 
-static void php_array_data_shuffle(zval *array) /* {{{ */
+static void php_array_data_shuffle(zval *array, zval *zrng) /* {{{ */
 {
 	uint32_t idx, j, n_elems;
 	Bucket *p, temp;
@@ -2857,7 +2858,7 @@ static void php_array_data_shuffle(zval *array) /* {{{ */
 			}
 		}
 		while (--n_left) {
-			rnd_idx = php_mt_rand_range(0, n_left);
+			rnd_idx = zrng ? php_rng_range(zrng, 0, n_left) : php_mt_rand_range(0, n_left);
 			if (rnd_idx != n_left) {
 				temp = hash->arData[n_left];
 				hash->arData[n_left] = hash->arData[rnd_idx];
@@ -2882,7 +2883,7 @@ static void php_array_data_shuffle(zval *array) /* {{{ */
 			}
 		}
 		while (--n_left) {
-			rnd_idx = php_mt_rand_range(0, n_left);
+			rnd_idx = zrng ? php_rng_range(zrng, 0, n_left) : php_mt_rand_range(0, n_left);
 			if (rnd_idx != n_left) {
 				temp = hash->arData[n_left];
 				hash->arData[n_left] = hash->arData[rnd_idx];
@@ -2912,13 +2913,15 @@ static void php_array_data_shuffle(zval *array) /* {{{ */
 /* {{{ Randomly shuffle the contents of an array */
 PHP_FUNCTION(shuffle)
 {
-	zval *array;
+	zval *array, *zrng = NULL;
 
-	ZEND_PARSE_PARAMETERS_START(1, 1)
+	ZEND_PARSE_PARAMETERS_START(1, 2)
 		Z_PARAM_ARRAY_EX(array, 0, 1)
+		Z_PARAM_OPTIONAL
+		Z_PARAM_OBJECT_OF_CLASS_OR_NULL(zrng, rng_ce_RNG_RNGInterface)
 	ZEND_PARSE_PARAMETERS_END();
 
-	php_array_data_shuffle(array);
+	php_array_data_shuffle(array, zrng);
 
 	RETURN_TRUE;
 }
@@ -5556,7 +5559,7 @@ PHP_FUNCTION(array_multisort)
 /* {{{ Return key/keys for random entry/entries in the array */
 PHP_FUNCTION(array_rand)
 {
-	zval *input;
+	zval *input, *zrng = NULL;
 	zend_long num_req = 1;
 	zend_string *string_key;
 	zend_ulong num_key;
@@ -5567,10 +5570,11 @@ PHP_FUNCTION(array_rand)
 	uint32_t bitset_len;
 	ALLOCA_FLAG(use_heap)
 
-	ZEND_PARSE_PARAMETERS_START(1, 2)
+	ZEND_PARSE_PARAMETERS_START(1, 3)
 		Z_PARAM_ARRAY(input)
 		Z_PARAM_OPTIONAL
 		Z_PARAM_LONG(num_req)
+		Z_PARAM_OBJECT_OF_CLASS_OR_NULL(zrng, rng_ce_RNG_RNGInterface)
 	ZEND_PARSE_PARAMETERS_END();
 
 	num_avail = zend_hash_num_elements(Z_ARRVAL_P(input));
@@ -5586,7 +5590,7 @@ PHP_FUNCTION(array_rand)
 		if ((uint32_t)num_avail < ht->nNumUsed - (ht->nNumUsed>>1)) {
 			/* If less than 1/2 of elements are used, don't sample. Instead search for a
 			 * specific offset using linear scan. */
-			zend_long i = 0, randval = php_mt_rand_range(0, num_avail - 1);
+			zend_long i = 0, randval = zrng ? php_rng_range(zrng, 0, num_avail - 1) : php_mt_rand_range(0, num_avail - 1);
 			ZEND_HASH_FOREACH_KEY(Z_ARRVAL_P(input), num_key, string_key) {
 				if (i == randval) {
 					if (string_key) {
@@ -5604,7 +5608,7 @@ PHP_FUNCTION(array_rand)
 		 * probability of hitting N empty elements in a row is (1-1/2)**N.
 		 * For N=10 this becomes smaller than 0.1%. */
 		do {
-			zend_long randval = php_mt_rand_range(0, ht->nNumUsed - 1);
+			zend_long randval = zrng ? php_rng_range(zrng, 0, ht->nNumUsed - 1) : php_mt_rand_range(0, ht->nNumUsed - 1);
 			Bucket *bucket = &ht->arData[randval];
 			if (!Z_ISUNDEF(bucket->val)) {
 				if (bucket->key) {
@@ -5634,7 +5638,7 @@ PHP_FUNCTION(array_rand)
 
 	i = num_req;
 	while (i) {
-		zend_long randval = php_mt_rand_range(0, num_avail - 1);
+		zend_long randval = zrng ? php_rng_range(zrng, 0, num_avail - 1) : php_mt_rand_range(0, num_avail - 1);
 		if (!zend_bitset_in(bitset, randval)) {
 			zend_bitset_incl(bitset, randval);
 			i--;

ext/standard/basic_functions.c

@@ -34,6 +34,7 @@
 #include "ext/standard/php_uuencode.h"
 #include "ext/standard/php_mt_rand.h"
 #include "ext/standard/crc32_x86.h"
+#include "ext/standard/php_rng.h"
 
 #ifdef PHP_WIN32
 #include "win32/php_win32_globals.h"
@@ -412,6 +413,8 @@ PHP_MINIT_FUNCTION(basic) /* {{{ */
 
 	BASIC_MINIT_SUBMODULE(hrtime)
 
+	BASIC_MINIT_SUBMODULE(rng)
+
 	return SUCCESS;
 }
 /* }}} */

ext/standard/basic_functions.stub.php

@@ -139,7 +139,7 @@ function array_fill_keys(array $keys, mixed $value): array {}
  */
 function range($start, $end, int|float $step = 1): array {}
 
-function shuffle(array &$array): bool {}
+function shuffle(array &$array, ?RNG\RNGInterface $rng = null): bool {}
 
 function array_pop(array &$array): mixed {}
 
@@ -231,7 +231,7 @@ function array_udiff_uassoc(array $array, ...$rest): array {}
  */
 function array_multisort(&$array, &...$rest): bool {}
 
-function array_rand(array $array, int $num = 1): int|string|array {}
+function array_rand(array $array, int $num = 1, ?RNG\RNGInterface $rng = null): int|string|array {}
 
 function array_sum(array $array): int|float {}
 
@@ -683,7 +683,7 @@ function sscanf(string $string, string $format, mixed &...$vars): array|int|null
 
 function str_rot13(string $string): string {}
 
-function str_shuffle(string $string): string {}
+function str_shuffle(string $string, ?RNG\RNGInterface $rng = null): string {}
 
 function str_word_count(string $string, int $format = 0, ?string $characters = null): array|int {}
 
@@ -1203,6 +1203,17 @@ function random_bytes(int $length): string {}
 
 function random_int(int $min, int $max): int {}
 
+/* rng.c */
+
+function rng_bytes(RNG\RNGInterface $rng, int $length): string {}
+
+function rng_int(RNG\RNGInterface $rng, int $min, int $max): int {}
+
+function rng_next(RNG\RNGInterface $rng, bool $unsigned = true): int {}
+
+/** @throws ValueError */
+function rng_next64(RNG\RNGInterface $rng, bool $unsigned = true): int {}
+
 /* soundex.c */
 
 function soundex(string $string): string {}

ext/standard/basic_functions_arginfo.h

@@ -1,5 +1,5 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: 23c263defa042155631bec5fcb5282e4cd1e88a7 */
+ * Stub hash: f84bdc5decf171d559698bc9b40b0582ea57b084 */
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_set_time_limit, 0, 1, _IS_BOOL, 0)
 	ZEND_ARG_TYPE_INFO(0, seconds, IS_LONG, 0)
@@ -186,7 +186,10 @@ ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_range, 0, 2, IS_ARRAY, 0)
 	ZEND_ARG_TYPE_MASK(0, step, MAY_BE_LONG|MAY_BE_DOUBLE, "1")
 ZEND_END_ARG_INFO()
 
-#define arginfo_shuffle arginfo_natsort
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_shuffle, 0, 1, _IS_BOOL, 0)
+	ZEND_ARG_TYPE_INFO(1, array, IS_ARRAY, 0)
+	ZEND_ARG_OBJ_INFO_WITH_DEFAULT_VALUE(0, rng, RNG\\RNGInterface, 1, "null")
+ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_array_pop, 0, 1, IS_MIXED, 0)
 	ZEND_ARG_TYPE_INFO(1, array, IS_ARRAY, 0)
@@ -316,6 +319,7 @@ ZEND_END_ARG_INFO()
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_MASK_EX(arginfo_array_rand, 0, 1, MAY_BE_LONG|MAY_BE_STRING|MAY_BE_ARRAY)
 	ZEND_ARG_TYPE_INFO(0, array, IS_ARRAY, 0)
 	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, num, IS_LONG, 0, "1")
+	ZEND_ARG_OBJ_INFO_WITH_DEFAULT_VALUE(0, rng, RNG\\RNGInterface, 1, "null")
 ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_MASK_EX(arginfo_array_sum, 0, 1, MAY_BE_LONG|MAY_BE_DOUBLE)
@@ -1066,7 +1070,10 @@ ZEND_END_ARG_INFO()
 
 #define arginfo_str_rot13 arginfo_base64_encode
 
-#define arginfo_str_shuffle arginfo_base64_encode
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_str_shuffle, 0, 1, IS_STRING, 0)
+	ZEND_ARG_TYPE_INFO(0, string, IS_STRING, 0)
+	ZEND_ARG_OBJ_INFO_WITH_DEFAULT_VALUE(0, rng, RNG\\RNGInterface, 1, "null")
+ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_MASK_EX(arginfo_str_word_count, 0, 1, MAY_BE_ARRAY|MAY_BE_LONG)
 	ZEND_ARG_TYPE_INFO(0, string, IS_STRING, 0)
@@ -1838,6 +1845,24 @@ ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_random_int, 0, 2, IS_LONG, 0)
 	ZEND_ARG_TYPE_INFO(0, max, IS_LONG, 0)
 ZEND_END_ARG_INFO()
 
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_rng_bytes, 0, 2, IS_STRING, 0)
+	ZEND_ARG_OBJ_INFO(0, rng, RNG\\RNGInterface, 0)
+	ZEND_ARG_TYPE_INFO(0, length, IS_LONG, 0)
+ZEND_END_ARG_INFO()
+
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_rng_int, 0, 3, IS_LONG, 0)
+	ZEND_ARG_OBJ_INFO(0, rng, RNG\\RNGInterface, 0)
+	ZEND_ARG_TYPE_INFO(0, min, IS_LONG, 0)
+	ZEND_ARG_TYPE_INFO(0, max, IS_LONG, 0)
+ZEND_END_ARG_INFO()
+
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_rng_next, 0, 1, IS_LONG, 0)
+	ZEND_ARG_OBJ_INFO(0, rng, RNG\\RNGInterface, 0)
+	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, unsigned, _IS_BOOL, 0, "true")
+ZEND_END_ARG_INFO()
+
+#define arginfo_rng_next64 arginfo_rng_next
+
 #define arginfo_soundex arginfo_base64_encode
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_MASK_EX(arginfo_stream_select, 0, 4, MAY_BE_LONG|MAY_BE_FALSE)
@@ -2730,6 +2755,10 @@ ZEND_FUNCTION(mt_rand);
 ZEND_FUNCTION(mt_getrandmax);
 ZEND_FUNCTION(random_bytes);
 ZEND_FUNCTION(random_int);
+ZEND_FUNCTION(rng_bytes);
+ZEND_FUNCTION(rng_int);
+ZEND_FUNCTION(rng_next);
+ZEND_FUNCTION(rng_next64);
 ZEND_FUNCTION(soundex);
 ZEND_FUNCTION(stream_select);
 ZEND_FUNCTION(stream_context_create);
@@ -3372,6 +3401,10 @@ static const zend_function_entry ext_functions[] = {
 	ZEND_FALIAS(getrandmax, mt_getrandmax, arginfo_getrandmax)
 	ZEND_FE(random_bytes, arginfo_random_bytes)
 	ZEND_FE(random_int, arginfo_random_int)
+	ZEND_FE(rng_bytes, arginfo_rng_bytes)
+	ZEND_FE(rng_int, arginfo_rng_int)
+	ZEND_FE(rng_next, arginfo_rng_next)
+	ZEND_FE(rng_next64, arginfo_rng_next64)
 	ZEND_FE(soundex, arginfo_soundex)
 	ZEND_FE(stream_select, arginfo_stream_select)
 	ZEND_FE(stream_context_create, arginfo_stream_context_create)

ext/standard/config.m4

@@ -426,6 +426,11 @@ else
   AC_MSG_RESULT(no)
 fi
 
+dnl
+dnl rng
+dnl
+PHP_ADD_SOURCES(PHP_EXT_DIR(standard), rng_xorshift128plus.c rng_mt19937.c rng_os.c)
+
 dnl
 dnl Setup extension sources
 dnl
@@ -440,7 +445,7 @@ PHP_NEW_EXTENSION(standard, array.c base64.c basic_functions.c browscap.c crc32.
                             http_fopen_wrapper.c php_fopen_wrapper.c credits.c css.c \
                             var_unserializer.c ftok.c sha1.c user_filters.c uuencode.c \
                             filters.c proc_open.c streamsfuncs.c http.c password.c \
-                            random.c net.c hrtime.c crc32_x86.c,,,
+                            random.c net.c hrtime.c crc32_x86.c rng.c,,,
 			    -DZEND_ENABLE_STATIC_TSRMLS_CACHE=1)
 
 PHP_ADD_MAKEFILE_FRAGMENT

ext/standard/config.w32

@@ -35,7 +35,8 @@ EXTENSION("standard", "array.c base64.c basic_functions.c browscap.c \
 	url_scanner_ex.c ftp_fopen_wrapper.c http_fopen_wrapper.c \
 	php_fopen_wrapper.c credits.c css.c var_unserializer.c ftok.c sha1.c \
 	user_filters.c uuencode.c filters.c proc_open.c password.c \
-	streamsfuncs.c http.c flock_compat.c random.c hrtime.c", false /* never shared */,
+	streamsfuncs.c http.c flock_compat.c random.c hrtime.c \
+	rng.c rng_xorshift128plus.c rng_mt19937.c rng_os.c ", false /* never shared */,
 	'/DZEND_ENABLE_STATIC_TSRMLS_CACHE=1');
 PHP_STANDARD = "yes";
 ADD_MAKEFILE_FRAGMENT();

ext/standard/php_rng.h

@@ -0,0 +1,48 @@
+/*
+	+----------------------------------------------------------------------+
+	| Copyright (c) The PHP Group                                          |
+	+----------------------------------------------------------------------+
+	| This source file is subject to version 3.01 of the PHP license,      |
+	| that is bundled with this package in the file LICENSE, and is        |
+	| available through the world-wide-web at the following url:           |
+	| http://www.php.net/license/3_01.txt                                  |
+	| If you did not receive a copy of the PHP license and are unable to   |
+	| obtain it through the world-wide-web, please send a note to          |
+	| license@php.net so we can mail you a copy immediately.               |
+	+----------------------------------------------------------------------+
+	| Authors: Go Kudo <zeriyoshi@gmail.com>                               |
+	+----------------------------------------------------------------------+
+*/
+
+#ifndef PHP_RNG_H
+#define PHP_RNG_H
+
+#include "php.h"
+
+extern PHPAPI zend_class_entry *rng_ce_RNG_RNGInterface;
+
+typedef struct _php_rng php_rng;
+typedef struct _php_rng {
+	uint32_t (*next)(php_rng*);
+	uint64_t (*next64)(php_rng*);
+	zend_long (*range)(php_rng*); // optional for object defined range implementation.
+	void *state;
+	zend_object std;
+} php_rng;
+
+static inline php_rng *rng_from_obj(zend_object *obj) {
+	return (php_rng*)((char*)(obj) - XtOffsetOf(php_rng, std));
+}
+
+#define Z_RNG_P(zval) rng_from_obj(Z_OBJ_P(zval))
+
+PHP_MINIT_FUNCTION(rng);
+
+#define RNG_NAMESPACE "RNG\\"
+
+PHPAPI php_rng *php_rng_initialize(uint32_t (*next)(php_rng*), uint64_t (*next64)(php_rng*));
+PHPAPI int php_rng_next(uint32_t*, zval*);
+PHPAPI int php_rng_next64(uint64_t*, zval*);
+PHPAPI zend_long php_rng_range(zval*, zend_long, zend_long);
+
+#endif