CodingTipsAndPitfalls.md

Coding tips and common coding pitfalls

Prefer shared_ptrs

You should prefer shared_ptrs over raw pointers because they make memory leaks and memory errors less likely. There are only very limited cases in which raw pointers are justified, e.g. optimizations in very hot code paths.

Unexpected shared_ptr invalidation

Suppose you have a function which takes a reference to a shared_ptr, like this:

void foo(const shared_ptr<Client> &client) {
    performNetworking();
    log(client->getAddress());
}

You might think that client is never going to be destroyed during the scope of the function, right? Wrong. If client came from a non-local variable, and your function calls another function (perhaps indirectly) which resets that variable, then client is going to be invalidated. Consider a contrived example like this:

static shared_ptr<Client> client;

void performNetworking() {
    if (write(...) == -1) {
        // An error occurred, disconnect client.
        client.reset();
    }
}

More realistically, this kind of bug is likely to occur if foo() calls some function which invokes a user-defined callback, which unreferences the original object under some conditions. Thus, if your code might call an arbitrary user-defined function, you should increase the reference count locally:

void foo(const shared_ptr<Client> &client) {
    shared_ptr<Client> extraReference = client;
    performNetworking();
    log(client->getAddress());
}

A variant of this pitfall is documented under "Event loop callbacks".

Event loop callbacks

Obtain extra shared_ptr reference on this

If your event loop callback ever calls user-defined functions, either explicitly or implicitly, you should obtain a shared_ptr to your this object. This is because the user-defined function could call something that would free your object. The problem is documented in detail in "Unexpected shared_ptr invalidation".

Your class should derive from boost::enable_shared_from_this to make it easy for you to obtain a shared_ptr to yourself.

    void callback(ev::io &io, int revents) {
        shared_ptr<Foo> extraReference = shared_from_this();
        ...
    }

Exceptions

Event loop callbacks should catch expected exceptions. Letting an exception pass will crash the program. When system call failure simulation is turned on, the code can throw arbitrary SystemExceptions, so beware of those.

Thread interruption and RAII destructors

When using thread interruption, make sure that RAII destructors are non-interruptable. If your code is interrupted and then a thread_interrupted is thrown, make sure that RAII destructors don't check for the interruption flag and then throw thread_interrupted again. This not only fails to clean things up properly, but also confuses the exception system, resulting in strange errors such as "terminate called without an active exception".