# Lock-free triple buffer

I have a single producer and single consumer, and the producer never stops, but the consumer might not keep up. There's no need to consume every item, as long as we always access the most-recently produced item, and never process an item twice. In other words, we should drop items if the consumer isn't keeping up, but wait for the producer if it is.

#ifndef TRIPLE_BUFFER_HPP
#define TRIPLE_BUFFER_HPP

#include <atomic>
#include <chrono>
#include <condition_variable>
#include <mutex>

template<typename T>
class triple_buffer
{
// the actual buffer
T buffer[3] = {};

// the roles the buffers currently have
// read and write buffers are private to each side
// the available buffer is passed between them
T* writebuffer = &buffer[1];
std::atomic<T*> available = &buffer[2];

// When the reader catches up, it needs to wait for writer (slow path only)

public:

// Writer interface

// Writer has ownership of this buffer (this function never blocks).
T *get_write_buffer()
{
return writebuffer;
}

// Writer releases ownership of its buffer.
void set_write_complete()
{
// give back the write buffer
auto *written = writebuffer;
writebuffer = available.exchange(writebuffer);
// mark it as written
}

// Reader gets ownership of the buffer, until the next call of
{
auto const timeout_time = std::chrono::steady_clock::now() + timeout;

// get the written buffer, waiting if necessary
// it could be the available buffer
// yes, that's it
}
// else we need to wait for writer
b = nullptr;
auto test = [this,&b]{ b = next_read_buf.exchange(nullptr); return b; };
return nullptr;
}
}

}

// The unit test helper is enabled only if <gtest.h> is included before this header.
// It's not available (or necessary) in production code.
#ifdef TEST
// N.B. not thread-safe - only call this when reader and writer are idle
void test_invariant(const char *file, int line) const
{
const std::set<const T*> buffers{&buffer[0], &buffer[1], &buffer[2]};
const std::set<const T*> roles{readbuffer, available, writebuffer};
auto const fail = buffers != roles
if (fail) {
auto name = [this](const T *slot){
if (slot == &buffer[0]) { return "buffer[0]"; }
if (slot == &buffer[1]) { return "buffer[1]"; }
if (slot == &buffer[2]) { return "buffer[2]"; }
if (slot == nullptr) { return "(null)"; }
return "(invalid)";
};
"Buffer/role mismatch:\n"
"Buffers = " << &buffer[0] << ", " << &buffer[1] << ", " << &buffer[2] << "\n"
"Available = " << available  << " = "<< name(available) << "\n"
"Write = " << writebuffer << " = " << name(writebuffer) << "\n"
}
}
#endif
};

#endif // TRIPLE_BUFFER_HPP


I created this with help from a set of unit tests:

#include <gtest/gtest.h>

#include <triple-buffer.hpp>

#include <set>

#define EXPECT_INVARIANT(obj) (obj.test_invariant(__FILE__, __LINE__))

{
triple_buffer<int> buffer;
EXPECT_INVARIANT(buffer);
EXPECT_INVARIANT(buffer);
}

{
triple_buffer<int> buffer;
auto *write0 = buffer.get_write_buffer();
EXPECT_INVARIANT(buffer);
EXPECT_NE(write0, nullptr);
EXPECT_INVARIANT(buffer);

buffer.set_write_complete();
EXPECT_INVARIANT(buffer);
// having written, we can read
EXPECT_INVARIANT(buffer);

EXPECT_INVARIANT(buffer);
}

{
triple_buffer<int> buffer;
auto *write0 = buffer.get_write_buffer();
EXPECT_NE(write0, nullptr);
buffer.set_write_complete();

auto *write1 = buffer.get_write_buffer();
EXPECT_NE(write1, nullptr);
EXPECT_NE(write1, write0);
buffer.set_write_complete();

}

{
triple_buffer<int> buffer;
auto *write0 = buffer.get_write_buffer();
EXPECT_NE(write0, nullptr);
buffer.set_write_complete();

auto *write1 = buffer.get_write_buffer();
EXPECT_NE(write1, nullptr);
EXPECT_NE(write1, write0);
buffer.set_write_complete();

auto *write2 = buffer.get_write_buffer();
EXPECT_NE(write2, nullptr);
EXPECT_NE(write2, write1);
buffer.set_write_complete();

}

{
triple_buffer<int> buffer;
auto *write0 = buffer.get_write_buffer();
EXPECT_NE(write0, nullptr);
buffer.set_write_complete();

auto *write1 = buffer.get_write_buffer();
EXPECT_NE(write1, nullptr);
EXPECT_NE(write1, write0);
buffer.set_write_complete();

auto *write2 = buffer.get_write_buffer();
EXPECT_NE(write2, nullptr);
EXPECT_NE(write2, write1);
buffer.set_write_complete();

auto *write3 = buffer.get_write_buffer();
EXPECT_EQ(write3, write1);  // we should be overwriting the old unread value
buffer.set_write_complete();

}

{
triple_buffer<int> buffer;
auto *write0 = buffer.get_write_buffer();
EXPECT_NE(write0, nullptr);
buffer.set_write_complete();

auto *write1 = buffer.get_write_buffer();

// read should get complete buffer

buffer.set_write_complete();
auto *write2 = buffer.get_write_buffer();
EXPECT_NE(write2, nullptr);
EXPECT_NE(write2, write1);

buffer.set_write_complete();
}


Obviously, the unit tests are limited, being single threaded. In particular, they don't cover the wait_until() call or provoke any races. I feel I should probably create some module tests that can be slower than unit tests (I consider 1ms runtime the absolute upper limit for a unit-test), but don't have any experience using slower tests like that.

Anyway, my main concerns with the code (both the class and its tests) are:

1. Correctness. I believe it's correct in all cases, but concurrent code is notoriously hard to fully reason about, and I'd appreciate any insight into what I've missed.
2. Readability. Can this be understood and modified by someone else (future-me, in particular)?
3. Given I know there's only one reader, do I really need read_queue_mutex to be a member, or can I get away with instantiating a new one in each get_read_buffer() call? If so, should I?

Correctness. I believe it's correct in all cases, but concurrent code is notoriously hard to fully reason about, and I'd appreciate any insight into what I've missed.

It don't see any correctness issues.

Readbility. Can this be understood and modified by someone else (future-me, in particular)?

Lock-free code is always hard to follow. I think the get_write_buffer() and set_write_complete() functions are relatively easy to understand. The hardest to follow is get_read_buffer(). I would explain the invariants in the code:

• readbuffer is always owned by the consumer
• writebuffer is always owned by the producer
• available is never owned by either
• you can atomically exchange read/writebuffer with available without breaking the above invariants

And then also explain the trick: next_read_buf is set by the producer after it is finished with the buffer, and it also swaps writebuffer and available, after which next_read_buf == available. The consumer can atomically take over available in this case.

The wait is necessary in two cases: next_read_buf is nullptr (producer didn't produce anything yet since last consume), or if it just exchanged available and writebuffer, but had not written to next_read_buf yet.

Given I know there's only one reader, do I really need read_queue_mutex to be a member, or can I get away with instantiating a new one in each get_read_buffer() call? If so, should I?

You can instantiate a new one in each call. Either you pay the small price of instantiating a new std::mutex every call, or you pay the price of keeping a std::mutex around all the time. I don't think it matters much for performance. I would keep it like it is, so that the mutex and condition variable are kept close together in the source code.

This problem is solved in C++20 with std::atomic_wait().

# Consider using RAII to convey buffer ownership

A producer has to do two steps: get a pointer to a buffer to write to, and then release that buffer when it is done. That sounds like a job for RAII. Similar to std::lock_guard, consider adding a way to get a handle for the write buffer that will automatically do set_write_complete() when its lifetime ends. You could even do the same for the read buffer for symmetry's sake.

• Just the kind of review I was hoping for - thank you. I didn't know std::atomic_wait() - looks useful, but it's a shame there isn't a version with a timeout (I need to poll occasionally to check whether the program wants to terminate). I remember thinking about an RAII interface early on, but never followed up on that - thanks for reminding me to consider that again. Apr 24, 2021 at 17:14
• Hm, good point about the timeout. But if it is for checking if the program needs to terminate, don't! The usual way to avoid polling is to enqueue a new item which in some way signals that the consumer should immediately quit. Or in this case, you could for example have a dummy T that you point next_read_buf to (for example, use &buffer[3]), and you can check for that in the slow path in get_read_buffer(). Apr 24, 2021 at 17:35
• Good suggestions for the termination handler. I think I'm still in a position to change that and incorporate your advice. My items have quite a few members already (and I plan to add some to track what proportion of items get dropped, and how long the rest spend waiting to be read) so adding a flag shouldn't be a problem. Apr 24, 2021 at 17:48