Класс QRandomGenerator

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

Этот класс был введён в Qt 5.10.

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

Примечание: Все функции в этом классе являются перевключенными (реентерабельными).

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

• 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 OS (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 и qrand().

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

typedef 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 (len значений), как начальное значение. Два объекта, созданные или переинициализированные с тем же начальным значением, будут генерировать одну и ту же последовательность чисел.

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

    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() и securelySeeded().

double QRandomGenerator::bounded(double highest)

Генерирует одно случайное вещественное число в диапазоне от 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 бит.

Например, для получения значения от 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().

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 элементов случайными значениями, можно написать:

    QVector<quint32> vector;
    vector.resize(16);
    QRandomGenerator::global()->fillRange(vector.data(), vector.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(); });

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

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

double QRandomGenerator::generateDouble()

Генерирует одно случайное значение типа qreal в каноническом диапазоне [0, 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(). Эта функция получит оптимальный размер для алгоритма, используемого 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), BSD, Linux, Windows. Это также может быть справедливо и для других операционных систем.

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

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

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

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

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

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

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