Rationale: Or why am I bothering to rewrite nanomsg?
This is at least partially ill-advised.  Comes off as an expertly done, but same old refactoring project that could be titled &quot;I didn&#x27;t understand this and would understand it better if I were designed based on my personal preferences&quot;.  This is reinforced by the probably approaching 1 that nobody needs another &quot;six of one half dozen of the other&quot; message queue framework, and alluding to an belief that the C++ library is somehow too bloated for embedded environments. While that was at a time true, no reasonably modern embedded system that requires multi-threading to &quot;100s&quot; of threads, or uses 100s of live sockets for message queue I&#x2F;O, has to avoid C++ for being too heavy. This is just ZeroMQ alternative #N - not anything objectively better, and certainly not &quot;nano&quot; for embedded systems.  The &quot;one true messaging framework&quot; is a unicorn - everyone feels like it should exist but nobody can make it.<p><i>But for many cases this is not necessary. A simple callback mechanism would be far better, with the FDs available only as an option for code that needs them. This is the approach that we have taken with nng.</i><p>Replacing a state machine with callbacks... something something something you&#x27;re gonna have a bad time.  Esp. considering the gripes are about readability, following control flow, and race conditions.  Callbacks are objectively worse for all of those things. Control flow <i>is</i> hard to read in state machine frameworks because the primary flow is dictated by something like &quot;nextState(thisState, action)&quot;, so you can&#x27;t follow it with code lookup.<p>The problem here (and almost always) is lack of documentation or visualization (or picking the wrong abstraction level for the formally defined states).  The beauty is that the definition is almost by default naturally easy to parse (tables of states in a header file, etc.). It takes some extra effort, it is a one shot to write something that generates graphviz state chars or something similar from the state table definition.  You could write a custom dot syntax generator from a C-style table definition in what, three hours?  Doxygen already does this for much more complicated stuff.  Googling reveals this is nothing new: <a href="https:&#x2F;&#x2F;gist.github.com&#x2F;freqlabs&#x2F;24d88ad8e687891c970a69f16f1387b8" rel="nofollow">https:&#x2F;&#x2F;gist.github.com&#x2F;freqlabs&#x2F;24d88ad8e687891c970a69f16f1...</a><p>All that said, State Machines are (currently) the one true abstraction for a given program because that is what a computer is, and every program is, to begin with.  If you&#x27;re not using them explicitly, it just means you have a poorly defined&#x2F;documented state machine.  Maybe someday there will be a better model of computing, or a better way to model programs.  For now, the human brain isn&#x27;t getting any better at keeping track of computer programs, and anything more than single-threaded functional-style code is almost certainly not any &quot;absolute&quot; improvement in readability.<p>I firmly believe that visualization has become necessary due to complexity, and it is past time to embrace it.  There is some stigma that visualization is for fakers - &quot;real programmers only use a bare text editor&quot; - or that it is for children learning programming, or non-engineering folks that need pictures because they&#x27;re dumb.  To be a bit hyperbolic, if we want any chance at keeping up with &quot;the machines&quot;, we&#x27;re going to need a better general-purpose, more workable abstraction than text files.  There is no more canonical example of this than the issues pointed out here - state machines are the right abstraction for complex systems, but complex state machines are incredibly difficult to follow in source code.