Protothreads and C++

Part of my day job is embedded programming, and recently I’ve discovered Adam Dunkels’ lovely invention: protothreads. He calls them lightweight, stackless threads in C. And that they are.

What protothreads give you is the ability to write procedural, thread-style code, but without the overhead of real threads. The kind of thing embedded programmers normally use switch state machines for.

The other alternative is full-blown threads, but real threads certainly have their drawbacks. They each need their own stack, for one — and that’s often nasty in embedded systems, where you might only have 2 KB of RAM total. There’s the performance hit of context switching. There’s having to worry about sharing between threads, locking, etc.

Enter protothreads.

One of the cool things about them is that, behind the scenes, they break all the conventions (but not the commandments). Use of the legendary Duff’s device, macros that open braces but don’t close them … but they work, they’re fast and portable, and they give you pseudo-threads almost for free.

Because of how they work — perhaps it’s the same for any neat tool — there are a few gotchas:

• You can use locals, but their values won’t be remembered across waits (you have to use statics for that).
• You’ve got to put all your “state change code” in a single function.
• And you can’t have a switch of your own spanning the use of the wait macros.

You’ll want to read more about them and see some examples on Adam Dunkels’ website.

Protothreads in C++

But what about this C++ thing? Well, C++ is a more or less a superset of C, so protothreads will work as-is. But if we take C and sprinkle in a dash of ++, we can make them even tastier:

• You can make a Protothread class, so you don’t need to pass the struct pt* around everywhere.
• You can use instance variables where you might have used statics, making your protothreads easy to multi-instance.
• You can write classes derived from Protothread that add helper variables and macros to read and wait for timers, specific I/O ports, etc.

“Okay, so show us an example.” Fair call.

Below is a C++-style protothread that implements a simple packet protocol. Each packet has a sync byte, a length byte, n data bytes, and a checksum byte. Packets are only processed if they’re good and complete:

bool UartThread::Run()
{
    PT_BEGIN();

    while (true) {
        // wait for sync byte
        PT_WAIT_UNTIL(ReadByte(ch));
        if (ch == Sync) {
            // read length byte, ensure packet not too big
            PT_WAIT_UNTIL(ReadByte(ch));
            len = ch;
            if (len <= MaxLength) {
                // read n data bytes
                for (i = 0; i < len; i++) {
                    PT_WAIT_UNTIL(ReadByte(ch));
                    data[i] = ch;
                }
                // read checksum, dispatch packet if valid
                PT_WAIT_UNTIL(ReadByte(ch));
                if (ValidChecksum(data, len, ch))
                    Dispatch(data, len);
            }
        }
    }

    PT_END();
}

Not bad, eh? Even with comments it’s much shorter and sweeter than the equivalent state machine version (which, incidentally, is pretty much what the protothread macros expand to):

bool UartThread::Run()
{
    while (true) {
        switch (state) {
        case StateSync:
            if (!ReadByte(ch))
                return true;
            if (ch != Sync)
                break;
            state = StateLength;

        case StateLength:
            if (!ReadByte(ch))
                return true;
            len = ch;
            if (len > MaxLength) {
                state = StateSync;
                break;
            }
            i = 0;
            state = StateData;

        case StateData:
            while (i < len) {
                if (!ReadByte(ch))
                    return true;
                data[i] = ch;
                i++;
            }
            state = StateChecksum;

        case StateChecksum:
            if (!ReadByte(ch))
                return true;
            if (ValidChecksum(data, len, ch))
                Dispatch(data, len);
            state = StateSync;
        }
    }
}

So there you go. I know which version I’d rather write and maintain.

Feel free to use the Protothread.h header file I put together from Adam Dunkels’ C version — it should have all you need to get started. I’ve left a “protothread scheduler” as an exerciser for the reader, as it would be both simple and application-dependent.

Just a final word: I’m not suggesting protothreads are a replacement for threads — they’re not. But when you need the appearance of threads, or you’re dealing with embedded micros and don’t have screeds of RAM, give them a try.

Chris Woods has also implemented a version of protothreads in C++, but he’s taken a different approach for the Symbian OS.

25 July 2008 by Ben    12 comments

12 comments and pings (oldest first)

class LEDFlasher : public Protothread
{
public:
    virtual bool Run();

private:
    ExpiryTimer _timer;
    uintf _i;
};

bool LEDFlasher::Run()
{
    PT_BEGIN();

    for (_i = 0; _i < 10; _i++)
    {
        SetLED(true);
        _timer.Start(250);
        PT_WAIT_UNTIL(_timer.Expired());

        SetLED(false);
        _timer.Start(750);
        PT_WAIT_UNTIL(_timer.Expired());
    }

    PT_END();
}

int main()
{
    LEDFlasher flasher1;
    LEDFlasher flasher2;

    while (flasher1.IsRunning() || flasher2.IsRunning()) {
        flasher1.Run();
        flasher2.Run();
    }
    return 0;
}

Add a comment