Поддержка потоков

Команды поддержки потоков предназначены для указания уровня поддержки многопоточного программирования в классе или функции. Существует три уровня поддержки: threadsafe, reentrant и nonreentrant.

По умолчанию установлено значение nonreentrant, что означает, что связанный класс или функция не могут вызываться из нескольких потоков. Reentrant и threadsafe — уровни, используемые в основном для классов.

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

Когда класс помечен как \reentrant или \threadsafe, функции в этом классе могут быть помечены как nonreentrant с помощью команды \nonreentrant.

Пример

\beginqdoc
    \class QLocale
    \brief The QLocale class converts between numbers and their
    string representations in various languages.

    \reentrant
    \ingroup i18n
    \ingroup text

    QLocale is initialized with a language/country pair in its
    constructor and offers number-to-string and string-to-number
    conversion functions similar to those in QString.

    ...

    \nonreentrant

    Sets the global default locale to \a locale. These values are
    used when a QLocale object is constructed with no
    arguments. If this function is not called, the system's locale
    is used.

    \warning In a multithreaded application, the default locale
    should be set at application startup, before any non-GUI
    threads are created.

    \sa system(), c()
\endqdoc
void QLocale::setDefault(const QLocale &locale)
{
    default_d = locale.d;
}

QDoc отображает это как:

Класс QLocale

Класс QLocale выполняет преобразование между числами и их строковыми представлениями на различных языках. Подробнее...

#include <QLocale>

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

...

---

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

...

void QLocale::setDefault ( const QLocale & locale )

Устанавливает глобальную локаль по умолчанию на locale. Эти значения используются при создании объекта QLocale без аргументов. Если эта функция не вызывается, используется локаль системы.

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

Предупреждение: Эта функция не является рекурсивной.

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

...

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

QDoc сгенерирует то же самое уведомление и предупреждения, когда класс объявлен безопасным для потоков.

Дополнительную информацию см. в общей документации по рекурсивности и безопасности потоков.

Команды

\threadsafe

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

Команда должна находиться на отдельной строке.

Документация, сгенерированная с помощью этой команды, будет аналогична документации, сгенерированной для команды \reentrant. См. пример выше в введении.

См. также \reentrant и \nonreentrant.

\reentrant

Команда \reentrant указывает, что связанный класс или функция могут вызываться одновременно из нескольких потоков, при условии, что каждый вызов ссылается на свои собственные данные. См. пример выше.

Команда должна находиться на отдельной строке.

См. также \nonreentrant и \threadsafe.

\nonreentrant

Команда \nonreentrant указывает, что связанный класс или функция не могут вызываться из нескольких потоков. Нерекурсивный режим — это значение по умолчанию.

Команда должна находиться на отдельной строке.

Когда класс помечен как \reentrant или \threadsafe, функции в этом классе могут быть помечены nonreentrant с помощью этой команды в комментарии \fn функций, которые нужно исключить.

См. также \reentrant и \threadsafe.