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

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

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

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

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

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

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

qint64 QRandomGenerator::bounded(qint64 highest)

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

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

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

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

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

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

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

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

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

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

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

void QRandomGenerator::seed(quint32 seed = 1)

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

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

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

Переинициализирует этот объект, используя последовательность 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().