Thread Support | QDoc Manual 5.9

Qt 5.9 | QDoc Manual | Thread Support

Qt 5.9.2 Reference Documentation

Status ◦ Relating Things

# Thread Support

The thread support commands are for specifying the level of support for multithreaded programming in a class or function. There are three levels of support: `threadsafe`, `reentrant` and `nonreentrant`.

The default is `nonreentrant` which means that the associated class or function cannot be called by multiple threads. `Reentrant` and `threadsafe` are levels primarily used for classes.

`Reentrant` means that all the functions in the referenced class can be called simultaneously by multiple threads, provided that each invocation of the functions reference unique data. While `threadsafe` means that all the functions in the referenced class can be called simultaneously by multiple threads even when each invocation references shared data.

When a class is marked \reentrant or \threadsafe, functions in that class can be marked `nonreentrant` using the \nonreentrant command.

## Example

      \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 renders this as:

> #
> QLocale Class Reference

> The QLocale class converts between numbers and their string representations in various languages. More...

>       #include <QLocale>

> Note: All the functions in this class are reentrant, except setDefault().

> ...

> ## Member Type Documentation

> ...

> ### void QLocale::setDefault ( const QLocale & locale )

> Sets the global default locale to 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.

> Warning: This function is not reentrant.

> See also system() and c().

> ...

As shown above, QDoc generates a notification when a class is declared reentrant, and lists the exceptions (the declared nonreentrant functions). A link to the general documentation on reentrancy and thread-safety is included. In addition a warning, "Warning: This function is not reentrant.", is generated in the nonreentrant functions' documentation.

QDoc will generate the same notification and warnings when a class is declared threadsafe.

For more information see the general documentation on reentrancy and thread-safety.

## Commands

### \threadsafe

The \threadsafe command includes a line in the documentation to indicate that the associated class or function is threadsafe and can be called simultaneously by multiple threads, even when separate invocations reference shared data.

The command must stand on its own line.

The documentation generated from this command will be similar to the what is generated for the \reentrant command. See the example above in the introduction.

See also \reentrant and \nonreentrant.

### \reentrant

The \reentrant command indicates that the associated class or function can be called simultaneously by multiple threads, provided that each invocation references its own data. See the example above.

The command must stand on its own line.

See also \nonreentrant and \threadsafe.

### \nonreentrant

The \nonreentrant command indicates that the associated class or function cannot be called by multiple threads. Nonreentrant is the default case.

The command must stand on its own line.

When a class is marked \reentrant or \threadsafe, functions in that class can be marked `nonreentrant` using this command in the \fn comment of the functions to be excluded.

See also \reentrant and \threadsafe.

Status ◦ Relating Things