Theron - C++ concurrency library

Getting started with Theron

This guide is an introduction to downloading Theron and setting it up to build your first Theron-based application.

1. Download Theron

Download the latest version here, and save it to your disk. Unzip the downloaded zip file into your source code depot - it creates a folder named Theron-something, where something is the version, and a bunch of subfolders within that. The root folder contains a makefile and a Visual Studio solution called Theron.sln.

2. Build Theron

Building Theron is necessary to compile the libraries you'll link against in your own applications. The build also compiles and links the tests, samples and benchmarks included with Theron. The details of how Theron is built depend on your choices of platform and thread library.

Theron can be used on a variety of different platforms, usually without major code changes. The main supported platforms are GCC under Linux and Visual Studio under Windows, and it's those that we talk about here.

The download includes a simple makefile and a Visual Studio 2010 solution. These should serve as good starting points for most users. Even if you plan eventually to integrate Theron into your own build, it may be best to start simple by building the provided makefile or solution.

  • Build Theron with GCC using the included makefile This is the option of choice for Linux users, and is also the best starting point for other platforms such as Mac OS. It involves using the included makefile to build Theron using some version of the well-known make utility.
  • Build Theron with Visual Studio using the included solution file This option is clearly only for users of Visual Studio in Windows. It involves loading the included solution file Theron.sln into the Visual Studio IDE, selecting a configuration and platform, and then building it using Build Solution in the Build menu.

Theron needs a thread library for its internal threading operations. In Visual Studio builds, it always uses Windows threads and so there is little to configure. In GCC builds, you can specify the configuration using optional make arguments. The download includes support for several different thread libraries including std::thread, Boost.Thread and Windows threads. See the section on building with GCC for details. For an overview of the thread library support in Theron see here.

3. Test the build

Theron should generally build without errors or warnings, although it's hard to guarantee this on all possible platforms. Once it's built, you can test that everything built okay by running the included tests and samples. By default the binaries are all built into the /Bin subfolder, which is initially empty.

Try running the unit tests and samples. The tests should reliably all pass without hanging -- otherwise something is wrong. By default the tests run silently and all the tests are run just once. You can change this with optional -verbose and -count flags.

4. Build Theron into your own application

Once the Theron libraries have been built, you're ready to start using them in your own application. The easiest way to start is to just add your own projects to the included makefile or solution, copying one of the existing samples as a starting point. But eventually you'll want to pull the Theron headers and libraries into your own, separate, build - and maybe even build the Theron libraries as part of that build.

Mainly this comes down to adding the Theron include path and library path to your own project. The headers are in the Include subfolder. With that path added to your include paths, you can include Theron headers like this:


#include <Theron/Theron.h>

The included build scripts build the Theron library (there's only one) into the Lib folder. The release library is called libtheron.a in makefile builds, and Theron.lib in Visual Studio builds. The debug library is called libtherond.a in makefile builds, and Therond.lib (note the extra 'd').

Lastly, here's a trivial application you can compile to test your build:


#include <Theron/Theron.h>

class Actor : public Theron::Actor
{
public:

    explicit Actor(Theron::Framework &framework) : Theron::Actor(framework)
    {
        RegisterHandler(this, &Actor::Handler);
    }

private:

    void Handler(const int &message, const Theron::Address from)
    {
        Send(message, from);
    }
};

int main()
{
    Theron::Receiver receiver;
    Theron::Framework framework;
    Actor actor(framework);

    framework.Send(int(0), receiver.GetAddress(), actor.GetAddress());

    receiver.Wait();
}

5. Read the tutoral

Once you're up and building, you're in a position to take on the samples. Use the online tutorial as a guide to the samples, or just read it by itself. It'll waft you gently through the basics of writing Theron-based apps.