Класс QRandomGenerator

Класс QRandomGenerator позволяет получать случайные значения с помощью высококачественного генератора случайных чисел. Подробнее...

• Список всех членов, включая наследуемые

Примечание: Все функции в этом классе являются повторно входящими.

Примечание: Эти функции также являются безопасными для потоков:

• system()
• global()

Общедоступные типы

Общедоступные функции

Статические общедоступные члены

Связанные нечлены

Подробное описание

QRandomGenerator может использоваться для генерации случайных значений с помощью высококачественного генератора случайных чисел. Подобно C++ генераторам случайных чисел, QRandomGenerator можно инициализировать значениями, предоставленными пользователем, через конструктор. При инициализации последовательность чисел, генерируемых этим классом, является детерминированной. То есть, при одинаковых данных инициализации QRandomGenerator сгенерирует одну и ту же последовательность чисел. Но при разных начальных значениях результаты должны быть существенно разными.

QRandomGenerator::securelySeeded() можно использовать для создания QRandomGenerator, который будет надежно инициализирован с помощью QRandomGenerator::system(), что означает, что последовательность генерируемых чисел не может быть легко предсказана. Кроме того, QRandomGenerator::global() возвращает глобальный экземпляр QRandomGenerator, который Qt гарантирует надежную инициализацию. Этот объект потокобезопасен, может быть использован совместно для большинства задач и всегда инициализируется из QRandomGenerator::system()

QRandomGenerator::system() можно использовать для доступа к криптографически безопасному генератору случайных чисел системы. В системах Unix он эквивалентен чтению из /dev/urandom или системных вызовов getrandom() или getentropy().

Класс может генерировать 32-битные или 64-битные величины или заполнять массив этими значениями. Наиболее распространенный способ генерации новых значений — вызов функций generate(), generate64() или fillRange(). Пример использования:

    quint32 value = QRandomGenerator::global()->generate();

Кроме того, он предоставляет функцию с плавающей точкой generateDouble(), которая возвращает число в диапазоне [0, 1) (включая ноль и не включая 1). Также есть набор вспомогательных функций, которые облегчают получение случайного числа в ограниченном целочисленном диапазоне.

Инициализация и детерминизм

QRandomGenerator можно инициализировать конкретными данными. Когда это сделано, числа, генерируемые объектом, всегда будут одинаковыми, как в следующем примере:

    QRandomGenerator prng1(1234), prng2(1234);
    Q_ASSERT(prng1.generate() == prng2.generate());
    Q_ASSERT(prng1.generate64() == prng2.generate64());

Данные инициализации представляют собой одно или несколько 32-битных слов. Идеальный размер данных инициализации приблизительно равен размеру самого класса QRandomGenerator. Из-за смешивания данных инициализации QRandomGenerator не может гарантировать, что различные данные инициализации приведут к различным последовательностям.

QRandomGenerator::global(), как и все генераторы, созданные с помощью QRandomGenerator::securelySeeded(), всегда инициализируются из QRandomGenerator::system(), поэтому невозможно заставить его генерировать идентичные последовательности.

Массовая генерация данных

При работе в детерминированном режиме QRandomGenerator может использоваться для массовой генерации данных. На самом деле, приложениям, которым не нужны криптографически защищенные или истинные случайные данные, рекомендуется использовать обычный QRandomGenerator вместо QRandomGenerator::system() для своих потребностей в случайных данных.

Для удобства использования QRandomGenerator предоставляет глобальный объект, который легко использовать, как в следующем примере:

    int x = QRandomGenerator::global()->generate();
    int y = QRandomGenerator::global()->generate();
    int w = QRandomGenerator::global()->bounded(16384);
    int h = QRandomGenerator::global()->bounded(16384);

Генератор случайных чисел системы

QRandomGenerator::system() может использоваться для доступа к генератору случайных чисел системы, который является криптографически безопасным на всех системах, на которых работает Qt. Эта функция будет использовать аппаратные средства для генерации случайных чисел, где это возможно. На таких системах эти средства являются истинными генераторами случайных чисел. Однако, если это истинные генераторы случайных чисел, эти средства имеют ограниченные источники энтропии и могут не генерировать результаты, если их пул энтропии исчерпан.

Если это происходит, сначала операционная система, а затем QRandomGenerator переходят к псевдогенераторам случайных чисел с уменьшающимся качеством (генератор отката Qt является самым простым). Являются ли эти генераторы по-прежнему криптографически безопасными, определяется реализацией. Поэтому QRandomGenerator::system() не следует использовать для генерации случайных чисел с высокой частотой, чтобы пул энтропии не стал пустым. Как правило, этот класс не должен вызываться для генерации более килобайта случайных данных в секунду (примечание: это может варьироваться от системы к системе).

Если приложению нужны данные истинного генератора случайных чисел (True RNG) в большом объеме, оно должно использовать средства операционной системы (например, /dev/random в Linux) напрямую и ожидать появления энтропии. Если приложение требует псевдогенераторов случайных чисел (PRNG) криптографического качества, но не истинно случайных, QRandomGenerator::system() всё ещё можно использовать (см. раздел ниже).

Если не требуется ни истинный генератор случайных чисел (True RNG), ни криптографически безопасный псевдогенератор (PRNG), приложения должны вместо этого использовать псевдогенераторы случайных чисел (PRNG), такие как детерминированный режим QRandomGenerator и те, что из стандартной библиотеки C++. QRandomGenerator::system() можно использовать для их инициализации.

Качество отката

QRandomGenerator::system() использует средства операционной системы для получения случайных чисел, которые пытаются собрать реальную энтропию из окружающей среды, чтобы произвести истинные случайные числа. Однако возможно, что пул энтропии будет исчерпан, в этом случае операционная система перейдет на псевдослучайный генератор на некоторое время. При любых обстоятельствах QRandomGenerator::system() не будет блокироваться, ожидая сбора дополнительной энтропии.

Следующие операционные системы гарантируют, что результаты из их API генерации случайных чисел будут по крайней мере криптографически безопасного качества, даже если пул энтропии исчерпан: Apple OSes (Darwin), BSD, Linux, Windows. За исключением проблем с установкой системы (например, /dev/urandom недоступен для текущего процесса), QRandomGenerator::system() будет иметь те же гарантии.

На других операционных системах QRandomGenerator перейдет к псевдогенератору (PRNG) с хорошим числовым распределением, но он не может гарантировать надлежащую инициализацию во всех случаях. Для получения дополнительной информации см. документацию ОС.

Приложениям, которым требуется, чтобы QRandomGenerator не переходил к генераторам, не обладающим криптографическим качеством, рекомендуется проверить документацию своей операционной системы или ограничить развертывание одной из перечисленных выше.

Реентерабельность и безопасность потоков

QRandomGenerator является реентерабельным, что означает, что несколько потоков могут одновременно работать с этим классом, если они работают с различными объектами. Если нескольким потокам нужно использовать одну последовательность PRNG, требуется внешняя блокировка с помощью мьютекса.

Исключение составляют объекты, возвращаемые QRandomGenerator::global() и QRandomGenerator::system(): эти объекты потокобезопасны и могут использоваться любым потоком без внешней блокировки. Обратите внимание, что потоковая безопасность не распространяется на копирование этих объектов: их всегда следует использовать по ссылке.

Совместимость со стандартной библиотекой C++

QRandomGenerator моделируется по требованиям к генераторам случайных чисел в стандартной библиотеке C++ и может использоваться практически во всех контекстах, в которых могут использоваться генераторы стандартной библиотеки. Исключением из требований являются следующие:

• QRandomGenerator не поддерживает инициализацию из других объектов последовательности семян (seed sequence) помимо самого std::seed_seq;
• QRandomGenerator не сравниваем (но копируемый) или не потоковый для std::ostream или от std::istream.

QRandomGenerator также совместим с классами равномерного распределения std::uniform_int_distribution и std:uniform_real_distribution, а также с свободной функцией std::generate_canonical. Например, следующий код может использоваться для генерации числа с плавающей запятой в диапазоне [1, 2.5):

    std::uniform_real_distribution dist(1, 2.5);
    return dist(*QRandomGenerator::global());

См. также QRandomGenerator64.

Документация по типам членов

QRandomGenerator::result_type

Псевдоним типа, возвращаемого operator(). То есть, quint32.

См. также operator().

Документация по функциям-членам

Это перегруженная функция.

Эта функция существует для помощи в разрешении перегрузки, когда типы параметров не совсем совпадают. Они будут продвигать меньший тип к типу большего и вызывать правильную перегрузку.

QRandomGenerator::QRandomGenerator(const QRandomGenerator &other)

Создаёт копию состояния генератора в объекте other. Если other — это QRandomGenerator::system() или его копия, этот объект также будет считывать данные из средств генерации случайных чисел операционной системы. В этом случае последовательности, генерируемые двумя объектами, будут разными.

Во всех остальных случаях новый объект QRandomGenerator начнет с той же позиции в детерминированной последовательности, что и объект other. Оба объекта будут генерировать одинаковую последовательность с этого момента.

По этой причине не рекомендуется создавать копию QRandomGenerator::global(). Если требуется эксклюзивный детерминированный генератор, рассмотрите вместо этого использование securelySeeded() для получения нового объекта, не связанного с QRandomGenerator::global().

QRandomGenerator::QRandomGenerator(const quint32 *begin, const quint32 *end)

Это перегруженная функция.

Инициализирует этот объект QRandomGenerator значениями, найденными в диапазоне от begin до end, как семенами. Два объекта, созданных или переинициализированных с одинаковым значением семени, будут генерировать одинаковую последовательность чисел.

Этот конструктор эквивалентен:

    std::seed_seq sseq(begin, end);
    QRandomGenerator generator(sseq);

См. также seed() и securelySeeded().

QRandomGenerator::QRandomGenerator(std::seed_seq &sseq)

Это перегруженная функция.

Инициализирует этот объект QRandomGenerator последовательностью семян sseq в качестве семян. Два объекта, созданных или переинициализированных с одинаковым значением семени, будут генерировать одинаковую последовательность чисел.

См. также seed() и securelySeeded().

QRandomGenerator::QRandomGenerator(const quint32 *seedBuffer, qsizetype len)

Это перегруженная функция.

Инициализирует этот объект QRandomGenerator значениями, найденными в массиве seedBuffer, как семенами. Два объекта, созданных или переинициализированных с одинаковым значением семени, будут генерировать одинаковую последовательность чисел.

Этот конструктор эквивалентен:

    std::seed_seq sseq(seedBuffer, seedBuffer + len);
    QRandomGenerator generator(sseq);

См. также seed() и securelySeeded().

template <qsizetype N> QRandomGenerator::QRandomGenerator(const quint32 (&)[N] seedBuffer = N)

Это перегруженная функция.

Инициализирует этот объект QRandomGenerator значениями, найденными в массиве seedBuffer, как семенами. Два объекта, созданных или переинициализированных с одинаковым значением семени, будут генерировать одинаковую последовательность чисел.

См. также seed() и securelySeeded().

QRandomGenerator::QRandomGenerator(quint32 seedValue = 1)

Инициализирует этот объект QRandomGenerator значением seedValue в качестве начального значения. Два объекта, созданные или переинициализированные с одинаковым значением seed, будут генерировать одинаковую последовательность чисел.

См. также seed() и securelySeeded().

double QRandomGenerator::bounded(double highest)

Генерирует одно случайное значение типа double в диапазоне от 0 (включительно) до highest (исключительно). Эта функция эквивалентна и реализована как:

    return generateDouble() * highest;

Если параметр highest отрицательный, результат также будет отрицательным; если он бесконечен или NaN, результат также будет бесконечным или NaN (то есть не случайным).

См. также generateDouble() и bounded().

quint32 QRandomGenerator::bounded(quint32 highest)

Это перегруженная функция.

Генерирует одно случайное 32-битное целое число в диапазоне от 0 (включительно) до highest (исключительно). Тот же результат можно получить, используя std::uniform_int_distribution с параметрами 0 и highest - 1. Этот класс также может быть использован для получения значений больше 32 бит; для 64 бит можно использовать перегрузку bounded() для 64 бит.

Например, чтобы получить значение от 0 до 255 (включительно), можно написать:

    quint32 v = QRandomGenerator::global()->bounded(256);

Естественно, то же самое можно получить, используя маску результата generate() только на 8 младших битов. Любое из решений будет одинаково эффективным.

Обратите внимание, что эта функция не может быть использована для получения значений во всем 32-битном диапазоне quint32. Вместо этого используйте generate().

См. также generate(), generate64(), и generateDouble().

quint32 QRandomGenerator::bounded(quint32 lowest, quint32 highest)

Это перегруженная функция.

Генерирует одно случайное 32-битное целое число в диапазоне от lowest (включительно) до highest (исключительно). Параметр highest должен быть больше lowest.

Тот же результат можно получить, используя std::uniform_int_distribution с параметрами lowest и \a highest - 1. Этот класс также может быть использован для получения значений больше 32 бит.

Например, чтобы получить значение от 1000 (включительно) до 2000 (исключительно), можно написать:

    quint32 v = QRandomGenerator::global()->bounded(1000, 2000);

Обратите внимание, что эта функция не может быть использована для получения значений во всем 32-битном диапазоне quint32. Вместо этого используйте generate().

См. также generate(), generate64(), и generateDouble().

int QRandomGenerator::bounded(int highest)

Это перегруженная функция.

Генерирует одно случайное 32-битное целое число в диапазоне от 0 (включительно) до highest (исключительно). highest должно быть положительным.

Обратите внимание, что эта функция не может быть использована для получения значений во всем 32-битном диапазоне int. Вместо этого используйте generate() и приведение к типу int.

См. также generate(), generate64(), и generateDouble().

int QRandomGenerator::bounded(int lowest, int highest)

Это перегруженная функция.

Генерирует одно случайное 32-битное целое число в диапазоне от lowest (включительно) до highest (исключительно), оба из которых могут быть отрицательными, но highest должно быть больше lowest.

Обратите внимание, что эта функция не может быть использована для получения значений во всем 32-битном диапазоне int. Вместо этого используйте generate() и приведение к типу int.

См. также generate(), generate64(), и generateDouble().

quint64 QRandomGenerator::bounded(quint64 highest)

Это перегруженная функция.

Генерирует одно случайное 64-битное целое число в диапазоне от 0 (включительно) до highest (исключительно). Тот же результат можно получить, используя std::uniform_int_distribution<quint64> с параметрами 0 и highest - 1.

Обратите внимание, что эта функция не может быть использована для получения значений во всем 64-битном диапазоне quint64. Вместо этого используйте generate64().

Примечание: Эта функция реализована в виде цикла, который зависит от полученного случайного значения. В долгосрочной перспективе в среднем она должна выполняться чуть меньше 2 раз, но если генератор случайных чисел неисправен, эта функция может выполняться значительно дольше.

См. также generate(), generate64(), и generateDouble().

quint64 QRandomGenerator::bounded(quint64 lowest, quint64 highest)

Это перегруженная функция.

Генерирует одно случайное 64-битное целое число в диапазоне от lowest (включительно) до highest (исключительно). Параметр highest должен быть больше lowest.

Тот же результат можно получить, используя std::uniform_int_distribution<quint64> с параметрами lowest и \a highest - 1.

Обратите внимание, что эта функция не может быть использована для получения значений во всем 64-битном диапазоне quint64. Вместо этого используйте generate64().

Примечание: Эта функция реализована в виде цикла, который зависит от полученного случайного значения. В долгосрочной перспективе в среднем она должна выполняться чуть меньше 2 раз, но если генератор случайных чисел неисправен, эта функция может выполняться значительно дольше.

См. также generate(), generate64(), и generateDouble().

qint64 QRandomGenerator::bounded(qint64 highest)

Это перегруженная функция.

Генерирует одно случайное 64-битное целое число в диапазоне от 0 (включительно) до highest (исключительно). highest должно быть положительным.

Обратите внимание, что эта функция не может быть использована для получения значений во всем 64-битном диапазоне qint64. Вместо этого используйте generate64() и приведение к типу qint64 или используйте беззнаковую версию этой функции.

Примечание: Эта функция реализована в виде цикла, который зависит от полученного случайного значения. В долгосрочной перспективе в среднем она должна выполняться чуть меньше 2 раз, но если генератор случайных чисел неисправен, эта функция может выполняться значительно дольше.

См. также generate(), generate64(), и generateDouble().

qint64 QRandomGenerator::bounded(qint64 lowest, qint64 highest)

Это перегруженная функция.

Генерирует одно случайное 64-битное целое число в диапазоне от lowest (включительно) до highest (исключительно), оба из которых могут быть отрицательными, но highest должно быть больше lowest.

Обратите внимание, что эта функция не может быть использована для получения значений во всем 64-битном диапазоне qint64. Вместо этого используйте generate64() и приведение к типу qint64.

Примечание: Эта функция реализована в виде цикла, который зависит от полученного случайного значения. В долгосрочной перспективе в среднем она должна выполняться чуть меньше 2 раз, но если генератор случайных чисел неисправен, эта функция может выполняться значительно дольше.

См. также generate(), generate64(), и generateDouble().

void QRandomGenerator::discard(unsigned long long z)

Отбрасывает следующие z элементов из последовательности. Этот метод эквивалентен вызову generate() z раз и отбрасыванию результата, как в:

    while (z--)
        generator.generate();

template <typename UInt, IfValidUInt<UInt>> void QRandomGenerator::fillRange(UInt *buffer, qsizetype count)

Генерирует count 32- или 64-битных значений (в зависимости от типа UInt) и сохраняет их в буфере, на который указывает buffer. Это самый эффективный способ получения более одного значения за раз, так как это уменьшает количество вызовов источника генератора случайных чисел.

Например, чтобы заполнить список из 16 элементов случайными значениями, можно написать:

    QList<quint32> list;
    list.resize(16);
    QRandomGenerator::global()->fillRange(list.data(), list.size());

См. также generate().

template <typename UInt, size_t N, IfValidUInt<UInt>> void QRandomGenerator::fillRange(UInt (&)[N] buffer = N)

Генерирует N 32- или 64-битные значения (в зависимости от типа UInt) и сохраняет их в массиве buffer. Это наиболее эффективный способ получения более одного значения за раз, так как уменьшает количество вызовов источника генератора случайных чисел.

Например, чтобы сгенерировать два 32-битных значения, можно написать:

    quint32 array[2];
    QRandomGenerator::global()->fillRange(array);

Также можно было бы сделать один вызов generate64() и затем разделить две половины 64-битного значения.

См. также generate().

quint64 QRandomGenerator::generate64()

Генерирует 64-битное случайное значение и возвращает его.

См. также operator()() и generate().

quint32 QRandomGenerator::generate()

Генерирует 32-битное случайное значение и возвращает его.

См. также operator()() и generate64().

template <typename ForwardIterator> void QRandomGenerator::generate(ForwardIterator begin, ForwardIterator end)

Генерирует 32-битные значения и сохраняет их в диапазоне между begin и end. Эта функция эквивалентна (и реализуется как):

    std::generate(begin, end, [this]() { return generate(); });

Эта функция соответствует требованиям функции std::seed_seq::generate, которая требует значений беззнаковых 32-битных целых чисел.

Обратите внимание, что если диапазон [begin, end) относится к области, которая может хранить более 32 бит на элемент, элементы все равно будут инициализированы только 32 битами данных. Любые другие биты будут нулевыми. Чтобы заполнить диапазон 64-битными значениями, можно написать:

    std::generate(begin, end, []() { return QRandomGenerator::global()->generate64(); });

Если диапазон относится к непрерывной памяти (например, массив или данные из QList), функция fillRange() также может быть использована.

См. также fillRange().

double QRandomGenerator::generateDouble()

Генерирует одно случайное значение типа qreal в каноническом диапазоне [0, 1) (т. е., включая ноль и не включая 1).

Эта функция эквивалентна:

    QRandomGenerator64 rd;
    return std::generate_canonical<qreal, std::numeric_limits<qreal>::digits>(rd);

То же самое можно получить, используя std::uniform_real_distribution с параметрами 0 и 1.

См. также generate(), generate64() и bounded().

[static] QRandomGenerator *QRandomGenerator::global()

Возвращает указатель на общий QRandomGenerator, который был инициализирован с помощью securelySeeded(). Эта функция должна использоваться для создания случайных данных без дорогостоящего создания QRandomGenerator с защищенной инициализацией для конкретного использования или хранения довольно большого объекта QRandomGenerator.

Например, следующее создает случайный цвет RGB:

    return QColor::fromRgb(QRandomGenerator::global()->generate());

Доступ к этому объекту потокобезопасен, поэтому его можно использовать в любом потоке без блокировок. Объект также можно копировать, и последовательность, производимая копией, будет такой же, как у общего объекта. Однако имейте в виду, что если другие потоки обращаются к глобальному объекту, эти потоки могут получать выборки в непредсказуемые моменты.

Примечание: Эта функция потокобезопасна.

См. также securelySeeded() и system().

[static] QRandomGenerator::result_type QRandomGenerator::max()

Возвращает максимальное значение, которое может сгенерировать QRandomGenerator. То есть std::numeric_limits<result_type>::max().

См. также min() и QRandomGenerator64::max().

[static] QRandomGenerator::result_type QRandomGenerator::min()

Возвращает минимальное значение, которое может сгенерировать QRandomGenerator. То есть 0.

См. также max() и QRandomGenerator64::min().

[static] QRandomGenerator QRandomGenerator::securelySeeded()

Возвращает новый объект QRandomGenerator, который был защищенно инициализирован с помощью QRandomGenerator::system(). Эта функция получит идеальный размер seed для алгоритма, который использует QRandomGenerator, и поэтому является рекомендуемым способом создания нового объекта QRandomGenerator, который будет храниться некоторое время.

Учитывая количество данных, необходимое для защищенной инициализации детерминированного генератора, эта функция несколько затратна и не должна использоваться для краткосрочных применений QRandomGenerator (использовать ее для генерации менее 2600 байтов случайных данных фактически является пустой тратой ресурсов). Если применение не требует такого количества данных, рассмотрите использование QRandomGenerator::global() и не храните объект QRandomGenerator вместо этого.

См. также global() и system().

void QRandomGenerator::seed(quint32 seed = 1)

Переинициализирует этот объект, используя значение seed в качестве начального значения.

void QRandomGenerator::seed(std::seed_seq &seed)

Это перегруженная функция.

Переинициализирует этот объект, используя последовательность начальных значений seed как начальное значение.

[static] QRandomGenerator *QRandomGenerator::system()

Возвращает указатель на общий QRandomGenerator, который всегда использует возможности операционной системы для генерации случайных чисел. Для следующих операционных систем возможности системы считаются криптографически безопасными: Apple OSes (Darwin), BSDs, Linux, Windows. Это также может быть справедливо и для других операционных систем.

Они также, возможно, поддерживаются истинным генератором случайных чисел аппаратного обеспечения. По этой причине QRandomGenerator, возвращаемый этой функцией, не должен использоваться для генерации больших объемов данных. Вместо этого используйте его для инициализации QRandomGenerator или генератора случайных чисел из заголовка <random>.

Объект, возвращаемый этой функцией, потокобезопасен и может использоваться в любом потоке без блокировок. Он также может быть скопирован, и полученный QRandomGenerator также будет обращаться к возможностям операционной системы, но не будет генерировать ту же последовательность.

Примечание: Эта функция потокобезопасна.

См. также securelySeeded() и global().

QRandomGenerator::result_type QRandomGenerator::operator()()

Генерирует 32-битное случайное значение и возвращает его.

См. также generate() и generate64().