1 files changed, 164 insertions, 0 deletions
diff --git a/examples/serialport/doc/blockingslave.qdoc b/examples/serialport/doc/blockingslave.qdoc
new file mode 100644
index 00000000..4b835d98
--- /dev/null
+++ b/examples/serialport/doc/blockingslave.qdoc
@@ -0,0 +1,164 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 - 2012 Denis Shienkov <denis.shienkov@gmail.com>
+** Contact: http://www.qt-project.org/legal
+**
+** 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 Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example blockingslave
+    \title Blocking Slave Example
+    \ingroup qtserialport-examples
+
+    The Blocking Slave example shows how to create a application for a
+    serial interface using QSerialPort's synchronous API in a non-GUI thread.
+
+    \image blockingslave-example.png Screenshot of the Blocking Slave example
+
+    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{QSerialPort::bytesWritten()}{bytesWritten()}.
+
+    \li \e{The synchronous (blocking) approach.} In non-GUI and multithreaded
+    applications, the \c waitFor...() functions can be called (i.e.
+    QSerialPort::waitReadyRead()) to suspend the calling thread until the
+    operation has completed.
+
+    \endlist
+
+    In this example, the synchronous approach is demonstrated. The
+    \l{slave}{Slave Example} 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 unmanagable complexity to your application.
+
+    This application is a Slave, that demonstrate the work paired with Master
+    application \l{blockingmaster}{Blocking Master Example}.
+
+    The Slave application is receives the request via serial port from
+    the Master application and send a response to it.
+
+    We will start with the SlaveThread class, which handles the serial
+    programming code.
+
+    \snippet blockingslave/slavethread.h 0
+
+    SlaveThread is a QThread subclass that provides an API for receive requests
+    from Master, and it has signals for delivering responses and reporting
+    errors.
+
+    You should be call startSlave() to startup Slave application. This method
+    transfers to the SlaveThread desired parameters for configure and startup
+    the serial interface. When SlaveThread received from Master any request then
+    emitted the request() signal. If any error occurs, the error() or timeout()
+    signals is emitted.
+
+    It's important to notice that startSlave() is called from the main, GUI
+    thread, but the response data and other parameters will be accessed from
+    SlaveThread's thread. Because we will be reading and writing SlaveThread's
+    data members from different threads concurrently, we use QMutex to
+    synchronize access.
+
+    \snippet blockingslave/slavethread.cpp 2
+
+    The startSlave() function stores the serial port name, timeout and response
+    data, and we lock the mutex with QMutexLocker to protect this data. We then
+    start the thread, unless it is already running. We will come back to the
+    QWaitCondition::wakeOne() call later.
+
+    \snippet blockingslave/slavethread.cpp 4
+    \snippet blockingslave/slavethread.cpp 5
+
+    In the run() function, we start by acquiring the mutex lock, fetching the
+    serial port name, timeout and response data from the member data, and then
+    releasing the lock again. The case that we are protecting ourselves against
+    is that \c startSlave() could be called at the same time as we are fetching
+    this data. QString is \l reentrant but \e not \l{thread-safe}, and we must
+    also avoid the unlikely risk of reading the serial port name from one startup,
+    call and timeout or response data of another. And as you might have guessed,
+    SlaveThread can only handle one startup at a time.
+
+    The QSerialPort object we construct on stack into run() function before loop
+    enter:
+
+    \snippet blockingslave/slavethread.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, we check for changed or not the name of serial port for the
+    current startup. And if the name is changed then re-open and re-configure
+    the serial port.
+
+    \snippet blockingslave/slavethread.cpp 7
+
+    The loop will continue wait for reading request data:
+
+    \snippet blockingslave/slavethread.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 error occurs when reading data.
+
+    \snippet blockingslave/slavethread.cpp 9
+
+    After a successful read, we try send response and wait completion of the
+    transfer:
+
+    \snippet blockingslave/slavethread.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 error occurs when writing data.
+
+    \snippet blockingslave/slavethread.cpp 11
+
+    After a successful writing is emitted request() signal containing the
+    data received from the Master application:
+
+    \snippet blockingslave/slavethread.cpp 12
+
+    Next, the thread goes to re-reads the current parameters for serial interface,
+    because they can be updated when new startSlave() and run loop from the
+    beginning.
+
+    \snippet blockingslave/slavethread.cpp 13
+
+    \sa {Simple Terminal Example}, {Blocking Master Example}
+*/