Callback for multithreading

The basic Qt multithreading we have seen before was a bit too basic. Its extensions for showing how and why to use QMutex, and then QMutexLocker do not change much of its substance. Let's complicate it a bit to make it a tad more interesting.

In the original example we have a class, Writer, that extends QThread and that in its run() method writes something. But what if we would like that all the Writer object would run a function that could be set at runtime? A possible solution to this requirement is based on function pointers.

In my main file I have written this function:

namespace
{
static QMutex mio; // 1.

void doSomething(const char* msg, int i)
{
QMutexLocker qml(&mio); // 2.
std::cout << msg << ", thread id " << QThread::currentThreadId() // 3.
<< " value " << i << std::endl;
}
}

1. Since we are about to work in a multithreaded environment, and since we'll have many threads competing on the output console, we'll use a mutex to avoid mixups.
2. Using a lock on the mutex we ensure it would be correctly released at the end of the block.
3. We print the thread id and the data passed by the caller.

We want all the object instantiating Writer calling this doSomething() function (and possibly other functions having the same prototype). To do that, I have refactored the Writer class definition in this way:
#ifndef WRITER_H
#define WRITER_H

#include <QThread>

typedef void(*MY_FUN)(const char*, int); // 1.

class Writer : public QThread
{
public:
explicit Writer(int value);
void run();

static void setCallback(MY_FUN fun); // 2.
private:
static MY_FUN callback_; // 3.
};

#endif // WRITER_H

1. MY_FUN has been typedeffed as pointer to a function returning void and having two input parameters, a pointer to const char, and an integer.
2. using this static method we could set the callback function available to all Writer objects.
3. the callback_ function pointer is static: all the Writer object refer to the same one.

The static data members have to be defined in the source code, so in writer.cpp I added the callback_ definition:
MY_FUN Writer::callback_ = NULL;
Initially there is no callback function pointer defined.

And here is the Writer functions:
void Writer::setCallback(MY_FUN fun)
{
callback_ = fun;
}

Writer::Writer(int value)
{
if(callback_) // 1.
callback_("ctor", value);
}

void Writer::run()
{
for(int i = 0; i < 20; ++i)
{
if(callback_)
callback_("Running", i); // 2.

msleep(200);
}
}

1. As always when working with pointers, it is a good idea to check them before trying to use them.
2. Being called from run(), we ensure that our callback function is called in the new thread.

Not a big change in the main function:
int main(int argc, char *argv[])
{
QCoreApplication a(argc, argv);

Writer::setCallback(&doSomething);

Writer w1(1);
Writer w2(2);
Writer w3(3);

w1.start();
w2.start();
w3.start();

w1.wait();
w2.wait();
w3.wait();

// terminates in a couple of seconds
QTimer::singleShot(12000, &a, SLOT(quit()));

return a.exec();
}

What we have done, basically, has been externalizing the job done by each sub-thread, so that it could be easily changed even at runtime.

Go to the full post

Multithreading with a GUI

Have you ever dreamt of a tiny Qt window-based application showing a number that could be continuously increased or decreased pushing on a couple of buttons? Well, that is what we are about to do in this post.

OK, it's a pretty silly application, but it has a few good points to show. Through it we could easily show how the user could stop and start other threads from the main one, and we could see the connect mechanism as a way to allow us to easily establish a communication between different threads.

I leave out the creation of the application graphical part, think of it as a preparatory exercise. As a hint, I tell you that I created by Qt Creator a Qt Gui Application with a QMainWindow. Then, in design mode, I put in the window a QLabel (named lbValue), and a couple of QPushButton objects, btnIncrease and btnDecrease. I have even embellished a bit the mainWindow, adding another QLabel saying "Current value:" and other few details that here have no primary interest (an Exit button, a few menu items ...).

Then I created a connection from each of the two buttons to a slot, right clicking on each of them and selecting the "Go to slot..." item in the popup window, selecting clicked() as signal. In response to that, Qt created a couple of private slots in the MainWindow class declaration, named on_btnDecrease_clicked() and on_btnIncrease_clicked() that are connected as expected to the proper button.

Now the fun stuff.

Actually, what we are going to see here is a Qt antipattern. Using a QThread derived class in this way is attractive but wrong. A working alternative is shown in another post, where I use a callback mechanism in multithreading environment that works right.

We want that clicking on a button a thread starts and modify the label value adding (or subtracting) a specific amount. To do that we can create a class like this:
#ifndef INCREASER_H
#define INCREASER_H

#include <QThread>

class Increaser : public QThread // 1
{
Q_OBJECT // 2
public:
  Increaser(int step); // 3
  void run(); // 4
  void stop(); // 5
  void restart(); // 6
signals:
  void increase(int); // 7
private:
  bool isRunnable_; // 8
  int step_;
};

#endif // INCREASER_H
1. We are extending QThread, as we have already seen previously.
2. We need the Q_OBJECT macro, since we want to use the signal-slot connection mechanism.
3. The ctor requires a step, that we'll use to increment the label value
4. Override of run(), virtual function defined in QThread.
5. Terminates the execution of the current thread.
6. When we want to restart an Increaser that has already been started, we should call this specific method.
7. When the current thread wants the label to be changed emits this signal. If this signal is not connected to any slot, nothing happens.
8. Flag that we use to gracefully stop (and restart) the current thread.

Here its implementation:
Increaser::Increaser(int step) : isRunnable_(true), step_(step) {}

void Increaser::run()
{
  while(true) // 1
  {
    msleep(500); // 2
    if(!isRunnable_) // 3
      break;
    emit increase(step_); // 4
  }
}

void Increaser::stop() // 5
{
  isRunnable_ = false;
  wait();
}

void Increaser::restart()
{
  isRunnable_ = true; // 6
  QThread::start();
}
1. When the current thread runs, it executes this infinite loop.
2. It sleeps for half a second.
3. If a request to stop the thread has been issued, the loop breaks - so the run terminates.
4. If the run is still active, an increase signal is emitted. [Dammit, this does not work as expected - at least, as expected by me. The connect mechanism does not let this code being executed by the current thread, but transfer the request to the main thread. If what you need to call at this point is just a free function, you could have a look at this other post where I use a function pointer as a callback. A more general solution is showed in another post, using a C++ class callback mechanism].
5. The stop() call is synchronous. The run flag is set to false, then we wait till run() terminates, before returning to the caller.
6. If we don't reset the run flag to true, run() would immediately terminate.

Now we are ready to extend our MainWindow:
#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <QMainWindow>
#include <QMutex>
#include "increaser.h"

namespace Ui
{
  class MainWindow;
}

class MainWindow : public QMainWindow
{
Q_OBJECT

public:
  explicit MainWindow(QWidget *parent = 0);
  ~MainWindow();

  void closeEvent(QCloseEvent *); // 1
private slots:
  void on_btnDecrease_clicked(); // 2
  void on_btnIncrease_clicked();
  void changeValue(int); // 3
private:
  Ui::MainWindow *ui;
  Increaser increaser_; // 4
  Increaser decreaser_;

  int curValue_; // 5
  QMutex mCV_; // 6
};

#endif // MAINWINDOW_H
1. We don't want to leave the execution when secondary threads are still running, so we ensure here they are terminated.
2. The two slots created by Designer accordingly to our request.
3. The slot we create to connect to the Increaser signal (notice that this would lead to troubles).
4. A couple of Increaser objects.
5. The current value that is displayed in the label.
6. We'll have two threads competing for changing curValue_, so we should rule its access using a QMutex.

Here is the ctor definition:
MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent), ui(new Ui::MainWindow),
increaser_(2), decreaser_(-3), curValue_(100)
{
  ui->setupUi(this);
  ui->lbValue->setText(QString::number(curValue_)); // 1

  connect(&increaser_, SIGNAL(increase(int)), this, SLOT(changeValue(int))); // 2
  connect(&decreaser_, SIGNAL(increase(int)), this, SLOT(changeValue(int)));
}
1. The label text is set using the starting value given to curValue_.
2. We connect the signal of both Increaser objects to the local slot. They are competing on the same resource. [This looks quite cool, but it does not work as I expected. The connection reside in the current (main) thread, and not in the one managed by the Increaser objects. An alternative approach could be using function pointers. Or we can modify this code using C++ class callback instead.]

I show just one on_xxx_clicked() slot, since they are essentially the same. The difference is that one refers to increaser_ and btnIncrease, the other to decreaser_ and btnDecrease:
void MainWindow::on_btnIncrease_clicked()
{
  if(increaser_.isRunning()) // 1
  { // the thread is running, stop it
    ui->btnIncrease->setText("Start +");
    increaser_.stop();
  }
  else // 2
  { // start (or restart) the thread
    ui->btnIncrease->setText("Stop +");
    increaser_.restart();
  }
}
1. If the thread is already running, clicking the button we ask to stop it.
2. Otherwise we (re)start it. Notice that I just call restart() without caring much of the difference. It would make sense calling explicitly start() only when we wanted to assign a specific priority to the thread.

When a request to close the main window is issued, we ensure the Increaser thread are stopped before terminating:
void MainWindow::closeEvent(QCloseEvent *)
{
  increaser_.stop();
  decreaser_.stop();
}
Here is the slot that lets the Increasers modify the label value:
void MainWindow::changeValue(int step)
{
  QMutexLocker ml(&mCV_);
  ui->lbValue->setText(QString::number(curValue_ += step));
}
Here the code is quite simple, and we shouldn't have much harm even if both thread would try to run it concurrently. Worst case scenario is that both increase on curValue_ happen before the label is actually displayed, so we could lose to see a number that was doomed to disappear in moment. In any case, using a QMutexLocker we ensure it working correctly, without losing anything at all. [Actually, currently here the mutex has no use at all, since this function is not called by different threads, as I expected. See an alternative using function pointers and another, more to the point, that uses C++ object callback]

Go to the full post

RAII for QMutex by QMutexLocker

When more than a thread is competing on a shared resource, we are bound to have problems. Using a QMutex is the most common answer in Qt for this issue.

Still, we should design the code carefully - if it is not trivial as the one I am using for these examples - to ensure that all the calls to lock()/unlock() match correctly, an we should pay extra care on the possible exceptions that could break that matching.

RAII (Resouce Acquisition Is Initialization) paradigm helps us to solve this concern, keeping our code even more readable. And QMutexLocker is the Qt class designed to do that.

The RAII idea is that when we need to acquire a resource we should think of this as a initialization, so, in our case we should think to acquiring a lock on the mutex as the creation of an object (of type QMutexLocker) that accept the mutex as initialization parameter. Doing that we save ourselves the hassle of remembering to unlock() the mutex, since that would be automatically done by the QMutexLocker dtor.

And what if an exception happens just after the QMutexLocker object is allocated? No problem at all. The C++ mechanism of stack unwinding ensures that all objects on the stack are correctly disposed.

All this safety is achieved rewriting the run() function from the previous post in this way:
void Writer::run()
{
for(int i = 0; i < 20; ++i)
{
{
QMutexLocker qml(&mio_);
std::cout << '[' << qPrintable(mark_) << value_ << ']';
}

msleep(200);
}
}

If you are wondering why I have put the QMutexLocker object and the print statements in a block of their own, you should remember that we want the locking on the mutex to be effective in the shortest possible region of the code. Since we are using a QMutexLocker object to rule it, we create an artificial block, just to get the effect of making that object exiting of its scope as soon as possible, unlocking the mutex.

Go to the full post

QMutex for shared resources

It is almost an everyday experience seeing a problem rising from the fact that two or more guys competes on a resource available to both.

The resource could be a door, wide enough just to let pass a single person. How to decide who should wait and who could pass? In computer sciences we could use a mutex (short for MUTual EXclusion) to take that decision, and Qt implements this concept in the QMutex class.

In a multithreading environment, the standard output console is a good example of a shared resource for which different threads competes. To let this issue emerge, I have slightly modified the example of the previous post, where we played with a simple multithreading Qt application. I have made the class Writer moderately more complex, adding a private integer member, named value_, and I changed accordingly its ctor, to let the user code a way to set the new data member:
explicit Writer(const QString& mark, int value = 42) : mark_(mark), value_(value) {}
Besides, I changed the printing line in the Writer::run() method in this way:
std::cout << '[' << qPrintable(mark_) << value_ << ']';
Actually, I have also changed the main, passing 1, 2, and 3 as second parameter to the ctor for each Writer object, and this was the first output line I have got running the application:
[One[Three3]1][Two2][Three3][One1][Two2][Three3][One1][Two2][Three[One1]3][Two2]
As you can see, we have an issue. Often nothing bad happens, and we have the print just as we exptected: "[One1]". But sometimes we get funny results, like the very first chunk of characters: "[One[Three3]1]". What happened there is quite clear, Thread 1 was happily executing its printing line, had already sent the first part of it, "[One", to the standard output console, when Thread 3 jumped in, printed all its stuff, "[Three3]", before giving back the control to Thread 1 that, completely unaware of the interruption, sent the final part, "1]", to the console.

This is usually bad, as you can imagine. And the worst part is that the unexpected behaviour happens randomly, making it a possible nightmarish debugging issue.

Luckly we have ways to avoid this scenario. Using QMutex we could redesign our Writer class in this way:
#ifndef WRITER_H
#define WRITER_H

#include <QThread>
#include <QString>
#include <QMutex>

class Writer : public QThread
{
public:
explicit Writer(const QString& mark, int value = 42) : mark_(mark), value_(value) {}

void run();
private:
QString mark_;
int value_;

static QMutex mio_;
};

#endif // WRITER_H

The focal point is that we added a unique QMutex object available to all the class instances - that is the sense of making it static - so that it would be the access ruler to the IO. Its name should suggest its raison d'être: mio_ as mutex for I/O.

Being a static variable it has to be defined somewhere in the source code, I put it in the writer.cpp file, just before the run() definition:
QMutex Writer::mio_;

void Writer::run()
{
for(int i = 0; i < 20; ++i)
{
mio_.lock(); // 1.
std::cout << '[' << qPrintable(mark_) << value_ << ']';
mio_.unlock(); // 2.

msleep(200);
}
}

1. Any thread executing the run() code, before printing - using the shared resource std::cout - tries to acquire a lock on the mutex. If another thread has locked the mutex, the current one patiently sits waiting for it.
2. As soon as the thread has finished using the shared resource, it should release the lock on the mutex, giving a chance to the other threads to access it.

As we can see running this new version of the application, this approach works fine, and it is ok in such a simple case, but it is far from being perfect. We rely too heavily on the programmer to match correctly lock()/unlock() on a mutex and we are not considering the risk of an exception happening just after we locked a mutex and before we could unlock it. In the next post we'll see a more robust solution.

Go to the full post

Basic multithreading with Qt

Qt provides a class, QThread, that helps us creating multithreading applications. The basic idea is that you create a your own class derived from QThread, implement its run() method to do what you expect it doing and then use it instantiating an object of that class for each thread you want to be available, and explicitely starting it.

As an example, think to a writer class that simply outputs a few times a string:
#ifndef WRITER_H
#define WRITER_H

#include <QThread>
#include <QString>

class Writer : public QThread
{
public:
explicit Writer(const QString& mark) : mark_(mark) {}

void run();
private:
QString mark_;
};

#endif // WRITER_H

As said, we redefine run(), virtual QThread function to let it performs a specific task:
void Writer::run()
{
for(int i = 0; i < 20; ++i)
{
std::cout << qPrintable(mark_);
msleep(200);
}
}

The QThread::msleep() function is used to put the current thread to sleep for the passed millisecs.

Here is the main function for this first approach to Qt multithreading:
#include <QtCore/QCoreApplication>
#include <QTimer>
#include "writer.h"

int main(int argc, char *argv[])
{
QCoreApplication a(argc, argv); // 1.

Writer w1("One");
Writer w2("Two");
Writer w3("Three"); // 2.

w1.start();
w2.start();
w3.start(); // 3.

w1.wait();
w2.wait();
w3.wait(); // 4.

QTimer::singleShot(12000, &a, SLOT(quit())); // 5.

return a.exec();
}

1. To keep the code as simple as possible, I choose a Qt console application as target.
2. Three objects of the customized QThread subclass have been created.
3. And started. Once started, a thread is on its own till its run() method terminates.
4. We wait till all three sub-threads complete their job.
5. Then we send an event to the application loop, for asking to terminate in a dozen of seconds.

Go to the full post

From QDialog to statusBar

In the previous post I have used a dialog in modeless way. Here we see a modal dialog in action.

I want to let the user input a message he wants to display on the main window status bar, specifying also how long he'd like such a message being visible.

To do that I have slightly modified the dialog of the previous post, adding a QLineEdit element, named lineEdit, to let the user input the message to be displayed, and a QSpinBox, spinBox, to let him specify the requested time. There is not much to say about doing this stuff with the Qt Creator Design module, maybe it has some interest saying that I have set the spinBox property maximum to 10, so that the interval is now [0..10].

I have changed the DlgHello class declaration adding a couple of public methods like this:
class DlgHello : public QDialog
{
Q_OBJECT
public:
explicit DlgHello(QWidget *parent = 0);
QString getMessage();
int getDelay();
// ...
};

And here is their definition:
QString DlgHello::getMessage()
{
return ui->lineEdit->text();
}

int DlgHello::getDelay()
{
return ui->spinBox->value() * 1000;
}

Not much to say about getMessage(), but getDelay() is a bit more interesting since it returns the spinBox value multiplied by one thousand. The reason for that is that the status bar expects the time expressed in milliseconds, while in the spin box I expressed the value in seconds.

Here is the change in the main window:
void MainWindow::sayHello()
{
DlgHello dlg(this);
if(dlg.exec())
ui->statusBar->showMessage(dlg.getMessage(), dlg.getDelay());
}

Now we work on a DlgHello local variable defined in the method called as slot when the triggered() signal is emitted for the Say Hello action. Calling exec() on it makes us checking if the user click the OK button or not. In case of OK we show the message in the status bar with the specified delay. Notice that if user specifies 0 as delay, the message is shown as long as possible, until another element in the window requires to change the message on the status bar.

Go to the full post

Connecting Ui action to window function

A key feature to understand in Qt is the signal-slot relation. It could useful to get how it works thinking to an example like this one: Say that we have a MainWindow class created with Qt Creator in design mode, with a menu item for actionSayHello. We want that when the user call the related action, a dialog pops up saying hello to him.

One way to do that requires us to add to our MainWindow class a slot and the definition of a pointer to our dialog class:
class MainWindow : public QMainWindow
{
Q_OBJECT

// ...

private slots:
void sayHello();

// ...
private:
// ...
DlgHello* dlgHello;
};


The class ctor would now initialize to NULL the pointer to the dialog and provide a connection from the Ui action to the slot in the main window class:
MainWindow::MainWindow() : QMainWindow(NULL), ui(new Ui::MainWindow),
dlgHello(NULL)
{
ui->setupUi(this);
connect(ui->actionSayHello, SIGNAL(triggered()), this, SLOT(sayHello()));
}

We say that the signal triggered() for the ui actionSayHello object is connected to this sayHello() slot. Now, when the user click on the Say Hallo menu item, the triggered() signal is emitted and, through this connection, the MainWindow::sayHello() slot for this object is called.

Our definition for the sayHello function would be something as:
void MainWindow::sayHello()
{
if(dlgHello == NULL) // 1.
dlgHello = new DlgHello(this);

dlgHello->show(); // 2.
dlgHello->raise();
dlgHello->activateWindow();
}

1. Lazy initilization for the dialog - the first time the function is called, the object is created. This is a modeless dialog, so we just create it once and show/hide it accordingly to user requests.
2. Actually, calling all three these functions on the dialog is a bit an overkilling. It would be cleaner to call just show() if the dialog is hidden, and otherwise raise() and activateWindow(). But if the dialog is not hidden, show() does nothing, so writing the code in this way save us to some extra-typing that wouldn't add any value to our function.

Go to the full post

QApplication and QMainWindow

Even though is possible using Qt in console mode, typically a Qt application has a graphic user interface.

That means that the event loop is managed by a QApplication instance, and the user interact with the application through widgets. As startup widget we could use any reasonable class derived from QWidget, but the normal choice fall on QMainWindow or, better, on a subclass of it that we create in our application.

Here we are going to see how it's easy to generate a main window for our application using Qt Creator.

Large part of the job is done by Qt Creator itself as we specify that we want to create a new project - Qt Gui Application, and specify that we want our MainWindow has QMainWindow as base class. Other possible alternatives here are QWidget and QDialog.

The standard main file generated by Qt Creator in this case is something like this:

#include <QtGui/QApplication>
#include "mainwindow.h"

int main(int argc, char *argv[])
{
QApplication a(argc, argv);
MainWindow w;
w.show();

return a.exec();
}

A QApplication object is instantiated, passing to it the arguments coming from the command line; and then a MainWindow object is created and showed. Finally the QApplication::exec() method is called, that would run the event loop manager.

This is already a working Qt GUI application, but let's add to it some minimal customization.
#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <QMainWindow>
#include <memory>

namespace Ui {
class MainWindow;
}

class MainWindow : public QMainWindow
{
Q_OBJECT

public:
explicit MainWindow(); // 1.

private:
MainWindow(const MainWindow&); // 2.
MainWindow& operator=(const MainWindow&);

void closeEvent(QCloseEvent* event); // 3.
std::auto_ptr<Ui::MainWindow> ui; // 4.
};

#endif // MAINWINDOW_H

1. I want MainWindow having always no ancestor, so I give no chance of passing to it a parent.
2. I don't want MainWindow to be copied, so I explicitely make unusable its copy ctor and assignment operator.
3. Let's add a check on the application end.
4. And let's be smart on the UI pointer, using an auto_ptr (no need for a more advanced smart pointer). In this way there is no need anymore for dtor in this class.

And here are the changes in the class implementation:
#include "mainwindow.h"
#include "ui_mainwindow.h"
#include <QMessageBox>
#include <QCloseEvent>

MainWindow::MainWindow() : QMainWindow(NULL), ui(new Ui::MainWindow) // 1.
{
ui->setupUi(this);
}

void MainWindow::closeEvent(QCloseEvent* event) // 2.
{
int res = QMessageBox::warning(this, windowTitle(), "Are you sure?",
QMessageBox::Yes|QMessageBox::No);
if(res == QMessageBox::Yes)
event->accept(); // 3.
else
event->ignore(); // 4.
}

1. The QMainWindow ctor is called passing always NULL as parameter: no ancestor ever for objects of this class.
2. It's a virtual function defined in QWidget used to give the subclasses a chance to do so something when the user ask to close a window.
3. If the user confirms he wants to close the window, we mark the event as to be accepted.
4. The user changed his mind, we mark the event as to be ignored - the window won't be closed.

Besides this changes in the code, I made also a few changes in the GUI, using the internal Design Editor.

Firstly, I wanted "Simple App" be the title of my window. To do that, I selected MainWindow as current object in the Object Inspector (if you can't find it, check it in the menu Window - submenu View) and then, in the Property Editor I put the name I choose in the windowTitle field.

Secondly, I added a Menu, named File, with two items: Say Hello (currently doing nothing) and Exit (to close the window in an alternative way with respect to clicking on the 'X' on the window right top). This is done easily acting directly on the window as showed by the desing editor.

Thirdly, I wanted to associate a shortcut, Alt-X, to the Exit action. This could be done through the Action Editor window (if you don't see this windows, check the menu Window - submenu Views - Action Editor item). Double click on the item actionExit, it has been created for me by the Design Editor when I created the menu item Exit (by the way, I entered it as "E&xit" so that its x is interpreted as a shortcut in the menu) and you have access to all the details for the action. I was interested in adding a shortcut to it, so I entered it in the relative input line.

One more thing I wanted to do, was adding a connection between the Exit action and the window closing, so that clicking on the Exit menu item, or entering Alt-X, would actually close my window. I did that in the Signals & Slots Editor that should be accessible as a tabbed window besides the Action Editor. If you can't see it go in the menu Window - submenu Views - and check the relative item. I clicked on the big green plus to add a new connection, then I specified: actionExit as sender, triggered() as signal, MainWindow as receiver, and close() as slot.

If I get back to the Edit view (clicking on the Edit icon on the left in the Qt Creator window) I see the form as an XML file, in my case named mainwindow.ui, and I can check how the changes I made are reflected here.

Go to the full post

Ftp with Qt

As a better example of usage for QCoreApplication, we can see how to use QFtp, the Qt class that provides an implementation for an FTP client.

I wrote this post after reading the part relative to the same argument in chapter 15 of C++ GUI Programming with Qt4, 2nd Edition by Jasmin Blanchette and Mark Summerfield - Prentice Hall. And I suggest you to read it too for more details on the matter.

Since our project is going to use network features, we should ensure that our .pro file contains a line like this:
QT       += core network
Then, we create a class for managing the FTP access:
#ifndef FTPGETTER_H
#define FTPGETTER_H

#include <QObject>
#include <QFtp>
#include <QFile>
#include <QUrl>

class FtpGetter : public QObject
{
Q_OBJECT
public:
explicit FtpGetter(QObject *parent = 0);

bool getFile(const QUrl& url); // 1.
signals:
void done(); // 2.
private slots:
void ftpDone(bool); // 3.
private:
QFtp ftp;
QFile file;
};
#endif // FTPGETTER_H

1. We'll call getFile() to connect and retrieve a file from a FTP server.
2. This signal would be connected to the job to be done when the FtpGetter job is completed.
3. We'll make this slot be called when the QFtp object signals that its job is done.

In the relative .cpp file we are going to implements the FtpGetter methods in this way:
FtpGetter::FtpGetter(QObject *parent) : QObject(parent)
{
connect(&ftp, SIGNAL(done(bool)), this, SLOT(ftpDone(bool)));
}

The constructor connects the signal done() for the ftp object owned by the class to the ftpDone() slot of this instance.

Large part of the job is done in getFile():
bool FtpGetter::getFile(const QUrl &url)
{
if (!url.isValid())
{
std::cerr << "Error: Invalid URL." << std::endl;
return false;
}

if(url.scheme() != "ftp")
{
std::cerr << "Error: not an ftp address." << std::endl;
return false;
}

if(url.path().isEmpty())
{
std::cerr << "Error: URL has no path." << std::endl;
return false;
}

QString localFileName = QFileInfo(url.path()).fileName();
if(localFileName.isEmpty())
localFileName = "file.out";

file.setFileName(localFileName);
if(!file.open(QIODevice::WriteOnly))
{
std::cerr << "Error: Cannot write file "
<< qPrintable(file.fileName()) << ": "
<< qPrintable(file.errorString()) << std::endl;
return false;
}

ftp.connectToHost(url.host(), url.port(21));
ftp.login();
ftp.get(url.path(), &file);
ftp.close();

return true;
}

After checking that the user passed a good URL, we create a local file name (if possible, we keep the same name of the original file), we open it in write only mode, then we ask our FTP object to perform a connection, login, getting the file, and then close the connection. Notice that all these operation are done asynchronously, so we don't actually know if they succeeded or not at the end of this function call. We return sort of "tentatively" success, waiting for more feedback from FTP.

As we have seen in the ctor, ftpDone() is called in connection to ftp::done(), so it is here that we check if actually the FTP operation has succeeded or not:
void FtpGetter::ftpDone(bool error)
{
if(error)
std::cerr << "Error: " << qPrintable(ftp.errorString()) << std::endl;
else
std::cerr << "File downloaded to " << qPrintable(file.fileName()) << std::endl;
file.close();
emit done();
}

After writing some feedback, this method emits the done() signal.

The main function of our application would take care of instantiating a FptGetter object, calling it with a suitable URL (here I ask for a file on the trolltech server containing the list of mirrors), and connecting the FtpGetter::done() signal to the QCoreApplication::quit() slot for our current application object. That would mean that we quit the application when the FTP transfer has been completed:
int main(int argc, char *argv[])
{
QCoreApplication a(argc, argv);

FtpGetter getter;
QUrl url("ftp://ftp.trolltech.com/mirrors");
std::cout << "Getting file " << qPrintable(url.path())
<< " from " << qPrintable(url.authority());
if(!getter.getFile(url))
{
std::cout << " failed." << std::endl;
return 1;
}

QObject::connect(&getter, SIGNAL(done()), &a, SLOT(quit()));
return a.exec();
}

Notice that in case FtpGetter::getFile() returns failure we don't even care of entering the main loop in the core application object, and just terminating the application instead.

Go to the full post

QCoreApplication says hello

Usually we use Qt to develop a GUI application, but that is not mandatory. We could be interested in developing an application using a feature made available by Qt, like the network or XML support, without any explicit need for a graphical interface.

In this case we can develop a console application, that rely on QCoreApplication, instead of the usual QApplication, to provide an even loop for the application.

As an example, here is a trivial application, that says hello and then terminates. To make the code slightly more interesting, I create a class, Greeter, that provides a slot, sayHello(), to be called to greet the user:
#ifndef GREETER_H
#define GREETER_H

#include <QObject>
#include <iostream>

class Greeter : public QObject
{
Q_OBJECT
public:
explicit Greeter(QObject *parent = 0) : QObject(parent) {}

signals:

public slots:
void sayHello() { std::cout << "Hello" << std::endl; }
};
#endif // GREETER_H

And here is the main:
#include <QtCore/QCoreApplication>
#include <QTimer>
#include "greeter.h"

int main(int argc, char *argv[])
{
QCoreApplication a(argc, argv);

Greeter g;
QTimer::singleShot(2000, &g, SLOT(sayHello())); // 1.
QTimer::singleShot(5000, &a, SLOT(quit())); // 2.

g.sayHello(); // 3.
return a.exec(); // 4.
}

1. We use QTimer to do a delayed call (by 2 secs) to g.sayHello().
2. After 5 secs we'll call the quit() method for our QCoreApplication object, that will have the effect of terminating the call to exec().
3. We call immediately g.sayHello().
4. The Qt application enters the main event loop - that will be interrupted by the delayed call to quit().

Go to the full post

Accessing file as resource

It is a common requirement having a file associated to an application, typically containing properties for its setup.

Let's see how adding and using such a resource file to a Qt C++ application when working with Qt Creator.

Qt stores the information for accessing resources in ancillary XML files identified by the qrc extension. Create a new resource file in Qt Creator is just a matter of creating a new file in the current project, of "Qt" type and "Qt Resource file" specification. Once a resource file is created, we see it in the Resources section of the project.

In the XML file the resources are organized in a structure where is kept the prefix, mimicking the file system structure with the application home directory identified by "/", and the actual file name.

I create a text file named "input.txt" in the home directory for my application, and then I create a textFinder.qrc resource file in my application, and I add, under the home prefix "/" the file "input.txt" I just created. If I open the file with a text editor I see it now contains this XML:
<RCC>
<qresource prefix="/">
<file>input.txt</file>
</qresource>
</RCC>

If I check the project file for my application, I'll see that Qt Creator has added a new section for resources:
RESOURCES += \
textFinder.qrc

Here is a function that uses this resource file:
void MainWindow::loadTextFile()
{
QFile fInput(":/input.txt"); // 1.
fInput.open(QIODevice::ReadOnly); // 2.

QTextStream sin(&fInput); // 3.
QString line = sin.readAll(); // 4.
fInput.close(); // 5.

ui->textEdit->setPlainText(line); // 6.
}

1. QFile ctor accepts as input the file name to be accessed. In this case we want to access a resource, to let it know that to QFile, we prefix the name with a colon ':'.
2. A file could be opened in a few different modes. Here we choose to open it only for reading.
3. We create a textual stream referring to our file handler, and we use it to read from it in memory.
4. Since our file is small, it makes sense to read it all and putting its content in a single string. QTextStream provides another function, readLine(), that gets just one line.
5. It is a good idea to explicitly close a file when we are done with it. In any case, the QFile dtor close it implicitly.
6. This is a GUI application, with form created by Qt Creator. Here I am accessing the textEdit component I have previously put in the form associated to this (main) window. This component is of type QTextEdit, we call on it a method, setPlainText(), to reset its content.

This post is based on the article Creating a Qt C++ Application from the official Qt Reference Documentation for Qt Creator 2.1.

Go to the full post

Qt vs. Comodo

Qt and Comodo don't get along together smoothly. Not a big surprise after all, since one strive to have control of the machine, and the other would like to stop anyone to do anything that looks even just a bit suspicious to it.

I have got a lot of complaining from Comodo while installing the new Qt SDK 1.1 (still a Release Candidate, currently) but nothing terrible.

The real issue came up when I tried to debug a little silly application of mine: I couldn't even reach the main(), and I got was a segmentation fault instead.

After a while of messing around, I got the feeling that it could be caused by a conflict at system level with some other smart guy on my machine. Comodo was the first suspect, and luckily it was also the culprit. Instead of getting in the dirty details, I'll pass you a link to a discussion in the Comodo forum, GDB problem solved!, where you could find a solution, and probably ask for more info, if you need them.

Go to the full post

Generator Semantic Actions

It gets natural using an attribute to feed Boost Spirit Karma, but we can use semantic actions too.

Karma calls a semantic action before the generator is invoked, giving the action a way of providing data to the generator. So, for a double_ generator, the relative action should be in the form
void F(double& n);
As we have seen for parser semantic action, also generator semantic actions should be designed to support other two parameter (a reference to a Context object and to a boolean). In case of action implemented as function we could simply forget about them, Karma is smart enough to let that working by itself. But for functor and standard lambda we have to explicitly mention them as unused_type parameters.

To use an action that generates an integer, like this one:
void readInt(int& i) { i = 42; }
We call karma::generate() in this way:
using boost::spirit::karma::generate;
using boost::spirit::karma::int_;

std::string generated;
std::back_insert_iterator<std::string> sink(generated);
generate(sink, '{' << int_[&readInt] << '}');
std::cout << "Simple function: " << generated << std::endl;

As a result, the generated string should contain 42 between curly braces.

Have a look at the original Boost Spirit Karma documentation for more details. Here is a C++ source file from there with more examples on generator semantic actions.

Go to the full post

Generating text with Spirit Karma

Spirit Karma is the counterpart of Spirit Qi. Qi is used to parse a string using a specified grammar to extract data and put it in internal data structure, while Karma accepts data in internal format and generates a string from them accordingly to the specified grammar.

If you have no Karma at hand, you would probably use sprintf() or std::stringstream to perform the same task. But Karma gives you more flexibility, keeping the code easy to read and maintain, producing code that is usually faster. Even code size should not be an issue. And, if you already use Spirit Qi, Spirit Karma comes out quite naturally. On the negative side, Spirit code generation is not that easy, given the complex structure of the framework, and this could slow down a bit the project build time.

From double to string.

Using Karma to put a double in a string looks a bit of overkilling. But also using standard C++ the resulting code is not the simplest piece of code on Planet Earth. Typically I come out with something like this:
std::string d2str(double d)
{
  std::ostringstream oss;
  oss << d;
  return std::move(oss.str());
}
A standard stringstream object is used as mediator from internal type (double in this case) and a string.

Here is a way to get the same result using Karma:
bool kGenerate1(double d, std::string& s)
{
  using boost::spirit::karma::double_;
  using boost::spirit::ascii::space;
  using boost::spirit::karma::generate;

  std::back_insert_iterator<std::string> sink(s);
  return generate(sink, double_, d);
}
Basically, all the job resolves in calling karma::generate() passing an insert iterator to the collection where we want to push the result (typically a string), the grammar that has to be used (here just double_), and the value that has to be used to generate the result.

Lot of namespaces, but the code itself is even clearer than the one that uses standard functionality. And it should be faster too.

From two double to string.

If the doubles in input are two we have to face a couple of issue. How to pass them to Karma, and how to insert a delimiter between them. First issue could be solved passing explicitly both values to the generator [see comment to this post for details], or using an STL container that contains both of them; and the second issue calling karma::generate_delimited(), that accepts as input a delimiter and a skipper sequence:
bool kGenerate2(const double d1, const double d2, std::string& s) // 1
{
  using boost::spirit::karma::double_;
  using boost::spirit::ascii::space;
  using boost::spirit::karma::generate_delimited;

  std::back_insert_iterator<std::string> sink(s);
  return generate_delimited(sink, double_ << ',' << double_, space, d1, d2); // 2
}

bool kGenerate2(const std::deque<double>& dd, std::string& s) // 3
{
  using boost::spirit::karma::double_;
  using boost::spirit::ascii::space;
  using boost::spirit::karma::generate_delimited;

  std::back_insert_iterator<std::string> sink(s);
  return generate_delimited(sink, double_ << ',' << double_, space, dd);
}
1. First overload for our generating function: it explicitly requires two double values.
2. The grammar could be read as: a double followed by a comma, followed by a second double. Notice there the use of the "put to" operator (<<) that differs from Qi, where the "get from" (>>) is used. As a skipper is used the blank character.
3. Second overload, here I used std::deque as container for the values to be used.

One or more doubles to string.

Let's rewrite the previous case in a more generic way. Now we expect the doubles in input to be one or more, and we leave the user the choice of the used container for them. The grammar now specify that we expect a double followed by zero or more blocks made of a comma followed by a double:
template <typename Container>
bool kGenerate(const Container& c, std::string& s)
{
  using boost::spirit::karma::double_;
  using boost::spirit::ascii::space;
  using boost::spirit::karma::generate_delimited;

  std::back_insert_iterator<std::string> sink(s);
  return generate_delimited(sink, double_ << *(',' << double_), space, c);
}

Output as double or as int

As Nikhil pointed out, my d2str() function above behaves differently to kGenerate1(). The standard stringstream class do not output the fractional part of a double if the passed value has an actual integral internal representation, while Karma relies on the type the user specifies to decide the format to use. I had told it to always use the double_ format, and so I always get a double in output.

If we want our code to mimic the default stringstream behaviour, we could check explicitly on our own the fractional part of the double value. Something like this:
bool kGenerate1b(double d, std::string& s)
{
  using boost::spirit::karma::double_;
  using boost::spirit::karma::int_;
  using boost::spirit::ascii::space;
  using boost::spirit::karma::generate;

  std::back_insert_iterator sink(s);

  double asInt;
  if(std::modf(d, &asInt) == 0.0) // 1
    return generate(sink, int_, d); // 2
  else
    return generate(sink, double_, d);
}

1. The standard C math library provides this useful function modf() that split a double value in its integral and fractional parts. It is just what we need. Only if the fractional part, as returned by modf(), is zero (as double) we are going to dump the input value formatted as a double.
2. When the double in input is actually an integer, I use the karma::int_ format instead.

I based this post on a C++ source file provided by the original Boost Spirit Karma documentation.

Go to the full post

Parser attribute

Each Boost Spirit parser has an attribute. The attribute of a simple parser is easy to spot: for the built-in double_ is variable of double type.

The attribute of a list parser is a std::vector whose underlying type is determined by the attribute type of its elements. So the std::vector<double> is the attribute of
double_ % ','
The interesting consequence is that we can use attributes instead of semantic actions to work on the sequence elements, like we are going to see here below.

The problem

We have a CSV list of floating point numbers in a string, we want to generate from it a std::vector<double> containing its values.

Solution by parser semantic action

Combining the usage of semantic action (implemented by a standard lambda function) with the Boost Spirit shortcut syntax for list we should easily get code like this:
bool parse2vector(const std::string& input, std::vector<double>& vd)
{
using boost::spirit::qi::phrase_parse;
using boost::spirit::qi::unused_type;
using boost::spirit::qi::double_;
using boost::spirit::qi::ascii::space;

auto pushBack = [&vd](double d, unused_type, unused_type){ vd.push_back(d); };

std::string::const_iterator beg = input.begin();
bool ret = phrase_parse(beg, input.end(), double_[ pushBack ] % ',', space);
return beg != input.end() ? false : ret;
}

Piece of cake. For each double_ element found by the parser in the input string the semantic action pushBack is called. The semantic action is a lambda function that has reference access to the vector we want to fill in, and receive as input parameter the double value as parsed by the parser (and other two parameters not used here); then it simply push back in the vector the value.

Could there be anything simpler than that? Actually, yes, there is.

Solution by parser attribute

We could rewrite the same function passing to phrase_parse() an extra parameter, that should match the parser type. As we said above, a list of double_ has a std::vector<double> as attribute:
bool parse2vector(const std::string& input, std::vector<double>& vd)
{
using boost::spirit::qi::phrase_parse;
using boost::spirit::qi::double_;
using boost::spirit::qi::ascii::space;

std::string::const_iterator beg = input.begin();
bool ret = phrase_parse(beg, input.end(), double_ % ',', space, vd);
return beg != input.end() ? false : ret;
}

No more action specified, we let Spirit doing the dirty job for us.

I based this post on a C++ source file provided by the original Boost Spirit Qi documentation.

Go to the full post

Spirit syntax for list

In the previous post we have seen a function, csvSum() that adds up all the elements of a CSV (Comma Separated Value) list returning the result in a double that is passed as input parameter. A user could be surprised by the fact that the double value provided in input is not considered at all. Besides, if we just accept the fact that the function caller could initialize the returned value as he likes, the resulting code is more linear, since we are allowed to manage all the elements in the list in the same way.

That's how the call to phrase_parse() was written in our function:
bool r = phrase_parse(beg, input.end(),
double_[ref(sum) = _1] >> *(',' >> double_[ref(sum) += _1]), space);

The first element in the list is assigned to sum, overwriting whatever the caller has put in it. Instead of it, now we want to use the same parser semantic action for all the elements: ref(sum) += _1.

Having a CSV list (or, more generically speaking, a list of values separated by something) that requires each if its element to be managed in the same way is such a common task that Spirit provides an elegant syntax just for this case.

So, a CSV list of floating point numbers could be expressed with the full notation that we already know:
double_ >> *(',' >> double_)
Or with a more compact syntax that use the percent character to show an indefinite repetition with a separator:
double_ % ','
Usually the separator is just a character, and normally a comma. But the same notation could be used also if the separator is a string. For instance, we could have values separated by an uppercase triple X sequence:
double_ % "XXX"
Said that, this is the change we are about to do in our code:
bool r = phrase_parse(beg, input.end(), double_[ref(sum) += _1] % ',', space);

And we are about to call the adding function like this:
std::string s("1, 3, 4, 5");
double sum = 1000; // 1.

if(csvSum(s, sum) == false)
std::cout << "Bad CSV" << std::endl;

std::cout << "Sum is " << sum << std::endl;

1. Now we should remember to initialize correctly the startup value, otherwise we would get an unexpected result back.

Go to the full post

From CSV to sum

A common, albeit dated, way of storing information in a file, is using CSV (Comma Separated Values) format. Say that you have lists of numbers stored in this way, and you have to provide a function that converts a string containing an unknown number of elements in its resulting sum.

The first idea that jumped to my mind involved std::accumulate(). It requires a standard container to work, so the input should be prepared converting the original string (of characters) to a vector (of doubles).

Not a bad try, but simply exposing the idea, I saw that the most tricky part of the job is not in summing the values, but in parsing the input string to extract the actual values to work with. And if parsing has to be, better using Spirit and Phoenix.

From a parser perspective, the focus is on the grammar that determine if we should accept or not the input. In our case, we could think to the input as a sequence of numbers containing at least an element, having as mandatory separator a comma, and white spaces as skip elements. The first element in the sequence will trigger a semantic action that would intialize the result, all the other elements will perform a semantic action to increase the sum.

So, the grammar should be something like:
double_[setSum] >> *(',' >> double_[incrSum])
Once we found out the grammar, large part of the job is done.

Here is a possible implementation of a function that checks a string for values in the expects format, and return a success flag and the sum of the values:
// ...
#include <string>
#include <boost/spirit/include/qi.hpp>
#include <boost/spirit/include/phoenix_core.hpp>
#include <boost/spirit/include/phoenix_operator.hpp>

bool csvSum(const std::string& input, double& sum)
{
using boost::spirit::qi::phrase_parse;
using boost::spirit::qi::double_;
using boost::phoenix::ref;
using boost::spirit::qi::_1;
using boost::spirit::ascii::space;

std::string::const_iterator beg = input.begin();
bool r = phrase_parse(beg, input.end(),
double_[ref(sum) = _1] >> *(',' >> double_[ref(sum) += _1]), space);

if(beg != input.end())
return false;
return r;
}

If it is not clear to you what is going on in the code, I suggest you to check the previous post on Spirit and Phoenix.

The first semantic action gets the sum by reference, so that it could change it, and assign to it the double value as parsed by Spirit. The second semantic action is called for each subsequent element found by Spirit in the sequence, passing to it the parsed double value, that would be added to sum.

I based this post on a C++ source file provided by the original Boost Spirit Qi documentation.

Go to the full post

Semantic actions with Phoenix

In the Boost Spirit Qi documentation, Phoenix is described as a library defining a sort of "lambda on steroids", and its usage is recommended for implementing semantic actions that have a certain degree on complexity.

Here I'll show the difference when using as a semantic action a free function, a standard lambda function and Phoenix.

What we want to do is a parser that would generate a standard complex, or would give an error in case of malformed input. Our expected input is a string containing just a number, "42", or a complex representation with real and imaginary part included in round brackets - as a bonus we could even accept just a number, for the real part only: "(43, 12)" or "(33)".

Our parser should look something like this:
double_[funR] | '(' >> double_[funR] >> -(',' >> double_[funI]) >> ')';

That reads: A double, on which applying the funR semantic action, or an open round bracket followed by a double, on which applying the funR semantic action, followed by no or one block made of a comma followed by a double, on which applying the funI semantic action; the (possibly missing) block is followed by a close round bracket.

Firstly, we are going to implement the semantic action with a free function. This one:
void setValue(double& lhs, const double rhs) { lhs = rhs; }

And we are going to use it in this way:

template <typename Iterator>
bool parseCpxFun(Iterator first, Iterator last, std::complex<double>& c)
{
using boost::spirit::qi::double_;
using boost::spirit::ascii::space;
using boost::spirit::qi::phrase_parse;

double cReal = 0.0;
double cImg = 0.0; // 1.

auto funR = std::bind(&setValue, std::ref(cReal), std::placeholders::_1); // 2.
auto funI = std::bind(&setValue, std::ref(cImg), std::placeholders::_1);

auto expr = double_[funR] | '(' >> double_[funR] >> -(',' >> double_[funI]) >> ')'; // 3.

bool r = phrase_parse(first, last, expr, space); // 4.

if (!r || first != last) // 5.
return false;
c = std::complex<double>(cReal, cImg); // 6.
return r;
}

1. The parser would set the complex components here defined using the semantic action. The real part has always to be specified, so it is not so important to initialize this variable, but the imaginary part could be missing, so it is crucial having it defaulted to zero.
2. I used a few non strictly necessary variable to make the code more readable, funR and funI bind the semantic action, the function setValue(), to the variables that store the temporary real and imaginary parts. Notice the usage of std::ref() to let std::bind() know the variable should be passed by reference. As third parameter we have a placeholder to the parameter passed to the resulting function. Here I use std::bind() and std::ref(), but if your compiler does not support them yet you can substitute them with boost::bind() and boost::ref().
3. That is the parser, described above, how is implemented here, calling the binds to the free function working as semantic action.
4. And here is how we call phrase_parse(), passing a couple of delimiting iterators, the expression to be used as parser, and what to use as separator.
5. We want our parsing to be quite strict.
6. If the parsing succeeded, we create a complex using the components generated by the semantic actions.

We can simplify a bit the code, using lambda functions to implement semantic actions.

We rearrange the code writter for free function, getting rid of the free function itself, and rewriting parser and function used by it in this way:

// ...
using boost::spirit::qi::unused_type; // 1.

double cReal = 0.0;
double cImg = 0.0;

auto setCR = [&cReal](const double value, unused_type, unused_type) { cReal = value; }; // 2.
auto setCI = [&cImg](const double value, unused_type, unused_type) { cImg = value; };

auto expr = double_[setCR] | '(' >> double_[setCR] >> -(',' >> double_[setCI]) >> ')';

1. It's a real nuisance. As we have already seen, Spirit expect that a lambda function, or even a functor, when used as parser semantic action, accepting three parameter. When we just need the first one, we should use this unused_type for the other two parameters.
2. The lambda works on a variable in scope, cReal or cImg, accessed by reference, accepts a value passed by the caller (and other two unused parameters), and then does the required assignment.

Using Phoenix the code gets even simpler, given that Phoenix is based on boost::lambda that has a looser syntax than standard lambda:

using boost::spirit::qi::_1; // 1.
using boost::phoenix::ref; // 2.

double cReal = 0.0;
double cImg = 0.0;

auto setCR = (ref(cReal) = _1); // 3.
auto setCI = (ref(cImg) = _1);

auto expr = double_[setCR] | '(' >> double_[setCR] >> -(',' >> double_[setCI]) >> ')';

1. The Spirit Qi placeholders are used, since that version is designed explicitly for this usage.
2. Ditto for the Phoenix version of ref.
3. The resulting code is so clean that it makes not much sense putting it in a temporary. The only reason why I left it here is to better show the difference with the previous implementations.

I based this post on a C++ source file provided by the original Boost Spirit Qi documentation.

Go to the full post

Parser Semantic Actions

Usually you don't parse data just to see if they match with a given pattern, but you want take some action that involves the extracted information. This is done in Boost Spirit Qi by the so called parser semantic actions.

An action is nothing more than a C++ function, functor, or lambda function that is called by the parser any time it finds a matching element. The action signature should match the expected prototype relative to the actual parsed element type.

For instance, if a double_ element is parsed, the relative function should be something like
void F(double n);
Actually, there should be other two parameter, that we can safely ignore, and even not put in the function declaration - Spirit Qi takes care of picking up the correct overload - but, as we'll see in a moment, have to be declared as unused when we keep the functor or lambda function approach.

As an example, say that we want to parse a string that should contain an integer between curly brackets, something like "{42}" and, when the integer is detected by the parser, we want a function to be called.

A generic action manager for our problem could be written in this way:
template<typename Fun>
inline void bsGenericAction(const std::string& input, const Fun& fun) // 1.
{
using boost::spirit::qi::int_;

if(!boost::spirit::qi::parse(input.begin(), input.end(), '{' >> int_[fun] >> '}')) // 2.
std::cout << "Bad parsing for " << input << std::endl; // 3.
}

1. It expects in input the string to be parsed and the action that has to be called.
2. Here we are parsing the input using the Spirit Qi parse() function, passing to it the delimiting iterators to the sequence to be checked, and the parser. The function to be called is specified in square brackets.
3. If the parsing fails, we output a log message.

If we want to use as action this free function:
void print(int i) { std::cout << i << std::endl; }
We can use this utility function:
void bsActFFun(const std::string& input)
{
bsGenericAction(input, &print);
}
That should be called like that:
std::string test("{99}");
bsActFFun(test);

If we want to call a member function, like this Writer::print()
class Writer
{
public:
void print(int i) const { std::cout << i << std::endl; }
};
We could use:
void bsActMFun(const std::string& input)
{
Writer w;
auto fun = std::bind(&Writer::print, &w, std::placeholders::_1); // 1.
bsGenericAction(input, fun);
}

1. Maybe is worth spending a few words on the std::bind() usage. With it we are saying to the compiler to use the Writer::print() function associated to the w object, and passing to it the first value that it will be passed to the wrapper. If your compiler does not support yet std::bind(), a C++0x feature, you could rely on the Boost implementation.

Let's consider a functor:
using boost::spirit::qi::unused_type;
class PrintAction
{
public:
void operator()(int i, unused_type, unused_type) const
{
std::cout << i << std::endl;
}
};

As we said above, when using a functor we should specify three parameters. Currently we are interested only in the first one, so we say to Spirit we don't care about the other two in the showed peculiar way.

We use it by calling this function:
void bsActFOb(const std::string& input)
{
bsGenericAction(input, print_action());
}

And finally a lambda function:
void bsActLambda(const std::string& input)
{
using boost::spirit::qi::unused_type;
bsGenericAction(input, [](int i, unused_type, unused_type){ std::cout << i << std::endl; });
}

As a functor, it requires all three parameter specified, even if we don't plan to use them. Your compiler could miss also this feature, this is too a C++0x goodie, and also in this case you could use instead the Boost implementation. Actually, in this case Boost could even look smarter, since it doesn't explicitely ask for the parameters passed to the lambda, we don't have to rely on the unused_type declaration.

The original Boost Spirit Qi documentation provides a supporting C++ source file that I used as a base for this post.

Go to the full post

Parsing with Spirit Qi

A cool thing about Spirit is that it has been designed keeping in mind scalability. That means we could have a limited knowledge of Spirit and yet be able to work with it, if we don't need any fancy feature.

Spirit Qi provides a good number of built-in parsers that could be combined to create our own specific parser. The Spirit tutorial shows us how to start from a built-in parser (double_) to end up with a more complex parser that accepts a list of comma separated floating point numbers.

All the examples we are about to see in this post share the same structure: we call the Spirit Qi function phrase_parse() on a string containing our input specifying the parser that has to be applied, and the "skip-parser" element that could be in the input sequence and should not interfere with the evaluation (typically, and in this case too, anything that is considered a space - blank, return, ...). What we are changing is the parser that has to be used, so I wrote a function that implements the generic behaviour, and requires in input, besides the string containing the text to be evaluate, an expression that represents the parser to use:
#include <boost/spirit/include/qi.hpp>
#include <string>

// ...

template<typename Expr>
inline bool genericParse(const std::string& input, const Expr& expr)
{
std::string::const_iterator first = input.begin();

bool r = boost::spirit::qi::phrase_parse( // 1.
first, // 2.
input.end(),
expr, // 3.
boost::spirit::ascii::space // 4.
);
if(first != input.end()) // 5.
return false;
return r;
}

1. The phrase_parse() returns true if the input sequence is parsed correctly.
2. First two arguments: iterators delimiting the sequence.
3. Third argument: the parser.
4. Fourth argument: the skip-parser element
5. Here we implement a stricter parsing: we check that there is no trailing leftover.

Parsing a number

Now it is quite easy to implement a function that parses a floating point number:
bool bsParseDouble(const std::string& input)
{
return genericParse(input, boost::spirit::qi::double_);
}

boost::spirit::qi::double_ is the built-in parser that is used to identify a number that could be stored in a double variable.

I find that test cases are very useful not only to verify the correctness of the code we produce, but also to understand better what existing code actually does. So I have written a bunch of test cases to verify how the above written code behaves. Here is just the first one I have written:
TEST(BSParseDouble, Double)
{
std::string input("1.21");
EXPECT_TRUE(bsParseDouble(input));
}

Parsing two numbers

For parsing two floating point numbers we have to create a custom parser:
bool bsParseTwoDouble(const std::string& input)
{
auto expr = boost::spirit::qi::double_ >> boost::spirit::qi::double_;
return genericParse(input, expr);
}

Spirit overloads the operator right shift (>>) as a way to convey the meaning of "followed by". So we could read the custom parser we create as: a double followed by another double. And here is it one of the tests I have written for this function:
TEST(BSParseTwoDouble, Double)
{
std::string input("1.21");
EXPECT_FALSE(bsParseTwoDouble(input));
}

Parsing zero or more numbers

A postfix star (known as Kleene Star) is the usual way a zero or more repetition of a expression is represented in regular expressions. The problem is that there is no postfix start operator in C++, so that was not a possible choice for the Spirit designers. That's the reason why a postfix star is used instead:
bool bsParseKSDouble(const std::string& input)
{
return genericParse(input, *boost::spirit::qi::double_);
}

A test I wrote for this function ensures that a sequence of three double is accepted; another one is to check that a couples of ints in a few blanks are accepted too:
TEST(BSParseKSDouble, TrebleDouble)
{
std::string input("1.21 7.44 8.03");
EXPECT_TRUE(bsParseKSDouble(input));
}

TEST(BSParseKSDouble, BlankIntIntBlank)
{
std::string input(" 42 33 ");
EXPECT_TRUE(bsParseKSDouble(input));
}

Parsing a comma-delimited list of numbers

Finally, the big fish of this post. We expect at least one number, and a comma should be used as delimitator:
bool bsParseCSDList(const std::string& input)
{
auto expr = boost::spirit::qi::double_ >>
*(boost::spirit::qi::char_(',') >> boost::spirit::qi::double_);
return genericParse(input, expr);
}

We can read the parser in this way: a double followed by zero or more elements of the expression made by a comma followed by a double.
Actually, we didn't have to cast explicitely the character comma to the parser for it, since the operator >>, having on its right an element of type parser, is smart enough to infer the conversion on its own. So, we could have written:
auto expr = boost::spirit::qi::double_ >> *(',' >> boost::spirit::qi::double_);
But it has been a good way to show the built-in char_ parser.

Being this parsing a bit more interesting, I'd suggest you to write a lot of test cases, to check if your expectations match the actual parsing behaviour. Here is a few of them:
TEST(BSParseCSDList, Empty)
{
std::string input;
EXPECT_FALSE(bsParseCSDList(input));
}

TEST(BSParseCSDList, Double)
{
std::string input("1.21");
EXPECT_TRUE(bsParseCSDList(input));
}

TEST(BSParseCSDList, DoubleDouble)
{
std::string input("1.21,7.44");
EXPECT_TRUE(bsParseCSDList(input));
}

TEST(BSParseCSDList, DoubleDouble2)
{
std::string input("1.21, 7.44");
EXPECT_TRUE(bsParseCSDList(input));
}

TEST(BSParseCSDList, DoubleDoubleBad)
{
std::string input("1.21 7.44");
EXPECT_FALSE(bsParseCSDList(input));
}

Go to the full post

Atoi with Spirit

The first example I found in the excellent Boost Spirit documentation is about using IQ (Spirit parser) to implement something like the standard C atoi() function, and Karma (Spirit generator) to do the same thing the other way round, as the non-standard itoa() function does.

I am tendentially a TDD guy, so I have written a few test cases for a couple of functions that I have derived from my reading to see in action how close the behavior is to the expected one. I spare you the list of tests I generated, just showing the first one (I use Google Test, if you wonder):
TEST(BoostSpiritAtoi, Simple)
{
   std::string s("42");
   EXPECT_EQ(std::atoi(s.c_str()), bsAtoi(s)); // 1
}
1. The expected result for a call to the Boost Spirit Atoi should be the same of a call to standard atoi.

For what I have seen, the document's authors left out (as a simple chore for the reader) only the skipping of leading white characters. So the code I have written for the atoi emulation is only a tad different from what you would find in the documentation:
int bsAtoi(const std::string& input)
{
   std::string::const_iterator beg = input.begin();
   while(beg != input.end() && std::isspace(*beg)) // 1
      ++beg;

   int value = 0; // 2
   boost::spirit::qi::parse(beg, input.end(), boost::spirit::int_, value); // 3
   return value;
}
1. Loop to skip all the possible leading white spaces. We won't care about trailing ones, since they are correctly managed by the Spirit parser - and I know what I am saying, I have written and checked a few specific test cases to verify it.
2. If we don't initialize the returned value and the parser doesn't have anything to do (empty string in input, for instance) we would get back a dirty value.
3. Parse with Spirit.

The itoa() emulation is even simpler:
std::string bsIota(int value)
{
   std::string output;
   boost::spirit::karma::generate(std::back_inserter(output), boost::spirit::int_, value); // 1
   return std::move(output); // 2
}
1. We pass to Karma the back insert iterator to a local string, so that it could put there the result of the generation from the input value we pass to generate().
2. We can save some execution time relying on the move copy ctor for std::string.

A friendly reader wondered why I originally used in (1) the verbose but bit more explicit formula
std::back_insert_iterator<std::string>(output)
instead of its sleeker inline redefinition
std::back_inserter(output)
Actually, I don't remember. And I guess he is right, and his suggestion makes the code more readable.

By the way, if it is not clear to you what an inserter is, you could search for other posts on this same blog talking about them. I guess you could start reading this couple: Using inserters has a few examples involving back, front, and a generic inserter. std::copy_if could give you some fun with an example that uses std::copy_if, a back inserter and even a lambda function in the same line (cool, isn't it?).

Go to the full post

std::array and boost::array

When developing in C++, using C-style array is often a bad idea. Better using std::vector, the STL container that replaces C-style array offering features and capabilities of a STL container. On the other side, a std::vector is designed to be a dynamic container, this is cool, but sometimes there is no need for it, and it costs some overhead that we could avoid.

That's the point of using std::array, defined in C++0x, or boost::array, if your compiler does not support it yet. If we know the array size, and it is not supposed to change, we'll use a std::array; if we want to let a chance of dynamically change the size, we'll use a std::vector.

The code I'm showing hereafter is exctracted from a few testcases I have wrote using the google test framework. But even if you don't know what I'm talking about, it should be all quite easy to understand, at least in its general sense.

The code is written referring to the standard implementation but it is easy to switch to the boost container changing just the namespace and the include.

Initialization.

No constructor is provided for std::array, we just provide the referring type and its size:
std::array<int, 4> ai; // 1.
EXPECT_EQ(4, ai.size()); // 2.
std::for_each(ai.begin(), ai.end(), [](int i){ EXPECT_NE(0, i); }); // 3.

1. A std::array of four int has been put on the stack.
2. It contains four elements
3. We expect no initialization, so the chances that an element of the array would be set to zero should be pratically zero.

No construtctors, we said, but a std::array could be initialized using the assignment syntax used also for c-array, with the caution that we should use a double bracket, since the real array is a just member of the class we are initializing:
std::array<int, 4> a2 = {{ 42, 12, 9, 0 }}; // 1.
EXPECT_EQ(0, a2[3]); // 2.

1. Four ints in the array, initialized as specified.
2. The last element, index 3, is expected to have value zero.

Double brackets are a nuisance, and they do not add any information to the code, so the compiler could do without them. Besides, if we put less values between the brackets, default values are assumed:
std::array<int, 4> a3 = { 42, 12, 9 }; // 1.
EXPECT_EQ(4, a3.size()); // 2.
EXPECT_EQ(0, a3[3]); // 3.

1. No boring double brackets, and it works just the same.
2. The size is four, even if I specified just three values.
3. The last element has been initialized using the default value, that means zero.

We could even initialize a std::array with an empty pair of brackets:
std::array<int, 4> a4 = { };
std::for_each(a4.begin(), a4.end(), [](int i){ EXPECT_EQ(0, i); }); // 1.

1. An all zero element array is expected.

Assigning a value to all the elements.

We have just seen a practical way to initialize an std::array with all zero. But we need an alternative, for at least a couple of cases. Firstly, if our std::array is a member variable of a class we can't use that initializator. Secondly, we could need to set all the element of an array to a value different from zero. We can use indifferently two functions, that are actually synonym, assign() and fill():
std::array<int, 4> ai;
ai.assign(7); // 1.
std::for_each(ai.begin(), ai.end(), [](int i){ EXPECT_EQ(7, i); });

ai.fill(42); // 2.
std::for_each(ai.begin(), ai.end(), [](int i){ EXPECT_EQ(42, i); });

1. All the elements of the array are set to seven.
2. Same, but to fortytwo.

Swapping.

Given two arrays, same size, we could swap their content using a specific function:
std::array<int, 4> ai = { 42, 12, 9, 32 };
std::array<int, 4> a2 = { 24, 21, 7 };

EXPECT_EQ(42, ai[0]);
EXPECT_EQ(24, a2[0]);

a2.swap(ai);

EXPECT_EQ(24, ai[0]);
EXPECT_EQ(42, a2[0]);

Not much more to say on this function, I guess.

Getters and setters.

We can gain read and write access to a single element in a std::array in a number of way. Probably the most natural one is using the square brackets operator [], expecially if you have a background as a C programmer. It has the same limitations of its C counterpart: there is no check. It is just programmer responsibility avoid doing silly things like accessing elements outside the effective range.

The at() function works just like the [] operator, but it is not so trustful, and throws a std::out_of_range exception if it must.

And we have a couple of specialized functions to get the element at the beginning, front(), at at the end, back(), of the array:

std::array<int, 4> ai = { 42, 12, 9 };

EXPECT_EQ(0, ai.back()); // 1.
ai.back() = 33; // 2.
EXPECT_EQ(33, ai.back());

EXPECT_EQ(42, ai.front()); // 3.
ai.front() = 82;
EXPECT_EQ(82, ai.front());

EXPECT_EQ(12, ai.at(1));
EXPECT_THROW(ai.at(99), std::out_of_range); // 4.

1. Here we use back() to access the last array element to read it.
2. And here we actually change the value contained in the last element array.
3. front() works exactely as back(), as one would expect.
4. Our array does not have 99 elements, so trying to access that element would result in an exception.

Raw array.

When we need to acces the real stuff, usually because we should rely on some legacy code, we could extract the C-array in our std::array by calling the data() function:
std::array<int, 4> ai = { 42, 12, 9 };
int* ca = ai.data(); // 1.
for(size_t i = 0; i < ai.size(); ++i) // 2.
EXPECT_EQ(ca[i], ai[i]);

ca[3] = 99; // 3.
EXPECT_EQ(99, ai[3]);

1. ca now points to the C-array in our std::array.
2. We expect that we access the same stuff using both ca and ai.
3. And we expect that our changes made following the raw pointer result in changing the data as seen by std::array.

If we are using the Boost implementation, we also have access to another function, c_array(), that is merely a synonym of data():
boost::array<int, 4> ai = { 42, 12, 9 };

int* ca = ai.c_array();
for(size_t i = 0; i < ai.size(); ++i)
EXPECT_EQ(ca[i], ai[i]);

ca[3] = 99;
EXPECT_EQ(99, ai[3]);

Besides, the raw array is exposed as a public data member in the std::array (and in boost::array too), so we could be tempted to write the same code accessing it directly. Bad idea:
boost::array<int, 4> ai = { 42, 12, 9 };
ai.elems[3] = 99; // Boost - ???
//ai._Elems[3] = 99; // VC - ???
EXPECT_EQ(99, ai[3]);

Not a good a idea from an Object-Oriented point of view, since data should not be public if there is not a vary good reason that force you to to otherwise (here: having a way of initialize the raw array). Even though the data member is exposed, we should not access it directly, and here the reason is portability. Its name is not standardized, so any implementation could choose any fancy name.

Size.

Once created, a std::array won't change its size for all its life. Nevertheless we have a bunch of functions that are useful just from the point of view of homogeneity with the other STL containers:
std::array<int, 4> ai = { 42, 12, 9 };
EXPECT_FALSE(ai.empty()); // 1.
EXPECT_EQ(4, ai.size()); // 2.
EXPECT_EQ(ai.size(), ai.max_size()); // 3.

std::array<int, 0> a2; // 4.
EXPECT_TRUE(a2.empty());
EXPECT_EQ(0, a2.max_size());

1. empty() returns true if the array size is zero.
2. size() returns the actual size of the array.
3. max_size() is obviously the same of size().
4. Here is how to create a (pretty unuseful) zero size std::array.

Go to the full post

Multithreading with ASIO

ASIO could be used to make multithreading easier to be implemented and maintained. Think for instance to an application that should run a number of task in sequential or concurrent way, accordingly to a parameter that is passed from the argument line representing the number of thread to be used.

Implementing that with ASIO is pretty easy.

First of all, I wrote a couple of silly functions that represent the tasks my application should perform:
namespace
{
  boost::mutex mio; // 1

  void logMsg(char* reason, int i)
  {
    boost::lock_guard<boost::mutex> lock(mio); // 2.
    std::cout << reason << " for " << i << " at " << std::time(0) << std::endl;
  }

  void jobOne(int secs) // 3.
  {
    logMsg("Start jobOne", secs);
    boost::this_thread::sleep(boost::posix_time::millisec(1000 * secs));
    logMsg("End jobOne", secs);
  }

  void jobTwo(int millisecs)
  {
    logMsg("Start jobTwo", millisecs);
    boost::this_thread::sleep(boost::posix_time::millisec(millisecs));
    logMsg("End jobTwo", millisecs);
  }
}
1. A mutex is required because there could be more threads competing on a shared resource, in this case the output console where we'll print some log messages.
2. Here we use lock_guard to rule synchronize the access, so that the lock on the mutex is acquired entering the function and released on exit.
3. JobOne is actually just about sleeping for a few seconds.
4. JobTwo is not much different from jobOne.

And this could be an ASIO implementation for the given requirement:
void run(int tNumber) // 1
{
  boost::asio::io_service svc; // 2
  boost::asio::io_service::work work(svc); // 3
  boost::thread_group threads;

  for(int i = 0; i < tNumber; ++i) // 4
    threads.create_thread(std::bind(&boost::asio::io_service::run, &svc));

  svc.post(std::bind(jobOne, 2)); // 5
  svc.post(std::bind(jobOne, 1));
  svc.post(std::bind(jobTwo, 500));

  svc.stop(); // 6
  threads.join_all(); // 7
}
1. This function has to be called passing the number of threads we want to use.
2. As usual, io_service is the key element in ASIO code.
3. Try to comment this line and see what happens. In my case, the behavior becomes unpredictable, and that should be what you get too, since if you don't use a work object the run() function should terminate if there is nothing to do, and it could happen, given the way the code is written, that a thread could die before seeing anything at all to do. [See the comments for more on this point. As Stefan points out, if we don't use an io_service::work object, stopping the io_service object as here it is done in (6) is not a smart thing to do.]
4. We create as many thread as specified in the passed parameter. Any of these threads execute the run function on the IO service object.
5. We use post() to put in the execution queue for the IO service object any task we want to run.
6. Then we signal to the IO service object that there is nothing more to do.
7. And we wait for the threads execution to complete.

In this simple case, a work object is not actually mandatory. We could get rid of it inverting how the code is written. Moving (4), the loop for creating new threads for running the IO service, after (5), the block that creates the jobs to be executed, we will get that no threads would risk to see no job available, and so terminating before expected. But it is usually not a good idea relying on this behavior for a more general situation. [See a more elegant and robust solution and read the comment by Stefan here below for details]

Go to the full post