From d24a6483d0fcebc65d4f44d0f7bf908214f7b49b Mon Sep 17 00:00:00 2001 From: Tatiana Borisova Date: Wed, 7 Oct 2026 12:10:14 +0200 Subject: [PATCH] Document blocking I/O and threading considerations - Document that disconnectFromHost() may block while waiting for pending data to be written, with a timeout of up to 30 seconds. - Recommend keeping QMqttClient and its transport outside the UI thread because blocking I/O may occur and affect UI responsiveness. Pick-to: 6.12 Task-number: QTBUG-150345 Change-Id: I27d300210750710c4a5138f8c3f97c7c929466af Reviewed-by: Ivan Solovev --- src/mqtt/doc/src/overview.qdoc | 14 ++++++++++++++ src/mqtt/qmqttclient.cpp | 5 +++++ 2 files changed, 19 insertions(+) diff --git a/src/mqtt/doc/src/overview.qdoc b/src/mqtt/doc/src/overview.qdoc index 3180f74..b1e9f15 100644 --- a/src/mqtt/doc/src/overview.qdoc +++ b/src/mqtt/doc/src/overview.qdoc @@ -179,4 +179,18 @@ discarded. The broker \e{should} store the last message, but \e{may} also discard it. This depends on the implementation of the broker. + \section1 Threading and Blocking Operations + + Consider running \l QMqttClient and its related classes in a thread + separate from the UI thread.\l QMqttClient uses a \l QIODevice as + its transport, and some transport operations may block. For example, + QMqttClient::disconnectFromHost() may wait synchronously for pending + data to be written, with a timeout of up to 30 seconds. Calling it from + the UI thread can therefore block the UI event loop and make the + application unresponsive. Keeping the MQTT client and its transport in + a dedicated thread helps prevent potentially blocking I/O from affecting + UI responsiveness. Use signals and slots or other mechanisms that queue + work to the target thread to communicate between the MQTT thread and + the UI thread. + */ diff --git a/src/mqtt/qmqttclient.cpp b/src/mqtt/qmqttclient.cpp index 9ec2b0a..2fc87ee 100644 --- a/src/mqtt/qmqttclient.cpp +++ b/src/mqtt/qmqttclient.cpp @@ -637,6 +637,11 @@ void QMqttClient::connectToHost(bool encrypted, const QString &sslPeerName) /*! Disconnects from the MQTT broker. + + \note This function may block while waiting for pending data + to be written to the transport. + See \l {Threading and Blocking Operations} for recommended approaches + on handling it. */ void QMqttClient::disconnectFromHost() {