[Development] Unnecessary ambiguity in Qt documentation about reentrancy and safety of const methods.

Tue Jul 21 19:19:16 CEST 2026

> to state that calling read-only members from multiple threads on the same instance of this class is defined behavior, unless documented otherwise.

To be precise: "unless no other thread is calling mutating method at the same time".

We may have a case that 2 threads call const methods and only 1 is mutating at the same time -> undefined behavior.
This is the crucial part of the explanation IMO.

Jarek

________________________________________
From: Development <development-bounces at qt-project.org> on behalf of Volker Hilsheimer via Development <development at qt-project.org>
Sent: Tuesday, July 21, 2026 3:43 PM
To: NIkolai Marchenko
Cc: development at qt-project.org
Subject: Re: [Development] Unnecessary ambiguity in Qt documentation about reentrancy and safety of const methods.

> On 21 Jul 2026, at 15:00, NIkolai Marchenko <enmarantispam at gmail.com> wrote:
>
> At the very least, and this would probably be simpler, you could start establishing a contract for classes that already work like that and provide extended guarantees at least for them in the current docs so that people can actually rely on them instead of abusing the contract each time(even with mutual unformalized understanding between qt and users that the extended contract holds).

Ideally, we can extend the documentation language that gets generated for the `\reentrant` tag (and/or the general overview documentation on reentrancy) to state that calling read-only members from multiple threads on the same instance of this class is defined behavior, unless documented otherwise. We can’t do that unless we are sure that this is true for all `\reentrant` classes, and have explicitly documented the exception for those cases where it is not.

But perhaps a new `\reentrant_extended` qdoc macro that we introduce gradually as we identify compliant classes might be ok; we’d probably want to add a new `\reentrant_with_exception` macro to tag non-compliant classes.

Either way, unless someone does it, it won’t get done :) If there is a group of people that would like to work on it, then that’s the group of people that will push the change they’d like to see.

Volker

>
> On Tue, Jul 21, 2026 at 3:55 PM Volker Hilsheimer <volker.hilsheimer at qt.io> wrote:
> Thanks Kai.
>
> The task assumes that we agree that we want to extend the contract to match what the C++ standard library has established, at least as of C++11. Our definition of reentrancy [1] pre-dates that by a decade.
>
> [1] https://doc.qt.io/qt-6/threads-reentrancy.html
>
> I would think that the statement that
>
> > You can safely access different instances of QString from multiple threads simultaneously, but you can't safely access the same instance of QString from multiple threads simultaneously (unless you protect the accesses yourself with a QMutex).
>
> makes it pretty clearly that as of today, we do not provide any guarantees that calling any member function on the same instance from multiple threads is defined behavior (unless the respective class is marked as \threadsafe). However, this is evidently at the very least a surprise for users that come with the C++ standard library design choice in mind.
>
> Based on the points made in this thread, Qt matching the C++ standard library guarantee is the right direction and a good ambition to have. There will be exceptions that we can’t or don’t want to fix, in which case documenting them as exceptions is likely the best we can do.
>
> The question is how to get from where we are to where we would like to be, and if this is the kind of thing we want to prioritise. We have perhaps not always paid attention to adding the \threadsafe and \reentrant documentation tags, but more importantly we have probably (happy to be proven wrong) not kept track of classes or individual functions that lazily initialize without any synchronisation in place.
>
> https://qt-project.atlassian.net/browse/QTBUG-95166 is an existing task that calls for a general review, with comments that point out that QObject (not to speak of QWidget and Qt GUI in general) come with additional threading/concurrency aspects to consider.
>
> This seems like an excellent candidate for a Qt Project Goal [2] as something that requires broad community participation, spans several Qt modules, and requires a focused effort over a longer period of time.
>
> [2] https://wiki.qt.io/Category:Goals
>
>
> Volker
>
>
>
>
> > On 20 Jul 2026, at 14:33, Kai Köhne via Development <development at qt-project.org> wrote:
> >
> > Hi,
> >
> > Great discussion! I took the liberty to distill the summary - as I understand it - into a task: https://qt-project.atlassian.net/browse/QTBUG-148455 .
> >
> > Regards
> >
> > Kai
> >
> >
> > Confidential
> > From: Development <development-bounces at qt-project.org> on behalf of Giuseppe D'Angelo via Development <development at qt-project.org>
> > Date: Sunday, 19. July 2026 at 01:07
> > To: NIkolai Marchenko <enmarantispam at gmail.com>
> > Cc: development at qt-project.org <development at qt-project.org>
> > Subject: Re: [Development] Unnecessary ambiguity in Qt documentation about reentrancy and safety of const methods.
> >
> > On 19/07/2026 00:38, NIkolai Marchenko wrote:
> > > I am not exactly sure if your wording covers the
> > > qlocale::toDouble(string,bool&) or not.  aka non const but also
> > > partially not same data.
> >
> >
> > Well, the signature is
> >
> > > double QLocale::toDouble(const QString &s, bool *ok = nullptr) const
> >
> > Therefore, in the extended contract, it's OK to call this function from
> > multiple threads, without synchronization, on the same QLocale object
> > and/or on the same QString object. It's not OK to call it on the same
> > bool object.
> >
> > Without the extended contract, do note that it's formally illegal to
> > call this function on the same QString instance, even if called on
> > different QLocale instances. toDouble() could call something like
> > `s.utf16()` internally, which isn't thread-safe.
> >
> > My 2 c,
> > --
> > Giuseppe D'Angelo | giuseppe.dangelo at kdab.com | Senior Software Engineer
> > KDAB (France) S.A.S., a KDAB Group company
> > Tel. France +33 (0)4 90 84 08 53, http://www.kdab.com/
> > KDAB - Trusted Software Excellence
> > --
> > Development mailing list
> > Development at qt-project.org
> > https://lists.qt-project.org/listinfo/development
>

--
Development mailing list
Development at qt-project.org
https://lists.qt-project.org/listinfo/development