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

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

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

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

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

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

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

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

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

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

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

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

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

• QRandomGenerator не поддерживает инициализацию из другого класса последовательности семян, кроме 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, как семян. Два объекта, созданные или переинициализированные с одним и тем же значением семян, будут генерировать одну и ту же последовательность чисел.

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

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

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

QRandomGenerator::QRandomGenerator(const quint32 (&)[N] seedBuffer = ...)

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

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

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

QRandomGenerator::QRandomGenerator(quint32 seedValue = 1)

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

См. также 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 бита.

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

    quint32 v = QRandomGenerator::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::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();

void QRandomGenerator::fillRange(UInt *buffer, qsizetype count)

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

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

    QVector<quint32> vector;
    vector.resize(16);
    QRandomGenerator::fillRange(vector.data(), vector.size());

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

void QRandomGenerator::fillRange(UInt (&)[N] buffer = ...)

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

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

    quint32 array[2];
    QRandomGenerator::fillRange(array);

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

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

quint64 QRandomGenerator::generate64()

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

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

quint32 QRandomGenerator::generate()

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

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

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 OS (Darwin), BSD, Linux, Windows. Это также может быть верно и для других операционных систем.

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

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

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

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

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

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

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