Continuing on the topics I talked about at this year’s aKademy conference.

Most of the things I want to write here are not new to people who are immersed in C++ and follow the books/presentations by Alexandrescu, Sutter, and others. But, I’ve found that in our Qt-sub-culture, it is often not the case.

Qt is very good at hiding the ugly parts of C++, but at the same time, it sometimes hides too much.

Memory safety

One of the first things you learn in Qt is about the object trees and ownership where the parent obect conviniently destroys its children on its destruction.

IMO, this is one of the nicest features of Qt. But, sometimes, it tends to provide a sense of false security. As trivial example, imagine the following:

QThread *thread = new QThreadDerivedClass(this);
thread->start();

It looks nice - we are creating a new object, we pass it a parent (this), so we do not need to worry about its destruction ourselves. The issue is that the parent is often a long-lived object like a QCoreApplication or a main window. This tends to end up in the thread object not being destroyed until the application has been terminated.

Now imagine that the above object is an image cache, and you’ll have a quite substantial memory leak.

The parent-child ownership is a silver bullet in a lot of cases, but not all.

What does a pointer mean?

So, lets return to the topic at hand - API design. One of the biggest problems when using a new library is what the following declaration means:

SomeType * someMethod();

Namely, the question here is what does the ’SomeType *’ mean. It can mean quite a few things:

• (static) singleton instance
• should be disposed by the user
• creator-owned, creator disposes of it
• an optional value? (for example, parsing a number from a string could return a null if parsing failed)
• position in an array? (this one is rarely used nowadays, we have iterators for that case)

The problem here is deducing who owns the returned object, and are we guaranteed to get a non-null result at all. It can not be deduced without reading the documentation, and it could and should be.

1. Singletons

Since a singleton should be always present, there is really no point in making it a pointer at all. Implementing a proper singleton should be as easy as:

SomeType & instance()
{
    static SomeType s_instance;
    return s_instance;
}

It is thread-safe (in C++11), its declaration clearly states that it returns a non-null object, and an object with a long lifetime.

2. Factories

The next are the factory functions that return an instance of the object whose owner should be the callee, and the callee is responsible for its destruction:

std::unique_ptr<SomeType> createObject(...);

Even if the callee forgets to save the returned value, nothing will be leaked.

3. Caches, ref-counted singletons, etc.

When we have a function that returns something that can be destroyed at any time, or that should be destroyed only after everyone stops using it, we can simply write

std::shared_ptr<SomeType> getObject(...);
// or
std::weak_ptr<SomeType> getObject(...);

The first one tells the callee that the object will exist for as long as he wants to use it, but without the guarantee that it will be destroyed immediately after.

While the later says that it has been given an object that could go away at any point in time.

4. Optional result values

The last use-case is the most problematic one. Not because it has not been solved, but rather because the necessary class has not yet been provided in C++.

When it becomes the part of the standard, it will look something like this:

std::optional<SomeType> parseTheType(...);

For the time being, you could use boost::optional, pair<bool, SomeType> and similar.

If you wanted to give the failure error as well, without resorting to throwing exceptions all over the place, my advice is to go and watch Alexandrescu’s talk on “Systematic error handling in C++”.

Exception safety

Now, after we saw what can be done to the API to make the user’s life easier when it comes to memory management, just a very short note about the exception safety.

There is a reason why std::stack does not have a method pop that returns a value, but has the separated top and pop. This is, again, one of the things that should be known to most c++ developers, yet sometimes you can even find some c++ book authors that take jabs at the standard committee for making it that way, and not going for the more convenient API.

I suggest everyone to look at some writings about this - the issue itself gives a nice overview of things to watch out for when designing API which should behave well in the exception-enabled environment.

I’ve been keeping a set of scripts to keep parallel builds of a few projects, to be able to test whether everything behaves well on older compilers. It is also nice to compile things with clang while developing since it usually provides nicer error messages compared to gcc, even if might be slower or generate slower code.

The main problem is that the setup was not really scalable. Adding new build profiles, or projects was not as easy as it ought to be.

Enter kdesrc-build-extra

kdesrc-build-extra is a simple tool that creates profile-based alternative builds to those created by kdesrc-build. It does not do it for all projects, but only for those that you choose.

It allows you to create a few profiles, and specify which projects you want built with each of them. So, for example, you can keep parallel builds of plasma-workspace with gcc 4.5 and the latest clang, while having a static checker like clang-analyze for plasma-framework.

The example configuration file comes with the program. The format is the same as the one used by kdesrc-buildrc, just with a few custom fields.

This is one of the profiles from the provided example configuration file:

# Build profile for building with the clang compiler
build-profile clang-build

  # Prefix to use for building this profile
  build-dir    /opt/kf5/build-clang/

  # [optional] Where to install the binaries from this profile
  # install-dir /opt/kf5/usr-clang/

  # C++ compiler executable
  cxx-compiler /usr/bin/clang++

  # C compiler executable
  c-compiler   /usr/bin/clang

  # Which options to remove from the kdesrc-build setup
  # when building this profile.
  # Parameters covered by the above setting values are
  # automatically removed.
  cmake-options-remove -DUSE_COMPILER_HIDDEN_VISIBILITY \
                       -DKDE4_BUILD_TESTS \
                       -DBUILD_TESTING

  # What should we add to the parameter list?
  cmake-options-add    -DUSE_COMPILER_HIDDEN_VISIBILITY=0

  # Which projects do you want to build using this profile
  projects kactivities plasma-framework

end build-profile

Installation

Now comes a bit weird part. Since these kinds of scripts in KDE tend to cover all programming languages in existence - perl, ruby, python and similar, I decided to go over the edge and do this in Haskell.

Thanks to Haskell’s package manager, the installation is quite simple.

cabal update
cabal install kdesrc-build-extra
cp ~/.cabal/bin/kdesrc-build-extra /path/to/your/kf5/sources

(you just need to install cabal and ghc before doing that)

Usage

Copy the kdesrc-build-extrarc-example file into the KF5 sources directory, edit it to fit your setup, and that is it.

First of all, this post is not meant to criticize Qt in any way, just to raise some thinking points for people who create libraries.

After my talk at aKademy 2014, I’ve decided to start a short series of blog posts about some considerations to be had when designing public API and overall practices to make your code safer and cleaner.

API Design

When we are thinking about the API of a library we are crafting, we usually tend to think only about how easy it will be for the user to use it. And I’d say that Qt is doing very well in that regard.

The problem is that the API design should not be only about that.

When crafting code, we usually ballance between keeping it readable by others, making it execute as fast as you can, to use as less memory as posible etc.

API design should be the same. Although, in this case, you can give a greater priority to the readability, but not by completely sacrificing the other parts.

A small example

A nice example of this sacrifice can be seen when comparing QTextStream::readLine to std::getline.

// API shortened to look prettier
QString QTextStream::readLine();
std::istream& getline(std::istream &input,
                      std::string &line);

The Qt version looks much nicer - it reads a line, and returns it. It can not be any simpler.

The STL version, on the other hand, returns the (rest of the) stream after the line is read, and it returns the actual line through the out argument. Is there anyone who actually likes the out arguments?

The benefit of this is that you can do a if(std::getline(:::)) and get whether the stream is still valid, which is useful sometimes. But, still, it looks as a harder function to use than the one from QTextStream.

Things start to look a bit different once you start thinking about the most common use case for using a function that returns a line.

// taken out of the QTextStream documentation
QTextStream stream(:::);
QString line;
do {
    line = stream.readLine();
    // do something
} while (!line.isNull());

The equivalent code using the function from the STL would be something like this:

std::ifstream stream(:::);
std::string line;
while (std::getline(stream, line)) {
    // do something
}

After seing the examples, it is a little bit hard to mark the QTextStream::readLine as the clear winner when the ease-of-use is concerned.

Measuring the speed

But, the point of this post is not to talk about that.

The point is to show that the API design has influcence on the other aspects, and not only on readability. The nice API of Qt comes with a significant performance penalty.

I’ve just tested the previous code snippets on a text file that has somewhere around 56000 lines. Each line of the file was longer than 50 characters to exclude the possibility for the libraries to use the short-string optimizations.

The results were measured using the clock() function in the ctime header (start_clock = clock(); … clock() - start_clock), and the tests were repeated quite a few times:

* Qt code took ~41000 // QString
* Qt code took ~30500 // edit: QByteArray
* STL code took ~8700

The STL version is almost 5 times faster (edit: 3.5 times compared to QByteArray version).

And it is not because Qt’s implementation is slow or anything. It is mainly because of the API design.

Why is that?

I’ll write the answer below in the comments section to allow you to think about what could be the issue here.

edit: Added QIODevice/QByteArray to the above mix, as suggested by csslayer.

Introducing ottens.js inspired by Kevin’s great talk at aKademy script that does to your web page what should have been done a long time ago. Just call the function when your page has been loaded.

function ottensize() {
    var html = document.body.innerHTML;
    html = html.replace('hacking', 'crafting');
    html = html.replace('hacked', 'crafted');

    document.body.innerHTML = html;
}

If you like to keep your project-related files on your desktop for easy access, you might have kept links to them in different folders which you placed in a folder view.

Now, it is much easier, just link them to the activity they belong to, and set the folder view to display it.