doc/src/core/threads.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 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:FDL$
  10 ** GNU Free Documentation License
  11 ** Alternatively, this file may be used under the terms of the GNU Free
  12 ** Documentation License version 1.3 as published by the Free Software
  13 ** Foundation and appearing in the file included in the packaging of
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \page thread-basics.html
  30     \ingroup tutorials
  31     \startpage {index.html}{Qt Reference Documentation}
  32
  33     \title Threading Basics
  34     \brief An introduction to threads
  35
  36     \section1 What Are Threads?
  37
  38     Threads are about doing things in parallel, just like processes. So how do
  39     threads differ from processes? While you are making calculations on a
  40     spreadsheet, there may also be a media player running on the same desktop
  41     playing your favorite song. Here is an example of two processes working in
  42     parallel: one running the spreadsheet program; one running a media player.
  43     Multitasking is a well known term for this. A closer look at the media
  44     player reveals that there are again things going on in parallel within one
  45     single process. While the media player is sending music to the audio driver,
  46     the user interface with all its bells and whistles is being constantly
  47     updated. This is what threads are for \mdash concurrency within one single
  48     process.
  49
  50     So how is concurrency implemented? Parallel work on single core CPUs is an
  51     illusion which is somewhat similar to the illusion of moving images in
  52     cinema.
  53     For processes, the illusion is produced by interrupting the processor's
  54     work on one process after a very short time. Then the processor moves on to
  55     the next process. In order to switch between processes, the current program
  56     counter is saved and the next processor's program counter is loaded. This
  57     is not sufficient because the same needs to be done with registers and
  58     certain architecture and OS specific data.
  59
  60     Just as one CPU can power two or more processes, it is also possible to let
  61     the CPU run on two different code segments of one single process. When a
  62     process starts, it always executes one code segment and therefore the
  63     process is said to have one thread. However, the program may decide to
  64     start a second thread. Then, two different code sequences are processed
  65     simultaneously inside one process. Concurrency is achieved on single core
  66     CPUs by repeatedly saving program counters and registers then loading the
  67     next thread's program counters and registers. No cooperation from the
  68     program is required to cycle between the active threads. A thread may be in
  69     any state when the switch to the next thread occurs.
  70
  71     The current trend in CPU design is to have several cores. A typical
  72     single-threaded application can make use of only one core. However, a
  73     program with multiple threads can be assigned to multiple cores, making
  74     things happen in a truly concurrent way. As a result, distributing work
  75     to more than one thread can make a program run much faster on multicore
  76     CPUs because additional cores can be used.
  77
  78     \section2 GUI Thread and Worker Thread
  79
  80     As mentioned, each program has one thread when it is started. This thread
  81     is called the "main thread" (also known as the "GUI thread" in Qt
  82     applications). The Qt GUI must run in this thread. All widgets and several
  83     related classes, for example QPixmap, don't work in secondary threads.
  84     A secondary thread is commonly referred to as a "worker thread" because it
  85     is used to offload processing work from the main thread.
  86
  87     \section2 Simultaneous Access to Data
  88
  89     Each thread has its own stack, which means each thread has its own call
  90     history and local variables. Unlike processes, threads share the same
  91     address space. The following diagram shows how the building blocks of
  92     threads are located in memory. Program counter and registers of inactive
  93     threads are typically kept in kernel space. There is a shared copy of the
  94     code and a separate stack for each thread.
  95
  96     \image threadvisual-example.png "Thread visualization"
  97
  98     If two threads have a pointer to the same object, it is possible that both
  99     threads will access that object at the same time and this can potentially
 100     destroy the object's integrity. It's easy to imagine the many things that
 101     can go wrong when two methods of the same object are executed
 102     simultaneously.
 103
 104     Sometimes it is necessary to access one object from different threads;
 105     for example, when objects living in different threads need to communicate.
 106     Since threads use the same address space, it is easier and faster for
 107     threads to exchange data than it is for processes. Data does not have to be
 108     serialized and copied. Passing pointers is possible, but there must be a
 109     strict coordination of what thread touches which object. Simultaneous
 110     execution of operations on one object must be prevented. There are several
 111     ways of achieving this and some of them are described below.
 112
 113     So what can be done safely? All objects created in a thread can be used
 114     safely within that thread provided that other threads don't have references
 115     to them and objects don't have implicit coupling with other threads. Such
 116     implicit coupling may happen when data is shared between instances as with
 117     static members, singletons or global data. Familiarize yourself with the
 118     concept of \l{Reentrancy and Thread-Safety}{thread safe and reentrant}
 119     classes and functions.
 120
 121     \section1 Using Threads
 122
 123     There are basically two use cases for threads:
 124
 125     \list
 126     \o Make processing faster by making use of multicore processors.
 127     \o Keep the GUI thread or other time critical threads responsive by
 128        offloading long lasting processing or blocking calls to other threads.
 129     \endlist
 130
 131     \section2 When to Use Alternatives to Threads
 132
 133     Developers need to be very careful with threads. It is easy to start other
 134     threads, but very hard to ensure that all shared data remains consistent.
 135     Problems are often hard to find because they may only show up once in a
 136     while or only on specific hardware configurations. Before creating threads
 137     to solve certain problems, possible alternatives should be considered.
 138
 139     \table
 140     \header
 141         \o Alternative
 142         \o Comment
 143     \row
 144         \o QEventLoop::processEvents()
 145         \o Calling QEventLoop::processEvents() repeatedly during a
 146            time-consuming calculation prevents GUI blocking. However, this
 147            solution doesn't scale well because the call to processEvents() may
 148            occur too often, or not often enough, depending on hardware.
 149     \row
 150         \o QTimer
 151         \o Background processing can sometimes be done conveniently using a
 152            timer to schedule execution of a slot at some point in the future.
 153            A timer with an interval of 0 will time out as soon as there are no
 154            more events to process.
 155     \row
 156         \o QSocketNotifier QNetworkAccessManager QIODevice::readyRead()
 157         \o This is an alternative to having one or multiple threads, each with
 158            a blocking read on a slow network connection. As long as the
 159            calculation in response to a chunk of network data can be executed
 160            quickly, this reactive design is better than synchronous waiting in
 161            threads. Reactive design is less error prone and energy efficient
 162            than threading. In many cases there are also performance benefits.
 163     \endtable
 164
 165     In general, it is recommended to only use safe and tested paths and to
 166     avoid introducing ad-hoc threading concepts. QtConcurrent provides an easy
 167     interface for distributing work to all of the processor's cores. The
 168     threading code is completely hidden in the QtConcurrent framework, so you
 169     don't have to take care of the details. However, QtConcurrent can't be used
 170     when communication with the running thread is needed, and it shouldn't be
 171     used to handle blocking operations.
 172
 173     \section2 Which Qt Thread Technology Should You Use?
 174
 175     Sometimes you want to do more than just running a method in the context of
 176     another thread. You may want to have an object which lives in another
 177     thread that provides a service to the GUI thread. Maybe you want another
 178     thread to stay alive forever to poll hardware ports and send a signal to
 179     the GUI thread when something noteworthy has happened. Qt provides
 180     different solutions for developing threaded applications. The right
 181     solution depends on the purpose of the new thread as well as on the
 182     thread's lifetime.
 183
 184     \table
 185     \header
 186         \o Lifetime of thread
 187         \o Development task
 188         \o Solution
 189     \row
 190         \o One call
 191         \o Run one method within another thread and quit the thread when the
 192            method is finished.
 193         \o Qt provides different solutions:
 194            \list
 195               \o Write a function and run it with QtConcurrent::run()
 196               \o Derive a class from QRunnable and run it in the global thread
 197                  pool with QThreadPool::globalInstance()->start()
 198               \o Derive a class from QThread, reimplement the QThread::run()
 199                  method and use QThread::start() to run it.
 200            \endlist
 201
 202     \row
 203         \o One call
 204         \o Operations are to be performed on all items of a container.
 205            Processing should be performed using all available cores. A common
 206            example is to produce thumbnails from a list of images.
 207         \o QtConcurrent provides the \l{QtConcurrent::}{map()} function for
 208            applying operations on every container element,
 209            \l{QtConcurrent::}{filter()} for selecting container elements, and
 210            the option of specifying a reduce function for combining the
 211            remaining elements.
 212     \row
 213         \o One call
 214         \o A long running operation has to be put in another thread. During the
 215            course of processing, status information should be sent to the GUI
 216            thread.
 217         \o Use QThread, reimplement run and emit signals as needed. Connect the
 218            signals to the GUI thread's slots using queued signal/slot
 219            connections.
 220
 221     \row
 222         \o Permanent
 223         \o Have an object living in another thread and let it perform different
 224            tasks upon request.
 225            This means communication to and from the worker thread is required.
 226         \o Derive a class from QObject and implement the necessary slots and
 227            signals, move the object to a thread with a running event loop and
 228            communicate with the object over queued signal/slot connections.
 229     \row
 230         \o Permanent
 231         \o Have an object living in another thread, let the object perform
 232            repeated tasks such as polling a port and enable communication with
 233            the GUI thread.
 234         \o Same as above but also use a timer in the worker thread to implement
 235            polling. However, the best solution for polling is to avoid it
 236            completely. Sometimes using QSocketNotifier is an alternative.
 237     \endtable
 238
 239
 240     \section1 Qt Thread Basics
 241
 242     QThread is a very convenient cross platform abstraction of native platform
 243     threads. Starting a thread is very simple. Let us look at a short piece of
 244     code that generates another thread which says hello in that thread and then
 245     exits.
 246
 247     \snippet examples/tutorials/threads/hellothread/hellothread.h 1
 248
 249     We derive a class from QThread and reimplement the \l{QThread::}{run()}
 250     method.
 251
 252     \snippet examples/tutorials/threads/hellothread/hellothread.cpp 1
 253
 254     The run method contains the code that will be run in a separate thread. In
 255     this example, a message containing the thread ID will be printed.
 256     QThread::start() will call the method in another thread.
 257
 258     \snippet examples/tutorials/threads/hellothread/main.cpp 1
 259
 260     To start the thread, our thread object needs to be instantiated. The
 261     \l{QThread::}{start()} method creates a new thread and calls the
 262     reimplemented \l{QThread::}{run()} method in this new thread. Right after
 263     \l{QThread::}{start()} is called, two program counters walk through the
 264     program code. The main function starts with only the GUI thread running and
 265     it should terminate with only the GUI thread running. Exiting the program
 266     when another thread is still busy is a programming error, and therefore,
 267     wait is called which blocks the calling thread until the
 268     \l{QThread::}{run()} method has completed.
 269
 270     This is the result of running the code:
 271
 272     \badcode
 273     hello from GUI thread  3079423696
 274     hello from worker thread  3076111216
 275     \endcode
 276
 277
 278     \section2 QObject and Threads
 279
 280     A QObject is said to have a \e{thread affinity} or, in other words, that it
 281     lives in a certain thread. This means that, at creation time, QObject saves
 282     a pointer to the current thread. This information becomes relevant when an
 283     event is posted with \l{QCoreApplication::}{postEvent()}. The event will be
 284     put in the corresponding thread's event loop. If the thread where the
 285     QObject lives doesn't have an event loop, the event will never be delivered.
 286
 287     To start an event loop, \l{QThread::}{exec()} must be called inside
 288     \l{QThread::}{run()}. Thread affinity can be changed using
 289     \l{QObject::}{moveToThread()}.
 290
 291     As mentioned above, developers must always be careful when calling objects'
 292     methods from other threads. Thread affinity does not change this situation.
 293     Qt documentation marks several methods as thread-safe.
 294     \l{QCoreApplication::}{postEvent()} is a noteworthy example. A thread-safe
 295     method may be called from different threads simultaneously.
 296
 297     In cases where there is usually no concurrent access to methods, calling
 298     non-thread-safe methods of objects in other threads may work thousands
 299     of times before a concurrent access occurs, causing unexpected behavior.
 300     Writing test code does not entirely ensure thread correctness, but it is
 301     still important.
 302     On Linux, Valgrind and Helgrind can help detect threading errors.
 303
 304     The anatomy of QThread is quite interesting:
 305
 306     \list
 307     \o QThread does not live in the new thread where \l{QThread::}{run()} is
 308        executed. It lives in the old thread.
 309     \o Most QThread methods are the thread's control interface and are meant to
 310        be called from the old thread. Do not move this interface to the newly
 311        created thread using \l{QObject::}{moveToThread()}; i.e., calling
 312        \l{QObject::moveToThread()}{moveToThread(this)} is regarded as bad
 313        practice.
 314     \o \l{QThread::}{exec()} and the static methods
 315        \l{QThread::}{usleep()}, \l{QThread::}{msleep()},
 316        \l{QThread::}{sleep()} are meant to be called from the newly created
 317        thread.
 318     \o Additional members defined in the QThread subclass are
 319        accessible by both threads. The developer is responsible for
 320        coordinating access. A typical strategy is to set the members before
 321        \l{QThread::}{start()} is called. Once the worker thread is running,
 322        the main thread should not touch the additional members anymore. After
 323        the worker has terminated, the main thread can access the additional
 324        members again. This is a convenient strategy for passing parameters to a
 325        thread before it is started as well as for collecting the result once it
 326        has terminated.
 327     \endlist
 328
 329     A QObject's parent must always be in the same thread. This has a surprising
 330     consequence for objects generated within the \l{QThread::}{run()} method:
 331
 332     \code
 333     void HelloThread::run()
 334     {
 335          QObject *object1 = new QObject(this);  //error, parent must be in the same thread
 336          QObject object2;  // OK
 337          QSharedPointer <QObject> object3(new QObject); // OK
 338     }
 339     \endcode
 340
 341     \section2 Using a Mutex to Protect the Integrity of Data
 342
 343     A mutex is an object that has \l{QMutex::}{lock()} and \l{QMutex::}{unlock()}
 344     methods and remembers if it is already locked. A mutex is designed to be
 345     called from multiple threads. \l{QMutex::}{lock()} returns immediately if
 346     the mutex is not locked. The next call from another thread will find the
 347     mutex in a locked state and then \l{QMutex::}{lock()} will block the thread
 348     until the other thread calls \l{QMutex::}{unlock()}. This functionality can
 349     make sure that a code section will be executed by only one thread at a time.
 350
 351     The following line sketches how a mutex can be used to make a method
 352     thread-safe:
 353
 354     \code
 355     void Worker::work()
 356     {
 357         this->mutex.lock();  // first thread can pass, other threads will be blocked here
 358         doWork();
 359         this->mutex.unlock();
 360     }
 361     \endcode
 362
 363     What happens if one thread does not unlock a mutex? The result can be a
 364     frozen application. In the example above, an exception might be thrown and
 365     \c{mutex.unlock()} will never be reached. To prevent problems like this,
 366     QMutexLocker should be used.
 367
 368     \code
 369     void Worker::work()
 370     {
 371         QMutexLocker locker(&mutex);  // Locks the mutex and unlocks when locker exits the scope
 372         doWork();
 373     }
 374     \endcode
 375
 376     This looks easy, but mutexes introduce a new class of problems: deadlocks.
 377     A deadlock happens when a thread waits for a mutex to become unlocked, but
 378     the mutex remains locked because the owning thread is waiting for the first
 379     thread to unlock it. The result is a frozen application. Mutexes can be
 380     used to make a method thread safe. Most Qt methods aren't thread safe
 381     because there is always a performance penalty when using mutexes.
 382
 383     It isn't always possible to lock and unlock a mutex in a method. Sometimes
 384     the need to lock spans several calls. For example, modifying a container
 385     with an iterator requires a sequence of several calls which should not be
 386     interrupted by other threads. In such a scenario, locking can be achieved
 387     with a mutex that is kept outside of the object to be manipulated. With an
 388     external mutex, the duration of locking can be adjusted to the needs of the
 389     operation. One disadvantage is that external mutexes aid locking, but do
 390     not enforce it because users of the object may forget to use it.
 391
 392     \section2 Using the Event Loop to Prevent Data Corruption
 393
 394     The event loops of Qt are a very valuable tool for inter-thread
 395     communication. Every thread may have its own event loop. A safe way of
 396     calling a slot in another thread is by placing that call in another
 397     thread's event loop. This ensures that the target object finishes the
 398     method that is currently running before another method is started.
 399
 400     So how is it possible to put a method invocation in an event loop? Qt has
 401     two ways of doing this. One way is via queued signal-slot connections; the
 402     other way is to post an event with QCoreApplication::postEvent(). A queued
 403     signal-slot connection is a signal slot connection that is executed
 404     asynchronously. The internal implementation is based on posted events. The
 405     arguments of the signal are put into the event loop and the signal method
 406     returns immediately.
 407
 408     The connected slot will be executed at a time which depends on what else is
 409     in the event loop.
 410
 411     Communication via the event loop eliminates the deadlock problem we face
 412     when using mutexes. This is why we recommend using the event loop rather
 413     than locking an object using a mutex.
 414
 415     \section2 Dealing with Asynchronous Execution
 416
 417     One way to obtain a worker thread's result is by waiting for the thread
 418     to terminate. In many cases, however, a blocking wait isn't acceptable. The
 419     alternative to a blocking wait are asynchronous result deliveries with
 420     either posted events or queued signals and slots. This generates a certain
 421     overhead because an operation's result does not appear on the next source
 422     line, but in a slot located somewhere else in the source file. Qt
 423     developers are used to working with this kind of asynchronous behavior
 424     because it is much similar to the kind of event-driven programming used in
 425     GUI applications.
 426
 427     \section1 Examples
 428
 429     This tutorial comes with examples for Qt's three basic ways of working with
 430     threads. Two more examples show how to communicate with a running thread
 431     and how a QObject can be placed in another thread, providing service to the
 432     main thread.
 433
 434     \list
 435     \o Using QThread as shown \l{Qt thread basics}{above}
 436     \o \l{Example 1: Using the Thread Pool}{Using the global QThreadPool}
 437     \o \l{Example 2: Using QtConcurrent}{Using QtConcurrent}
 438     \o \l{Example 3: Clock}{Communication with the GUI thread}
 439     \o \l{Example 4: A Permanent Thread}{A permanent QObject in another thread
 440        provides service to the main thread}
 441     \endlist
 442
 443     The following examples can all be compiled and run independently. The source can
 444     be found in the examples directory: examples/tutorials/threads/
 445
 446     \section2 Example 1: Using the Thread Pool
 447
 448     Creating and destroying threads frequently can be expensive. To avoid the
 449     cost of thread creation, a thread pool can be used. A thread pool is a
 450     place where threads can be parked and fetched. We can write the same
 451     "hello thread" program as \l{Qt Thread Basics}{above} using the global
 452     thread pool. We derive a class from QRunnable. The code we want to run in
 453     another thread needs to be placed in the reimplemented QRunnable::run()
 454     method.
 455
 456     \snippet examples/tutorials/threads/hellothreadpool/hellothreadpool.cpp  1
 457
 458     We instantiate Work in main(), locate the global thread pool and use the
 459     QThreadPool::start() method. Now the thread pool runs our worker in another
 460     thread. Using the thread pool has a performance advantage because threads
 461     are not destroyed after they have finished running. They are kept in a pool
 462     and wait to be used again later.
 463
 464     \section2 Example 2: Using QtConcurrent
 465
 466     \snippet examples/tutorials/threads/helloconcurrent/helloconcurrent.cpp  1
 467
 468     We write a global function hello() to implement the work. QtConcurrent::run()
 469     is used to run the function in another thread. The result is a QFuture.
 470     QFuture provides a method called \l{QFuture::}{waitForFinished()}, which
 471     blocks until the calculation is completed. The real power of QtConcurrent
 472     becomes visible when data can be made available in a container. QtConcurrent
 473     provides several functions that are able to process itemized data on all
 474     available cores simultaneously. The use of QtConcurrent is very similar to
 475     applying an STL algorithm to an STL container.
 476     \l{examples-threadandconcurrent.html}{QtConcurrent Map} is a very short and
 477     clear example about how a container of images can be scaled on all available
 478     cores. The image scaling example uses the blocking variants of the functions
 479     used. For every blocking function there is also a non-blocking, asynchronous
 480     counterpart. Getting results asynchronously is implemented with QFuture and
 481     QFutureWatcher.
 482
 483     \section2 Example 3: Clock
 484
 485     \image thread_clock.png "clock"
 486
 487     We want to produce a clock application. The application has a GUI and a
 488     worker thread. The worker thread checks every 10 milliseconds what time it
 489     is. If the formatted time has changed, the result will be sent to the GUI
 490     thread where it is displayed.
 491
 492     Of course, this is an overly complicated way of designing a clock and,
 493     actually, a separate thread is unnecessary. We would be better off placing
 494     the timer in the main thread because the calculation made in the timer slot
 495     is very short-lived. This example is purely for instructional use and shows
 496     how to communicate from a worker thread to a GUI thread. Note that
 497     communication in this direction is easy. We only need to add a signal
 498     to QThread and make a queued signal/slot connection to the main thread.
 499     Communication from the GUI to the worker thread is shown in the next
 500     example.
 501
 502     \snippet examples/tutorials/threads/clock/main.cpp  1
 503
 504     We've connected the \c clockThread with the label. The connection must be a
 505     queued signal-slot connection because we want to put the call in the event
 506     loop.
 507
 508     \snippet examples/tutorials/threads/clock/clockthread.h  1
 509
 510     We have derived a class from QThread and declared the \c sendTime() signal.
 511
 512     \snippet examples/tutorials/threads/clock/clockthread.cpp  1
 513
 514     The trickiest part of this example is that the timer is connected to its
 515     slot via a direct connection. A default connection would produce a queued
 516     signal-slot connection because the connected objects live in different
 517     threads; remember that QThread does not live in the thread it creates.
 518
 519     Still it is safe to access ClockThread::timerHit() from the worker thread
 520     because ClockThread::timerHit() is private and only touches local variables
 521     and a private member that isn't touched by public methods.
 522     QDateTime::currentDateTime() isn't marked as thread-safe in Qt
 523     documentation, however we can get away with using it in this small
 524     example because we know that the QDateTime::currentDateTime() static
 525     method isn't used in any other threads.
 526
 527     \section2 Example 4: A Permanent Thread
 528
 529     This example shows how it is possible to have a QObject in a worker thread
 530     that accepts requests from the GUI thread, does polling using a timer and
 531     continuously reports results back to the GUI thread. The actual work
 532     including the polling must be implemented in a class derived from QObject.
 533     We have called this class \c WorkerObject in the code shown below. The
 534     thread-specific code is hidden in a class called \c Thread, derived from
 535     QThread.
 536     \c Thread has two additional public members. The \c launchWorker() member
 537     takes the worker object and moves it to another thread with a started event
 538     loop.
 539     The call blocks for a very short moment until the thread creation operation
 540     is completed, allowing the worker object to be used again on the next line.
 541     The \c Thread class's code is short but somewhat involved, so we only show
 542     how to use the class.
 543
 544     \snippet examples/tutorials/threads/movedobject/main.cpp  1
 545
 546     QMetaObject::invokeMethod() calls a slot via the event loop. The worker
 547     object's methods should not be called directly after the object has been
 548     moved to another thread. We let the worker thread do some work and polling,
 549     and use a timer to shut the application down after 3 seconds. Shutting the
 550     worker down needs some care. We call \c{Thread::stop()} to exit the event
 551     loop. We wait for the thread to terminate and, after this has occurred, we
 552     delete the worker.
 553
 554     \section1 Digging Deeper
 555
 556     Threading is a very complicated subject. Qt offers more classes for
 557     threading than we have presented in this tutorial. The following materials
 558     can help you go into the subject in more depth:
 559
 560     \list
 561     \o Good video tutorials about threads with Qt can be found in the material
 562        from the \l{Training Day at Qt Developer Days 2009}.
 563     \o The \l{Thread Support in Qt} document is a good starting point into
 564        the reference documentation.
 565     \o Qt comes with several additional examples for
 566        \l{Threading and Concurrent Programming Examples}{QThread and QtConcurrent}.
 567     \o Several good books describe how to work with Qt threads. The most
 568        extensive coverage can be found in \e{Advanced Qt Programming} by Mark
 569        Summerfield, Prentice Hall - roughly 70 of 500 pages cover QThread and
 570        QtConcurrent.
 571     \endlist
 572 */