Warning, /frameworks/threadweaver/examples/HelloInternet.in.md is written in an unsupported language. File is not indexed.

 ## Doing things in a Sequence
 
 The time when an application starts, especially one that needs
 to load quite some data, is usually one of contention. Translations
 need to be loaded and resources like icons and images initialized. As
 the application matures, more and more of such tasks are piled on to
 it. It will have to check for updates from a server, and load a
 greeting of the day to the user. Eventually, the application will
 take ages to load, users will tweet about how they are making coffee
 while it comes up, and the programmers will start to find a solution. 
 
 The application will come up a lot faster if it defers as many
 tasks as possible while it creates and shows the user interface, and
 also takes as many as possible of the startup tasks of an application
 off the main thread. The main thread is the one that runs when
 `main()` is entered, and in which the user interface lives. Everything
 that slows down or intermittendly blocks the main thread may be
 experienced by the user as the user interface being sluggish or
 hung. This is a common use case where concurrent programming can
 help. 
 
 But ... this is also one of the examples where standard thread pools
 fail. The startup tasks commonly need to be done in a certain order
 and are of different priority, and also should not be all tackled by
 the application process at the same time. 
 For example, the applications icons and translations may be needed
 first and urgently, where the information on available updates can
 still be processed a couple of seconds later. There are ways around
 this that are rather cumbersome, like using timers to queue up some
 tasks later or using chains of functions that queue up new tasks when
 one group is done. The following example will illustrate some aspects
 of how ThreadWeaver comes with the necessary tools to specify the
 order of tasks, on application startup and otherwise. The following
 `main()`[^4] function allocates a main widget and an object of type
 `ViewController` that takes care of the startup tasks.
 
 @@snippet(HelloInternet/main.cpp,hellointernet-main,cpp)
 
 The example application shows an image that it eventually loads from
 the network, and a caption for it. In the constructor of
 `ViewController`, the startup operations need to be kicked off. The
 operations in this example are 
 
 * to load a placeholder image that is shown while the application
   loads the image and caption from the network,
 * to load the post that contains the caption, but only the URL of the
   image to show,
 * and then, once the image URL is known, to finally load the image
   from the network and display it.
 
 The application's user interface will be shown right away, even before
 step 1 has been completed. Let's assume that the three steps need to
 be done in order, not in parallel.
 
 The important aspect is to do as little as possible in the
 constructor, considering that it is called from the main
 thread. Creating jobs and queueing them is not expensive however, so
 the constructor focuses on that and then returns.
 
 @@snippet(HelloInternet/ViewController.cpp,hellointernet-sequence,cpp)
 
 Remember the assumption that the three startup steps have to be
 performed in order. The new thing here is that instead of queueing
 individual jobs, the constructor creates a `Sequence`, and then adds
 jobs to that. A sequence has the jobs performed by the thread pool in
 the order they have been added to it. The jobs each simply call a
 member function of `ViewController` when being
 executed. ThreadWeaver's execution logic guarantees that the next job
 is only executed after the previous one has been finished. Because of
 that, only one of the member functions will be called at a time, and
 they will be called in the order the jobs have been added to the
 sequence. 
 
 Since only one of the member functions will be called at a time, there
 is no need for further synchronization of access to the member
 variables of `ViewController`. This raises the question of how the
 controller submits new captions, statuses and images to the main
 widget. It would be a mistake to simply call member functions of the
 main widget from the methods of `ViewController`, since these are
 executed from a worker thread. The controller submits update by using
 Qt signals that are connected to corresponding slots in the main
 widget. The parameters of the signals are passed by value, not by
 reference or pointers, making use of the implicit sharing built into
 Qt to avoid copying. This approach relies on the fact that the
 reference counting of Qt's implicit-sharing mechanism is thread safe. 
 
 @@snippet(HelloInternet/ViewController.cpp,hellointernet-loadresource,cpp)
 
 The method `loadPlaceholderFromResource()` implements the first step,
 to load an image from a resource that acts as a place holder until the
 real images has been downloaded. It cheats to appear busy by first
 sleeping for a short while. While it does so, the user interface will
 already appear to the user, with a blank background. It then emits a
 signal to make the main widget show a status message that indicates
 the program is downloading the post. 
 
 The method is called from the worker thread that executes the job, not
 the main thread. When the signal is emitted, Qt notices that sender and
 receiver are not in the same thread at the time, and sends the signal
 asynchronously. The receiver will not be called from the thread
 executing `loadPlaceholderFromResource()`, instead it will be invoked
 from the event loop of the main thread. That means there is no shared
 data between the controller and the main widget for processing the
 signal, and no further serialization of access to the QString variable
 holding the status text is necessary.
 
 Once the method returns and the job executing it completes, the next
 job of the sequence will be unlocked. This causes the method
 `loadPostFromTumblr()` to be executed by a worker thread. This method
 illustrates the convenience built into Qt to process data present in
 Open Standard formats (XML, in this case), even though this won't be
 discussed here in detail.[^5] If processing the data turns out to be
 expensive, the user interface will not be blocked by it, since it
 is not performed by the main thread.
 
 @@snippet(HelloInternet/ViewController.cpp,hellointernet-loadpost,cpp)
 
 In case an error occurs, the method invokes another method called
 `error()`. `error()` indicates the problem to the user by setting a
 status messages in the main widget. But it also apparently aborts the
 execution of the sequence, as the code assumes it does not continue
 after calling it.
 
 @@snippet(HelloInternet/ViewController.cpp,hellointernet-error,cpp)
 
 `error()` shows a different placeholder image, and emits the status
 message to the main widget. It then raises an exception of type
 `ThreadWeaver::JobFailed`, which will be caught by the worker thread
 executing the current job. The worker thread sets the status of
 the job to a failed state. Specific to sequences (because only
 sequences know the order of the execution of their elements), this
 will cause the sequence to abort the execution of it's remaining
 elements. Raising the exception will abort the processing of the job,
 but not terminate the worker thread. Leaking any other type of
 exception than `ThreadWeaver::Exception` from the `run()` method of a
 job is considered a runtime error. The exception will not be caught by
 the worker thread, and the application will terminate. 
 
 The example illustrates the steps necessary to perform concurrent
 operations in a certain order. It also shows how a specialized
 object (`ViewController`, in this case) can handle the data shared
 between the sequential operations, how to submit data and status
 information back to the user interface, and how to signal error
 conditions from job execution.
 
 ![Hello Internet](screenshots/HelloInternet.png "The HelloInternet
  example, after downloading the post") 
 
 [^4]: See `examples/HelloInternet` in the ThreadWeaver repository.
 [^5]: The example uses the
 [Tumblr API version 1](https://www.tumblr.com/docs/en/api/v1).