summaryrefslogtreecommitdiff
path: root/examples/serialport/doc/blockingreceiver.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'examples/serialport/doc/blockingreceiver.qdoc')
-rw-r--r--examples/serialport/doc/blockingreceiver.qdoc167
1 files changed, 167 insertions, 0 deletions
diff --git a/examples/serialport/doc/blockingreceiver.qdoc b/examples/serialport/doc/blockingreceiver.qdoc
new file mode 100644
index 0000000..555b2db
--- /dev/null
+++ b/examples/serialport/doc/blockingreceiver.qdoc
@@ -0,0 +1,167 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 - 2012 Denis Shienkov <denis.shienkov@gmail.com>
+** Copyright (C) 2016 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \example blockingreceiver
+ \title Blocking Receiver Example
+ \ingroup qtserialport-examples
+ \brief Shows how to use the synchronous API of QSerialPort in a non-GUI thread.
+
+ \e{Blocking Receiver} shows how to create an application for a serial interface
+ using QSerialPort's synchronous API in a non-GUI thread.
+
+ \image blockingreceiver-example.png
+
+ QSerialPort supports two general programming approaches:
+
+ \list
+
+ \li \e{The asynchronous (non-blocking) approach.} Operations are scheduled
+ and performed when the control returns to Qt's event loop. QSerialPort emits
+ a signal when the operation is finished. For example, QSerialPort::write()
+ returns immediately. When the data is sent to the serial port, QSerialPort
+ emits \l{QIODevice::bytesWritten()}{bytesWritten()}.
+
+ \li \e{The synchronous (blocking) approach.} In non-GUI and multithreaded
+ applications, the \c waitFor...() functions can be called (i.e.
+ QSerialPort::waitForReadyRead()) to suspend the calling thread until the
+ operation has completed.
+
+ \endlist
+
+ In this example, the synchronous approach is demonstrated. The
+ \l{terminal}{Terminal} example illustrates the
+ asynchronous approach.
+
+ The purpose of this example is to demonstrate a pattern that you can use
+ to simplify your serial programming code, without losing responsiveness
+ in your user interface. Use of Qt's blocking serial programming API often
+ leads to simpler code, but because of its blocking behavior, it should only
+ be used in non-GUI threads to prevent the user interface from freezing.
+ But contrary to what many think, using threads with QThread does not
+ necessarily add unmanageable complexity to your application.
+
+ This application is a Receiver, that demonstrate the work paired with Sender
+ application \l{Blocking Sender Example}.
+
+ The Receiver application receives the request via serial port from
+ the Sender application and send a response to it.
+
+ We will start with the ReceiverThread class, which handles the serial
+ programming code.
+
+ \snippet blockingreceiver/receiverthread.h 0
+
+ ReceiverThread is a QThread subclass that provides an API for receive requests
+ from Sender, and it has signals for delivering responses and reporting
+ errors.
+
+ You should call startReceiver() to startup Receiver application. This method
+ transfers to the ReceiverThread desired parameters for configure and startup
+ the serial interface. When ReceiverThread received from Sender any request then
+ emitted the request() signal. If any error occurs, the error() or timeout()
+ signals is emitted.
+
+ It's important to notice that startReceiver() is called from the main, GUI
+ thread, but the response data and other parameters will be accessed from
+ ReceiverThread's thread. ReceiverThread's data members are read and written
+ from different threads concurrently, so it is advisable to use QMutex to
+ synchronize access.
+
+ \snippet blockingreceiver/receiverthread.cpp 2
+
+ The startReceiver() function stores the serial port name, timeout and response
+ data, and QMutexLocker locks the mutex to protect these data. We then
+ start the thread, unless it is already running. QWaitCondition::wakeOne()
+ will be discussed later.
+
+ \snippet blockingreceiver/receiverthread.cpp 4
+ \snippet blockingreceiver/receiverthread.cpp 5
+
+ In the run() function, start by acquiring the mutex lock, fetch the
+ serial port name, timeout and response data from the member data, and then
+ release the lock again. Under no circumstance should the method \c startReceiver()
+ be called simultaneously with a process fetching these data. QString is reentrant
+ but not thread-safe, and it is not recommended to read the serial port name
+ from one startup, call and timeout or response data of another. ReceiverThread
+ can only handle one startup at a time.
+
+ The QSerialPort object we construct on stack into run() function before loop
+ enter:
+
+ \snippet blockingreceiver/receiverthread.cpp 6
+
+ This allows us once to create an object, while running loop, and also means
+ that all the methods of the object will be executed in the context of the
+ run() thread.
+
+ In the loop, check whether the name of the serial port for the current
+ startup has changed or not. If it has, re-open and reconfigure the serial port.
+
+ \snippet blockingreceiver/receiverthread.cpp 7
+
+ The loop will continue waiting for request data:
+
+ \snippet blockingreceiver/receiverthread.cpp 8
+
+ \warning The method waitForReadyRead() should be used before each read()
+ call for the blocking approach, because it processes all the I/O routines
+ instead of Qt event-loop.
+
+ The timeout() signal is emitted if an error occurs when reading data.
+
+ \snippet blockingreceiver/receiverthread.cpp 9
+
+ After a successful read, try to send a response and wait for completion of the
+ transfer:
+
+ \snippet blockingreceiver/receiverthread.cpp 10
+
+ \warning The method waitForBytesWritten() should be used after each write()
+ call for the blocking approach, because it processes all the I/O routines
+ instead of Qt event-loop.
+
+ The timeout() signal is emitted if an error occurs when writing data.
+
+ \snippet blockingreceiver/receiverthread.cpp 11
+
+ After a successful writing is emitted, request() signal containing the
+ data received from the Sender application:
+
+ \snippet blockingreceiver/receiverthread.cpp 12
+
+ Next, the thread switches to reading the current parameters for the serial
+ interface, because they can already have been updated, and run the loop
+ from the beginning.
+
+ \snippet blockingreceiver/receiverthread.cpp 13
+
+ \sa {Terminal Example}, {Blocking Sender Example}
+
+ \include examples-run.qdocinc
+*/