1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \example network/threadedfortuneserver

    44     \title Threaded Fortune Server Example

    45 

    46     The Threaded Fortune Server example shows how to create a server for a

    47     simple network service that uses threads to handle requests from different

    48     clients. It is intended to be run alongside the Fortune Client example.

    49 

    50     \image threadedfortuneserver-example.png

    51 

    52     The implementation of this example is similar to that of the

    53     \l{network/fortuneserver}{Fortune Server} example, but here we will

    54     implement a subclass of QTcpServer that starts each connection in a

    55     different thread.

    56 

    57     For this we need two classes: FortuneServer, a QTcpServer subclass, and

    58     FortuneThread, which inherits QThread.

    59 

    60     \snippet examples/network/threadedfortuneserver/fortuneserver.h 0

    61 

    62     FortuneServer inherits QTcpServer and reimplements

    63     QTcpServer::incomingConnection(). We also use it for storing the list of

    64     random fortunes. 

    65     

    66     \snippet examples/network/threadedfortuneserver/fortuneserver.cpp 0

    67 

    68     We use FortuneServer's constructor to simply generate the list of

    69     fortunes.

    70 

    71     \snippet examples/network/threadedfortuneserver/fortuneserver.cpp 1

    72 

    73     Our implementation of QTcpServer::incomingConnection() creates a

    74     FortuneThread object, passing the incoming socket descriptor and a random

    75     fortune to FortuneThread's constructor. By connecting FortuneThread's

    76     finished() signal to QObject::deleteLater(), we ensure that the thread

    77     gets deleted once it has finished. We can then call QThread::start(),

    78     which starts the thread.

    79 

    80     \snippet examples/network/threadedfortuneserver/fortunethread.h 0

    81 

    82     Moving on to the FortuneThread class, this is a QThread subclass whose job

    83     is to write the fortune to the connected socket. The class reimplements

    84     QThread::run(), and it has a signal for reporting errors.

    85 

    86     \snippet examples/network/threadedfortuneserver/fortunethread.cpp 0

    87     

    88     FortuneThread's constructor simply stores the socket descriptor and

    89     fortune text, so that they are available for run() later on.

    90 

    91     \snippet examples/network/threadedfortuneserver/fortunethread.cpp 1

    92 

    93     The first thing our run() function does is to create a QTcpSocket object

    94     on the stack. What's worth noticing is that we are creating this object

    95     inside the thread, which automatically associates the socket to the

    96     thread's event loop. This ensures that Qt will not try to deliver events

    97     to our socket from the main thread while we are accessing it from

    98     FortuneThread::run().

    99 

   100     \snippet examples/network/threadedfortuneserver/fortunethread.cpp 2

   101 

   102     The socket is initialized by calling QTcpSocket::setSocketDescriptor(),

   103     passing our socket descriptor as an argument. We expect this to succeed,

   104     but just to be sure, (although unlikely, the system may run out of

   105     resources,) we catch the return value and report any error.

   106 

   107     \snippet examples/network/threadedfortuneserver/fortunethread.cpp 3

   108 

   109     As with the \l{network/fortuneserver}{Fortune Server} example, we encode

   110     the fortune into a QByteArray using QDataStream.

   111 

   112     \snippet examples/network/threadedfortuneserver/fortunethread.cpp 4

   113 

   114     But unlike the previous example, we finish off by calling

   115     QTcpSocket::waitForDisconnected(), which blocks the calling thread until

   116     the socket has disconnected. Because we are running in a separate thread,

   117     the GUI will remain responsive.  

   118 

   119     \sa {Fortune Server Example}, {Fortune Client Example}, {Blocking Fortune

   120     Client Example}

   121 */