DEV Community: Matthew Faithfull

Code Sfumato

Matthew Faithfull — Sat, 08 Aug 2026 14:39:00 +0000

sfumato, (from Italian sfumare, “to tone down” or “to evaporate like smoke”), in painting or drawing, the fine shading that produces soft, imperceptible transitions between colours and tones. It is used most often in connection with the work of Leonardo da Vinci and his followers, who made subtle gradations, without lines or borders, from light to dark areas; the technique was used for a highly illusionistic rendering of facial features and for atmospheric effects - Britannica

Importantly for our purposes this technique was executed by the application of many, thin, translucent layers. Leonardo used paint but I believe the technique applies equally well to the art of software.

This might also be thought of as, 'The power of leaving things out', 'Applied ignorance', 'No code is the best code' or just another positive form of laziness. In software development laziness has long been known to be a good thing. So long it has it's rules.

Don't put off till tomorrow what you can put off till next week.
If at first you don't succeed, get someone else to do it for you.
Cheat at every opportunity.

The rules of laziness are, of course, terrible advice for life but very good advice for writing code.

That's it. That's what I wanted to say. Code Sfumato is the way I write my best code. I guess you want an example though ;<}

Code Sfumato in practice

Occasionally you find yourself needing to write things that really should just exist already and be completely obvious and standard. Then you write them and realize why they're not. One example of this is a simple stream buffer. Easy right?

How big should it be?
How do we put things in it?
How do we get them out again?
What should we do when it fills up?
What kinds of things does it need to hold?
How do we make sure it doesn't leek memory?
What if you can't get the answers to any of these questions?

Suddenly a simple problem that seemed like

auto buffer = std::array< my_struct, MAX_BUFFER_SIZE>();

would solve it, doesn't seem so simple any more. Unless it is in which case just use std::array and move on.

Let's put sfumato and the power of our ignorance to work, lazily of course.

Layer 1: An almost entirely ignorant (and harmless) buffer interface

class Buffer
{
/*solution goes here*/
};

We don't know what kind of things our buffer needs to contain but ultimately we know it's all 1's and 0's organised into bytes. So we don't really need to know what type the things are, just how many bytes it takes to store one of them.

class Buffer
{
protected:
    size_t m_unitSize;
};

We're making an assumption here that all the items in the buffer are the same size. Quite reasonable as, if we need different sized items, we can just use different buffers. However we should remember this assumption because it becomes the first rule for using Buffer. The unit size is fixed and therefore needs to be set before we use the Buffer, so on construction.

class Buffer
{
public:
    Buffer() : m_unitSize(1)
    {
    //...
    }

    Buffer(size_t unitSize /*...*/) : m_unitSize(unitSize)
    {
    //...
    }

    size_t Buffer::GetUnitSize() const
    {
        return m_unitSize;
    }
    
protected:
    size_t m_unitSize;
};

Default construction is nice to maintain if we can and a default unit size of 1 byte seems reasonable. We'll make retrieving the unit size part of the API so clients can easily check against it.
This look pretty solid and difficult to break. Of course in real development we'd have a growing set of unit tests to make sure and most of them would still fail at this point as we don't actually have a working buffer yet.
We know that at some point we're going to have to keep track of how many units of m_unitSize the Buffer owns. What our Capacity is. So let's do that.

class Buffer
{
public:
    Buffer() : m_unitSize(1)
    {
        SetCapacity((size_t)0);
    }

    Buffer(size_t unitSize, size_t itemCount) : 
        m_unitSize(unitSize)
    {
        SetCapacity(itemCount);
    }

    ~Buffer()
    {
        SetCapacity((size_t)0);
    }
    
    size_t GetUnitSize() const
    {
        return m_unitSize;
    }
    
    size_t Capacity(void) const
    {
        return m_allocationCount;
    }    
    
protected:

    virtual void SetCapacity(size_t itemCount)
    {
        m_allocationCount = itemCount;
    }    

    size_t m_unitSize;
    size_t m_allocationCount;//Track item count we have space for.
};

Well that was easy. We were lazy of course and didn't do any actual memory management. Maybe later.
This is still pretty safe and difficult to break. We should however handle copying and assignment as users of Buffer are bound to want to do such things.

class Buffer
{
public:
    Buffer() : m_unitSize(1)
    {
        SetCapacity(0);
    }

    Buffer(size_t unitSize, size_t itemCount) : 
        m_unitSize(unitSize)
    {
        SetCapacity(itemCount);
    }
    
    Buffer(const Buffer& src)
    {
        *this = src;
    }    

    ~Buffer()
    {
        SetCapacity((size_t)0);
    }
    
    Buffer& operator = (const Buffer& src)
    {
        if(&src != this)
        {
            SetUnitSize(src.GetUnitSize());
            SetCapacity(src.Capacity());
        }
        return *this;
    }
    
    size_t GetUnitSize() const
    {
        return m_unitSize;
    }
    
    size_t Capacity(void) const
    {
        return m_allocationCount;
    }    
    
protected:

    virtual void SetCapacity(size_t itemCount)
    {
        m_allocationCount = itemCount;
    }    

    void SetUnitSize(size_t unitSize)
    {
        if(m_allocationCount > 0 )
        {
            SetCapacity((size_t)0);
        }
        m_unitSize = unitSize;
    }
    
    size_t m_unitSize;
    size_t m_allocationCount;//Track item count we have space for.
};

Calling the assignment operator from the copy constructor is sometimes frowned on but we're being lazy so we'll do that and not duplicate code.
Notice we've added a SetUnitSize function which is now called on assignment when we already have a size and an allocation count. That's OK though because we set the allocation count back to zero if we change the unit size. Making sure to do so before we copy the allocation count from the source.
That was tricky. I'm glad we didn't complicate things with actual memory management.

There's no point allowing anyone to read our Buffer until it's been written to so we should add Writing next.
That's an important rule actually. Write always goes ahead of Read or Read always follows Write if you prefer. We can use that to keep our implementation simple.

We'll add two variables for writing. A write beginning and write end on the grounds that for the buffer to be useful we want to able to write to it multiple times without overwriting what's already there but we might want to write more than one item at a time. Given that no one is answering our questions on the requirements for this buffer today, we'll support single and multiple unit write. There's another usage rule. The client will need to tell us how many units it wants to write. This will generate the gap between write_begin and write_end until the client tells us how many units it actually wrote.

class Buffer
{
public:
    Buffer() : m_unitSize(1)
...
    Buffer(size_t unitSize, size_t itemCount) : 
        m_unitSize(unitSize)
...    
    Buffer(const Buffer& src)
...
    ~Buffer()
...    
    Buffer& operator = (const Buffer& src)
    {
        if(&src != this)
        {
            SetUnitSize(src.GetUnitSize());
            SetCapacity(src.Capacity());
            m_writeBegin = src.m_writeBegin;
            m_writeEnd = src.m_writeEnd;        
        }
        return *this;
    }
    
    size_t GetUnitSize() const
...    
    size_t Capacity(void) const
...    
    void Reset(size_t itemCount)
    {
        m_writeBegin = 0;
        m_writeEnd = 0;

        if(itemCount != 0 && itemCount != m_allocationCount)
        {
            SetCapacity(itemCount);
        }
    }    
    
protected:

    virtual void SetCapacity(size_t itemCount)
    {
        m_allocationCount = itemCount;
        m_writeBegin = 0;
        m_writeEnd = 0;      
    }    

    void SetUnitSize(size_t unitSize)
...    
    size_t m_unitSize;
    size_t m_allocationCount;//Track item count we have space for.
    size_t m_writeBegin;
    size_t m_writeEnd;    
};

I've added a convenience API for Reset as that's a thing users might need. If I was truly lazy I might not bother until there's a specific need of course but it modifies m_writeBegin and m_writeEnd so it may as well go in now.

We need a way to know how much space there is left in the buffer to write into before we go doing anything too dramatic like actually letting the user write data.

size_t Buffer::WriteCapacity() const
{
    size_t result = 
        m_allocationCount - 
        static_cast<size_t>(m_writeEnd - m_readBegin);
    return result;
}

This calculation may not make any sense right now. You'll need to trust me for a moment and we'll need to add read variables to Buffer as it turns out WriteCapacity is dependent on how much has already been read.

class Buffer
{
public:
    Buffer() : m_unitSize(1)
...
    Buffer(size_t unitSize, size_t itemCount) : 
        m_unitSize(unitSize)
...    
    Buffer(const Buffer& src)
...
    ~Buffer()
...    
    Buffer& operator = (const Buffer& src)
    {
        if(&src != this)
        {
            SetUnitSize(src.GetUnitSize());
            SetCapacity(src.Capacity());
            m_readBegin = src.m_readBegin;
            m_readEnd = src.m_readEnd;
            m_writeBegin = src.m_writeBegin;
            m_writeEnd = src.m_writeEnd;        
        }
        return *this;
    }
    
    size_t Buffer::WriteCapacity() const
    {
        size_t result = 
            m_allocationCount - 
            static_cast<size_t>(m_writeEnd - m_readBegin);
        return result;
    }

    size_t Buffer::ReadCapacity() const
    {
        size_t result = 
            static_cast<size_t>(m_writeBegin - m_readEnd);
        return result;
    }
    
    size_t GetUnitSize() const
...    
    size_t Capacity(void) const
...    
    void Reset(size_t itemCount)
    {
        m_readBegin = 0;
        m_readEnd = 0;
        m_writeBegin = 0;
        m_writeEnd = 0;

        if(itemCount != 0 && itemCount != m_allocationCount)
        {
            SetCapacity(itemCount);
        }
    }    
    
protected:

    virtual void SetCapacity(size_t itemCount)
    {
        m_allocationCount = itemCount;
        m_readBegin = 0;
        m_readEnd = 0;
        m_writeBegin = 0;
        m_writeEnd = 0;      
    }    

    void SetUnitSize(size_t unitSize)
...    
    size_t m_unitSize;
    size_t m_allocationCount;//Track item count we have space for.
    size_t m_readBegin;
    size_t m_readEnd;
    size_t m_writeBegin;
    size_t m_writeEnd;    
};

Now that we've got ReadCapaciy things might start to make more sense.

size_t Buffer::ReadCapacity() const
{
    size_t result = 
        static_cast<size_t>(m_writeBegin - m_readEnd);
    return result;
}

The data available for reading is in-between where we're going to write next and the end of what we've already read or are reading.

NOTE: This is the key to how the whole thing works so don't skip this bit.

Here's a representation of our buffer

|?-?-read_begin - - - - read_end( # # # #) write_begin - - - write_end?-?-|

The ( # # # #) part in the middle is what's already finished being written but hasn't started being read yet, i.e. the available Read Capacity.

The Write Capacity is the total buffer size less everything that has already been written and hasn't finished being read yet. i.e.

m_allocationCount - (m_writeEnd - m_readBegin);

Just the ?-?- space on the beginning and ?-?- end of the line in the diagram.

The part between read_begin and read_end is being read. The part between write_begin and write_end is being written. Either or both of these might be zero sized.

Hopefully that's super clear. Buffer management should be simple right.

Now that we know how much space is available for reading and writing we're almost ready to let clients write.

virtual size_t Buffer::WriteAcknowledge(size_t& itemCount)
{
    if(itemCount > (m_writeEnd - m_writeBegin))
    {
        itemCount = 
        static_cast<size_t>(m_writeEnd - m_writeBegin);
    }
    m_writeBegin += itemCount;
    m_writeEnd = m_writeBegin;
    return WriteCapacity();
}

This function lets clients tell us how many items they wrote. If they say they wrote more than the available space we disbelieve them.
Then we move the write_begin marker along by the number of items and set the write_end marker to the end of the actually written space as the client may not have written everything between write_begin and write_end this might mean write_end moving back. but it's always >= write_begin.

We'll obviously need the analogous function for reading so we might as well add that in.

size_t Buffer::ReadAcknowledge(size_t& itemCount)
{
    if(itemCount > (m_readEnd - m_readBegin))
    {
        itemCount = 
        static_cast<size_t>(m_readEnd - m_readBegin);
    }
    m_readBegin += itemCount;
    m_readEnd = m_readBegin;
    return ReadCapacity();
}

This allows the client to tell us they're done reading itemCount items.
However they might just want to say they are rejecting the last itemCount items they previously requested to read. They'll still need to acknowledge the ones they do read to move the read_begin point forward.

size_t Buffer::ReadReject(size_t& itemCount)
{
    if(itemCount > (m_readEnd - m_readBegin))
    {
        itemCount = static_cast<size_t>(m_readEnd - m_readBegin);
    }
    m_readEnd -= itemCount;
    return ReadCapacity();
}

We're almost there I promise. Just two more functions on this class to go.
All that's left is functions for the client to Request to Read, i.e. move the read_end point forward and to Request to Write, i.e. move the write_end point forward.

virtual byte* Buffer::WriteRequest(size_t& /*itemCount*/)
{
    return nullptr;
}

virtual byte* Buffer::ReadRequest(size_t& /*itemCount*/)
{
    return nullptr;
}

What happened?
Well we can't actually write these functions because they need to return actual pointers to data. We could complicate the Buffer class by adding real memory handling but that wouldn't be sfumato.
Instead having gradually built up one layer and reached the point where the client facing interface is defined if not entirely implemented, we'll begin another layer.

Layer 2: All the pointer magic in one place

We'll use traditional Object Oriented extension by inheritance. A PODBuffer< pod_t > is a Buffer. We'll add a template parameter as still nobody has told us what goes in this Buffer.

template< class pod_t >
class PODBuffer : public Buffer
{
protected:

    pod_t* m_pAllocation{nullptr};
};

Let's add some standard class furniture and then deal with memory management

template< class pod_t >
class PODBuffer : public Buffer
{
public:

    PODBuffer(size_t itemCount = 0) : 
        Buffer(sizeof(pod_t), itemCount)
    {
        SetCapacity(itemCount);
    }

    PODBuffer(const PODBuffer& src)
    {
        *this = src;
    }

    virtual ~PODBuffer()
    {
        //This is needed. Remind me to write an article
        //about why virtual functions don't work
        //in base class destructors.
        SetCapacity((size_t)0);
    }

    PODBuffer& operator = (const PODBuffer& src)
    {
        if(&src != this)
        {
            Buffer::operator = (src);
            memcpy(
                m_pAllocation, 
                src.m_pAllocation, 
                sizeof(pod_t) * std::min(
                    m_allocationCount, src.m_allocationCount
                )
            );
        }
        return *this;
    }

protected:

    pod_t* m_pAllocation{nullptr};
};

When the pod_t type is determined it's size will be available to become the Buffer unit size. We could add a requires clause using type traits to ensure it's a fixed size type however std::is_pod is deprecated and I'm not sure which one to use in its place. std::is_standard_layout ? Let me know and I'll add it.

When we copy a PODBuffer, now we actually copy the contents as well. Taking care to use only the size of the smaller buffer.
However so far there are no contents. Lets fix that by overriding SetCapacity

virtual void SetCapacity(size_t itemCount)
{
    if(m_allocationCount == itemCount && m_pAllocation != nullptr)
    {
        return;
    }

    delete[] m_pAllocation;
    m_pAllocation = (itemCount > 0) ? 
        new pod_t[itemCount] : nullptr;

    memset(m_pAllocation, 0, sizeof(pod_t) * itemCount);
    Buffer::SetCapacity(itemCount);
}

That's it. One new and one delete. Now those SetCapacity((size_t)0) calls we did earlier don't look so silly. For added security we fill the Buffer with zeros.
Let's override the failed implementation of WriteRequest now with one that returns a valid pointer.

virtual byte* WriteRequest(size_t& itemCount)
{
    pod_t* result = 0;
    if (itemCount == 0 || itemCount > WriteCapacity())
    {
        itemCount = WriteCapacity();
    }

    if (itemCount > 0)
    {
        result = AddressOf(m_writeBegin);
        m_writeEnd += itemCount;//write_end moves here
    }

    return reinterpret_cast<byte*>(result);
}

It would be nice to return a pod_t* here but C++ doesn't do covariant return types so to override the truly ignorant Buffer::WriteRequest we have to return a byte*. The client can safely cast it back as they know what a pod_t is.

Note that a write request is just that. Requesting to write 65 items might get you space to write 5 or 0 if the buffer is full. the client will need to take note of the value of itemCount after the call. This is how many items they are allowed to write.

Requesting to read is very similar but first lets look at AddressOf

pod_t* AddressOf(size_t index)
{
    pod_t* result = nullptr;
    if (m_allocationCount > 0)
    {
        result = m_pAllocation + (index % m_allocationCount);
    }
    return result;
}

This gives an offset into the allocated space in multiples of sizeof(pod_t) which is always within the allocated space.
Remember the + operator here is using pointer arithmetic rules. As m_pAllocation is a pod_t* so it adds in sizeof(pod_t*) sized units. Exactly what we want. ReadRequest uses the same function:

virtual byte* ReadRequest(size_t& itemCount)
{
    pod_t* result = AddressOf(m_readBegin);
    if (itemCount > ReadCapacity())
    {
        itemCount = static_cast<size_t>(ReadCapacity());
    }
    m_readEnd += itemCount;//read_end moves here
    return reinterpret_cast<byte*>(result);
}

You may have wondered how we keep the read_begin, read_end, write_begin and write_end values within the allocated space. The answer is that we don't. We care that Read follows Write and that End is >= Begin but we don't care what the actual numeric values are. (index % m_allocationCount) gives the correct position in the buffer and limiting the Write Capacity to the allocation size is sufficient to ensure that write_end is never more than allocation count units ahead of read_begin so we don't don't tread on our own tail as the output of (index % m_allocationCount) wraps around.

This leaves us with just one problem. When we report Read and Write capacities to the client we don't take that wrap around into account. If the available space is split over the end of the buffer we can't give the client a contiguous block of memory to Read or Write. We could give them two but that would be a really weird interface. Here's most of the memory you asked for and here's the other bit which is usually null.

Instead we'll just behave as if the second part wasn't available. To do this we need to override WriteCapacity and ReadCapacity

virtual size_t WriteCapacity()
{
    size_t result = m_allocationCount - 
        static_cast<size_t>(m_writeEnd - m_readBegin);

    if(AddressOf(m_writeBegin) + result > EndOfBuffer())
    {
        result = EndOfBuffer() - AddressOf(m_writeBegin);
    }
    return result;
}

virtual size_t ReadCapacity()
{
    size_t result = static_cast<size_t>(m_writeBegin - m_readEnd);

    if(AddressOf(m_readEnd) + result > EndOfBuffer())
    {
        result = EndOfBuffer() - AddressOf(m_readEnd);
    }
    return result;
}

pod_t* EndOfBuffer(void)
{
    pod_t* result = nullptr;
    if (m_allocationCount > 0)
    {
        result = m_pAllocation + m_allocationCount;
    }
    return result;
}

That's really it this time. Here's the whole PODBuffer< pod_t > class along with streaming >> operators << to easily insert and extract items.

template< class pod_t >
class PODBuffer : public Buffer
{
public:

    PODBuffer(size_t itemCount = 0) : 
        Buffer(sizeof(pod_t), itemCount), m_pAllocation(nullptr)
    {
        SetCapacity(itemCount);
    }

    PODBuffer(const PODBuffer& src)
    {
        *this = src;
    }

    virtual ~PODBuffer()
    {
        SetCapacity((size_t)0);
    }

    PODBuffer& operator = (const PODBuffer& src)
    {
        if(&src != this)
        {
            Buffer::operator = (src);
            memcpy(m_pAllocation, 
                src.m_pAllocation,
                sizeof(pod_t) * std::min(
                    m_allocationCount, src.m_allocationCount
                )
            );
        }
        return *this;
    }

    PODBuffer& operator << (const pod_t& item)
    {
        size_t count = 1;
        pod_t* pWrite = reinterpret_cast<pod_t*>
            WriteRequest(count));

        if(pWrite && count == 1)
        {
            *pWrite = item;
            WriteAcknowledge(count);
        }
        return *this;
    }

    PODBuffer& operator >> (pod_t& item)
    {
        size_t count = 1;
        pod_t* pRead = reinterpret_cast<pod_t*>
            (ReadRequest(count));

        if(pRead && count == 1)
        {
            item = *pRead;
            ReadAcknowledge(count);
        }

        return *this;
    }

    virtual size_t WriteCapacity()
    {
        size_t result = m_allocationCount - 
            static_cast<size_t>(m_writeEnd - m_readBegin);

        if(AddressOf(m_writeBegin) + result > EndOfBuffer())
        {
            result = EndOfBuffer() - AddressOf(m_writeBegin);
        }
        return result;
    }

    virtual size_t ReadCapacity()
    {
        size_t result = static_cast<size_t>(
            m_writeBegin - m_readEnd);

        if(AddressOf(m_readEnd) + result > EndOfBuffer())
        {
            result = EndOfBuffer() - AddressOf(m_readEnd);
        }
        return result;
    }

    virtual byte* WriteRequest(size_t& itemCount)
    {
        pod_t* pResult = 0;
        if (itemCount == 0 || itemCount > WriteCapacity())
        {
            itemCount = WriteCapacity();
        }

        if (itemCount > 0)
        {
            pResult = AddressOf(m_writeBegin);
            m_writeEnd += itemCount;
        }

        return reinterpret_cast<byte*>(pResult);
    }

    virtual byte* ReadRequest(size_t& itemCount)
    {
        pod_t* pResult = AddressOf(m_readBegin);
        if (itemCount > ReadCapacity())
        {
            itemCount = static_cast<size_t>(ReadCapacity());
        }
        m_readEnd += itemCount;
        return reinterpret_cast<byte*>(pResult);
    }

    virtual void SetCapacity(size_t itemCount)
    {
        if(m_allocationCount == itemCount 
            && m_pAllocation != nullptr)
        {
            return;
        }

        delete[] m_pAllocation;
        m_pAllocation = (itemCount > 0) ? 
            new pod_t[itemCount] : nullptr;

        memset(m_pAllocation, 0, sizeof(pod_t) * itemCount);
        Buffer::SetCapacity(itemCount);
    }

protected:

    pod_t* EndOfBuffer(void)
    {
        pod_t* pResult = nullptr;
        if (m_allocationCount > 0)
        {
            pResult = m_pAllocation + m_allocationCount;
        }
        return pResult;
    }

    pod_t* AddressOf(size_t index)
    {
        pod_t* result = nullptr;
        if (m_allocationCount > 0)
        {
            result = m_pAllocation + (index % m_allocationCount);
        }
        return result;
    }

    pod_t* m_pAllocation;
};

and for completeness (because I'm not really very good at being lazy)

typedef PODBuffer< byte > ByteBuffer;

The two hard things that catch everyone out the first few times doing buffers are the memory management and preventing overruns. It turns out that actual memory management requires just two lines of code.

delete[] m_pAllocation;
m_pAllocation = (itemCount > 0) ? new pod_t[itemCount] : nullptr;

And buffer overruns are terminated forever by just one.

result = m_pAllocation + (index % m_allocationCount);

We used the power of our ignorance of the real requirements to create a semi circular buffer class for any number of units of any fixed sized type. We left it up to the client to decide everything we didn't know and we delayed all the hard parts until they weren't hard or we didn't have to do them at all. We separated the task into layers that deal with different problems. Keeping every step as simple as possible.

#include <cstddef>
#include <cstdint>
#include <cstring>
#include <cassert>
#include <string>
#include "podbuffer.h"

struct test_s
{
    bool b;
    const char* s;
    unsigned long long l;
};

int main()
{
    PODBuffer<test_s> aBuffer(15);
    test_s test{ true, "something", 100000000 };
    aBuffer << test;
    test_s result;
    aBuffer >> result;
    assert(memcmp(&result, &test, sizeof(test_s)) == 0);
    return 0;
}

Conclusion:

What are the costs and benefits of this sfumato approach to writing code?

The resulting code is certainly not compact. Although that doesn't matter as much in a compiled language like C++ as it would in Python or JS.
You can end up with many layers and it requires a well organised source tree not to loose track of them.

The performance has not been honed to the last clock cycle and cache line. I generally prefer to leave that to the optimising compiler which knows a great deal more about my hardware than I do. Is this buffer fast though? In practice you can count the nano seconds because they seldom reach 3 digits. Yes it's fast although you're welcome to make it faster and let me know how.

The functions are small and simple. You may have noticed that there's no single function in this article that's more than a handful of lines. This makes writing unit tests as you go along easy. This also makes tracking down bugs and generally understanding the code you wrote 5 years ago, easier.

You get reliable, readable, intentional, testable code with strong separation of concerns. So don't be afraid to write incomplete classes that only do part of the job. As long as the part they do is simple, safe and reliable. You can always add another layer of sfumato to solve the next problem. Abstracting each problem, or set of problems, into it's own thin layer leads to surprisingly pleasing results.

This PODBuffer< pod_t > class, or one very like it, is in use in the general data pipeline library of the QuerySoft Open Runtime. I wrote the first version of it more than a decade ago and it's changed very little. (That's why some of the code style is a bit out of date)

Do you have a favourite class or code snippet that you've been using for years across projects. Is it sfumato code? If you do please consider sharing it.

Here's a snippet of Buffer in real use. It was streaming JSON from a file to a parser at the time but you can't tell by looking.

bool Source::Pull(size_t& unitsRead, size_t unitsToRead)
{
    if(!unitsToRead)
    {
        return true;
    }

    Buffer* buffer = GetBuffer();
    if(buffer)
    {
        byte* space = buffer->WriteRequest(unitsToRead);
        if(!space)
        {
            log::debug("Buffer capacity: {0}, Write capacity: {1}, Read capacity: {2}, Unit size: {3}", 
                buffer->Capacity(), 
                buffer->WriteCapacity(), 
                buffer->ReadCapacity(), 
                buffer->GetUnitSize());
            continuable("Pipeline stall. No space in source buffer.");
            return false;
        }

        size_t bytesRead = ReadBytes(
            space, buffer->GetUnitSize() * unitsToRead);

        if(bytesRead > 0)
        {
            unitsRead = bytesRead / buffer->GetUnitSize();
            buffer->WriteAcknowledge(unitsRead);
            OnReadSuccess(unitsRead);
        }
        else
        {
            OnEndOfData();
        }
        return true;
    }
    else
    {
        return false;
    }
}

External Polymorphism

Matthew Faithfull — Thu, 06 Aug 2026 01:01:06 +0000

External Polymorphism - Ways of getting the same extensibility and composability of types you get with 'normal' inheritance based polymorphism but without virtual functions or thunks and their associated costs. Without changing the types that you're extending and composing or imposing heavy requirements on them.

The idea has been around for at least thirty years and there have been lots of C++ implementations over the years. Mostly they started out recreating vtables outside the target classes in an effort to implement type erasure. These days type erasure is common place but, useful as it is, it is only one form of external polymorphism.

I've recently been porting a std::function alternative library magic_func which uses type erasure over function pointers and also looking at Ilya Korolev's Contracts library which puts what could maybe be external polymorphism back into the types being adapted. That gives you access to all the internals of the target type and uses the encapsulation of the target type to encapsulate the contract machinery as well.
Can we do some of what Contracts is doing without modifying the target classes and at the same time do type safe external polymorphism rather than fully generic type erasure.?

Using the principles of code sfumato we'll see if we can gradually build something useful starting very simple.
Let's say we have some kind of business object...

namespace domain
{
    struct datatype
    {        
        unsigned int accno;
        float ammount;
        std::string name;
        std::vector<std::string> log;
    };  
}

Everything is public. Everything is a value type. This is just plain data.

There are two ways we could bind something external to a member of
domain::datatype in C++. Either by pointer or by reference.
Pointers are easy to type erase, they're all the same size and they don't have to be initialised. The downside is that because they don't have to be initialised, they do have to be null checked and because they are stored and have size they can't easily be elided by the optimiser.
References are somewhat more slippery to deal with but we'll give them try. Mostly because in the past I've always opted for pointers and I've never been super happy with the result.

template< typename T >
struct ValueAdapter
{
    ValueAdapter(T& t) : m_(t)
    { }        
private:
    T& m_;
};

Not bad as a first attempt. We can construct a ValueAdapter(x) on any value of type T and we have an object entirely external to T which can operate on x.
To make ValueAdapter useful though we need to extend it with the operations we want to perform on our captured T&.

When I first started messing around with external polymorphism it was extremely difficult to do. In 2003 tuples were a PhD thesis by a Finnish researcher and I may have been the first ever person to see
tuple::get<0>(t) compile under under a Microsoft compiler and execute correctly on Windows. It needed compiler specific template and macro hackery to make the port work (barely) with a maximum of 5 elements and it wasn't practical.
These days many extraordinary things are possible in modern C++. We'll come back to tuples. Lets try to improve ValueAdapter.

template <typename T, typename... Bases>
struct ValueAdapter : public Bases...
{
    using value_type = T;
    ValueAdapter(T& t) : Bases(std::forward<T&>(t))...
    { }        
};

A second attempt at ValueAdapter lets us provide it with a type for the value and a list of types to inherit from, each of which gets constructed with the T&, passed to ValueAdapter. We no longer need to hold a reference in this root object as each operation that needs one will hold onto one itself.

You might notice the Curiously Recuring Template Pattern (CRTP) hiding here in parameter pack form.

To make use of this we'll need to write a set of operations that can be composed into a ValueAdapter. Starting with a simple Read to get the value.

template<typename T>
struct Read
{    
    Read(T& t) : m_(t){ }

    T Get() const {return m_;}
    
private:
    T& m_;
};

Here's an equally simple Write to set the value.

template<typename T>
struct Write
{
    Write(T& t) : m_(t){ }

    void Set(const T t){ m_ = t; }    
    
private:

    T& m_;
};

These operations are so trivial and specific in what they do that they might even be considered bug free, maybe.

Now we can make an actual ValueAdapter type to eventually attach to unsigned int datatype::accno :

using AccNoAdapter = ValueAdapter< 
unsigned int, Read< unsigned int >, Write< unsigned int > >;

If we left out the Write we'd have a read only value and if we left out the Read we'd have a write only value. Both things we might want at some point. A practical library would certainly provide ReadOnlyValueAdapter as a type and many other operations we could plug in so we might end up with something like:

using AccNoAdapter = ReadOnlyValueAdapter< 
unsigned int, StreamOut< unsigned int >, 
ToString< unsigned int >, Name< unsigned int > >

This is fine but a bit tedious to type with the repetition of unsigned int, the type of the underlying thing we're binding to.
It should be possible to just say we want the ReadOnlyValueAdapter
type with an unsigned int and a list of operations, that also get the unsigned int automatically.

template<
    template<class...> class P,
    class T,
    template<class> class... L >
struct adapter_apply
{
    using type = P<T, L<T>... >;
};

With this beauty using template templates and pack expansion it is. We can now say:

using AccNoAdapter = adapter_apply<
    ReadOnlyValueAdapter, unsigned int, 
    StreamOut, ToString, Name >::type;

AccNoAdapter becomes a ReadOnlyValueAdapter templated on unsigned int and the expanded list of types, each templated on unsigned int exactly as we did before by hand.

That takes care of attaching almost anything we can think of to a single value type.

unsigned int accno;
AccNoAdapter accnoAdapter(accno);

attaches reading, writing, naming and streaming operations to accno so we can do things like.

accnoAdapter.SetName("Bob");
accnoAdapter.Set(163);
std::cout << accnoAdapter;

Here are a couple more ValueAdapter types we need to build to address the members of domain::datatype

using AmmountAdapter = adapter_apply< 
    ValueAdapter, float, 
    Read, EnhancedNumericWrite, 
    StreamIO, Name >::type;

using LogAdapter = adapter_apply< 
    CollectionAdapter, std::vector<std::string>,
    ReadCollection, Append, StreamOutCollection >::type;

We've painted the first layer of external polymorphism, Value Adapters.

Now we'd like to adapt entire objects at a time. In practice what we usually want is to provide specific interfaces over those objects that meet the requirements of something external to our domain.

template <typename... Args>
struct InterfaceAdapter : public std::tuple<Args...>
{
    using storage_type = std::tuple<Args...>;

    InterfaceAdapter(Args&&... args) : 
        std::tuple<Args...>{std::forward<Args>(args)...}
    { }
    //...

This is where tuples come in handy. Under the hood they are derived from all their arguments recursively and come with helpful and reliable standard library machinery like iteration and element lookup.
Otherwise the pattern is similar to what we did with ValueAdapter except that now the composed base classes are the ValueAdapter types we built up for the individual members.

using PaymentInterface = InterfaceAdapter< 
AccNoAdapter, AmmountAdapter, LogAdapter >;

These interface types are a kind of two dimensional class. A tuple of ValueAdapters, one for each member being referenced, with each ValueAdapter being a collection of operations attached to that member.

We need to bind this interface type to the underlying storage type domain::datatype that we started with. For this we'll need a binding adapter

template<class interface_t, class storage, typename field_enum>
struct Adapter : public interface_t, protected storage
{            
    template <typename... Args>
    Adapter(storage& src, Args&&... args) : 
        storage(src), interface_t(args...)
    { }

    //accessor for fields
    template<field_enum f>
    auto& at() { return std::get<static_cast<int>(f)>(*this); }

    template<field_enum f>
    struct type_of_field
    {
        using type = std::invoke_result_t<
            decltype(
                &Adapter<interface_t, storage, 
                field_enum>::template at<f>
            ), 
            Adapter<interface_t, storage,
            field_enum> >;
        };
    };

In order to map the elements from our ValueAdapter tuple to members in domain::datatype we also need to provide the adapter with an enum class

enum class paymentfields
{
    account,
    ammount,
    log
};

This just gives names to constants 0, 1 & 2 so that we can say things like

payment.at<paymentfields::account>().SetName("Account");

We'll get to that. First we need to combine our interface and enumeration types together to form a specific adapter type.

template<class storage>
struct PaymentAdapter : public Adapter<PaymentInterface, storage, paymentfields>
{
    PaymentAdapter(storage& src) : 
      Adapter<PaymentInterface, storage, paymentfields>(src,
        storage::accno,//the position in this list
        storage::ammount,//must match the enum value
        storage::log)//of the associated ValueAdapter
    { }
};

storage is still a template parameter here but we know it must have at least the named fields, in any order, for this template to be instantiated.
It's important to note that because Adapter inherits from storage PaymentAdapter is an instance of storage. The underlying struct will be copied when bound to PaymentAdapter and it will operate on the copy.
This is fine for outgoing adapters that read storage and provide an interface for something external but if we want to be able to modify the original storage type instance through the interface then we need a Port rather than an Adapter.

template<class interface_t, class storage, typename field_enum>
struct Port : public interface_t
{                
    template <typename... Args>
    Port(storage& src, Args&&... args) : 
        m_(src), interface_t(args...)
    { }

    //accessor for fields
    template<field_enum f>
    auto& at() { return std::get<static_cast<int>(f)>(*this); }

    template<field_enum f>
    struct type_of_field
    {
        using type = std::invoke_result_t<
            decltype(&Port<interface_t, storage,
                field_enum>::template at<f>),
            Port<interface_t, storage, field_enum> >;
    };

private:

    storage& m_;
};

A Port over the PaymentInterface and the same paymentfields enumeration gives us:

template<class storage>
struct PaymentPort : public Port<PaymentInterface, storage, paymentfields>
{
    PaymentPort(storage& src) : 
        Port<PaymentInterface, storage, paymentfields>(src,
        src.accno,//The refenced fields from the src
        src.ammount,//are bound to the ValueAdapters
        src.log)//in the order of the paymentfields enum
    { }
};

With all the type infrastructure we need in hand we can now do:

using adapter_t = PaymentAdapter<domain::datatype>;

domain::datatype data{ 20015678, 56.8f, "name" };
adapter_t payment(data);

payment is now a PaymentInterface bound to a copy of data. We can use the paymentfields enum to access the ValueAdapters and directly call the bolted on operations as if they were functions on members of domain::datatype.

payment.at<paymentfields::account>().SetName("Account");
auto a = payment.at<paymentfields::account>().Get();

payment.at<paymentfields::ammount>().SetName("Payment Ammount");
payment.at<paymentfields::ammount>().SetMinimum(0.01f);
payment.at<paymentfields::ammount>().SetMaximum(10000.0f);

payment.at<paymentfields::ammount>().SetOnChange(
    qor_pp_make_function(&OnPaymentAmmountChange));

payment.at<paymentfields::ammount>().Set(103.8f);

There's more though. I didn't show you the full implementation of
InterfaceAdapter above. It enables us to do things like applying a lambda template to each of the fields on an interface

payment.for_each_field([](size_t& index, const auto& x)     
{                        
    if constexpr(is_streamoutable<decltype(x)>())
    {
        if (index++ > 0) std::cout << ", ";
        if constexpr(is_named<decltype(x)>())
        {
            std::cout << x.GetName() << ": ";
        }
        x.operator << (std::cout);
    }
});

This iterates over the tuple of ValueAdapters on the PaymentInterface calling the lambda with each one. The lambda has to be a template because each ValueAdapter has a different type.
The is_streamoutable and is_named functions check whether the field being processed has particular operations attached to it. These are constexpr functions so the parts of the lambda that won't work never even make it into the binary.
In this way we can filter fields for ones that can be printed or read or written or whatever we need.

template<typename x>
constexpr bool is_named()
{
    using x_type = std::remove_cvref_t<x>;
    if constexpr(is_valueadapter<x>())
    {
        using v_type = typename x_type::value_type;
        return std::is_base_of_v<Name<v_type>, x_type>;
    }
    /*More stuff to handle Collections*/
    return false;
}

To use a Port that can modify our original object we wrap a PaymentPort around our domain::datatype.

using port_t = PaymentPort<domain::datatype>;
port_t pay(data);

pay.at<paymentfields::ammount>().Set(34.67f);
pay.at<paymentfields::log>().push_back("Set ammount to 34.67");

pay holds a reference to data so these lines modify the contents of data directly.

The types of individual fields can be retrieved with
interface_t::type_of_field< enum_index >::type
as seen here where we check if the account field is convertible into a string before attempting to write it out. is_stringable works just like is_named. It checks if the type is derived from the ToString<> operation.

if constexpr(is_stringable<
    adapter_t::type_of_field<paymentfields::account>::type >())
{
   std::cout << 
       payment.at<paymentfields::account>().toString();
}

That's it. There are undoubtedly wrinkles. Every implementation of external polymorphism I've come across has them but with this small library of templates we can build almost any functionality over a set of plain data objects without virtual functions and without modifying them.
There are no vtables. We don't even have to build artificial ones ourselves. The equivalent is the lookup done by std::get< i >( T ) to get a reference into our tuple of ValueAdapters.
We can have multiple specialist interfaces over the same type without any cross dependency or additional cost and we can add unlimited meta data, validation, etc to those interfaces. We can introspect the operations available on a data item and branch on the result with no runtime cost. Every custom operation is available for reuse on any interface without even having to derive from it.

When templates were still a non standard feature, liable to crash your compiler, and tuples were academic research we dreamed of being able to do things like this. What do you dream of being able to do that's just out of reach with C++ today?

Source code is available on the DomainInterfaceObjects branch of the QOR
If you think it's of value let me know and I'll pull it into main.

Fast Parsing

Matthew Faithfull — Fri, 31 Jul 2026 15:04:28 +0000

I've been attempting to optimise my state machine based text parser. As a precursor to making it do Unicode and act as a base layer for a JSON parser, HTML parser etc.
The internet tells me that Google's V8 can crunch through ASCII characters at ~1/10ns if you can believe that. I can't get closer than an order of magnitude with about ~1/150ns. At least that's down from ~1/1000ns this morning.

Here's what I've done so far:

I branched my basic state machine which uses std::function for it's events.
std::function has now been replaced with qor::tef (Type Erased Function) ported from Magic Function by Leandro Gracia Gil.
That should mean each call/event has half the overhead of std::function

I removed the suspend event from the new Workflow variant, Fastflow, altogether as the parser framework doesn't use.

The replacement Fastflow steps and all their derivatives now use a custom allocator, or in QOR framework terms they have a custom memory source policy.

template<> struct source_of< data::parser::text::utf8char >{ typedef memory::FastSource type;};

FastSource is a per-thread stack style arena which only free's when pages empty out. Perfect for large numbers of small allocations which go away when the parser is finished.

I also tried the per-thread SmallObjectSource which is a little more space efficient. The performance was identical to native but that's expected as this is a single threaded scenario so there's no contention for the global heap.

I had profiled the parsing of a 73KB file using the framework's built-in profiling. Hence the base line 1 microsecond per character.
When that couldn't tell me where the time was going I used the Visual Studio profiler to dig deeper into what was happening.

I'd already played about with the buffer size used to read the underlying file and surprisingly bigger was not better. Performance peaked at ~60-120 bytes and tailed off with a larger buffer. The buffers shouldn't get reallocated in use so this is odd and I'll need to dig deeper to determine why. I expected a single buffer big enough to consume the whole file at once would be optimal. Apparently not. I set it at 64 bytes.

For now I'm excluding the IO time and focussing on the parser where an
unexpectedly a large chunk of the time was spent pushing and popping to the std::stack<> of the state machine itself. I minimised this by using std::stack::top when mutating the top node rather than popping it and then pushing it back later. That wasn't enough so I overrode the underlying container over which std::stack is an adapter.

It now uses a std::vector instead of a std::deque

std::stack< ref_of<fastflow::Step>::type, std::vector< ref_of<fastflow::Step>::type > > m_StepStack;

So I can reserve space in the vector in advance.

std::vector< ref_of<fastflow::Step>::type > stepVector;
stepVector.reserve(64);
m_StepStack = std::stack< ref_of<fastflow::Step>::type, std::vector< ref_of<fastflow::Step>::type > >(std::move(stepVector));

With a simple parse tree for repeatedly tokenizing characters this should be more than enough to avoid reallocation completely.

Now the flame graph looks like this:

As you can see the parse is taking almost the same time as the I/O. The two together are ~22.5ms on a 4GHz Zen3 CPU Core.

I've had a look at the V8 source code for clues as as to what they might be doing to be 10x more efficient but it's certainly not obvious.

My code will be up at QOR experimental as soon as I've assessed what else all those changes have broken.
Running your own memory memory allocators tends to either work smoothly or blow up pretty spectacularly.

I'd welcome any suggestions as to what else I could optimise, how to get similar performance data on Linux or if you've been down a similar road.

I hope your day was as interesting as mine.

I asked Reddit what they wanted in a C++ application framework and their answers were...

Matthew Faithfull — Wed, 22 Jul 2026 17:28:16 +0000

In short their answers were useful and highly aligned, not just with with my thinking but with one another. There wasn't consensus, this is the internet, but there were was remarkable consistency.

"...painless cross-platform-ness, obviously. One should not need to dip into the underlying Win32 on Windows, say, basically ever to do typical things."

Agreed! We should be able to create substantial applications without consideration for which OS they're going to run on. Most of the languages our applications talk these days, from Unicode to OpenGL, to gRPC are standardised across operating systems and even across programming languages. With a little bit of work to smooth over the idiosyncrasies of individual operating systems we aught to be able to program in terms of these standards without worrying about the target platform on which they'll end up running.
In practice of course that 'little bit of work' could end up being rather large but perhaps it can be done.

"Must support CMake find_package vcpkg instrumentation..."

Agreed! We love to hate CMake but it is what the industry is settling around. We build with CMake and package with vcpkg. It doesn't solve all our problems or make delivering C++ software easy but it works well enough and will likely get the focus and feedback required to keep making it better.

"License must be something like BSD..."

Agreed! Boost license, MIT license and BSD licenses so that the project can be used commercially without caveats or concerns. Anyone can contribute, including companies and everyone who wants to commercialise their own fork can. No fuss, no argument licensing makes adoption much smoother and therefore much more likely.

"All C++...", "No DSL...", "No extra pre-processor stage..."

Agreed! C++ can do anything so if we're doing something, we're doing it in C++. Especially for a C++ framework. That includes Signals and Slots. DSLs are the temptation ever in the corner of the eye. Goading us make things look simpler while destroying discoverability and imposing new vocabulary on our users.

"Must not be header only..."

Agreed! Gigantic header only libraries are a menace. They slow build times, often hide bad code, leak definitions, have unclear APIs and all contain similar but not quite the same, boiler plate for platform and compiler support. Duplicated code that makes them inconsistent with one another and undermines your platform support from below while preventing you from centralising it.
Boost was originally intended to be a header only framework and it still suffers from the consequences today with header dependency chains reaching out across multiple libraries to things you never intended to depend on. It's getting better but their moving away from header only should be a lesson learned.

"Native C++ database (scalable)..with non SQL interface."

Not a big ask at all then ;-) However it is something we could do with. Many years ago I worked with a multi dimensional BI database written in Fortran that ran rings around Oracle and made SQL Server look silly. It was definitely non SQL although it did have it's own somewhat arcane query language. Something like that in modern C++ with simplified queries would be awesome.

Then there's the UI of course.

"MUST support a declarative GUI language that’s transpiled to a compiled language like C++, so no js framework in between."

"If you are going to have a separate WPF-style layout language (please don't use XML), allow the user to opt out of it. Don't make it mandatory. That is, allow the user to create UIs by just nesting together controls using normal C++ code if that is what they want to do."

"Make it possible, if not necessarily easy, to construct 100% custom controls."

"...support a dark theme out of the box."

"...supports WebAssembly ... so that we can create amazing ..native C++ websites."

"WinForms + designer but for C++"

So we want an optional declarative GUI language that can be generated from an interactive designer, hand written, or bypassed altogether to create completely custom controls, mixed in with the provided ones. The GUI that results must run natively and in a browser using WASM.

"Like Dioxus for Rust"

as someone noted.

Last but not least.

"...with the compile times of C#."

Of course, no problem ;-)

You'll notice that while there are a lot of big asks here and this is not every response I got. There is very little in the way of contradictory requirements. In principle we could have the C++ framework we want. Cross platform, comprehensive and flexible. We'd just have to write it.

So what are your MUST HAVEs and MUST NOTs for an all new, top of the line, C++ Application Framework?
Do you believe such a project is possible and would you be interested in contributing?