NNG™ Reference Manual
Garrett D'Amore
Second Edition
Copyright © 2018 Staysail Systems
San Marcos, California, United States of America
This document is optimized for on-screen use. Please consider purchasing the book before printing it.
Purchases of the book help fund continued development NNG™. For updates, additional formats, errata,
and more information, please visit it’s homepage.
NNG™ and nanomsg™ are trademarks of Garrett D’Amore.
Second edition, November 2018.
For Jenichka —
The sun always shines when you are home.
Preface
At the time of this writing, we are wrapping up NNG for its formal 1.0.0 release. It’s a good time for
reflection on the road that we took to get here. Like the road on the cover of this book, it was windy (if
quite a bit longer), but what we find at the end has made the journey worthwhile.
Originally the NNG project was conceived as a relatively modest effort to rewrite nanomsg based on
threads, with a more readily extensible internal architecture so that we could more easily undertake
projects like the ZeroTier and TLS transports.
It would not be incorrect to say that the initial NNG effort was started in “anger”, as we were frustrated
with nanomsg’s very complex internal state machines. Looking back on it now, those complex state
state machines don’t seem nearly as insane as they did just a year ago.
The simple, naïve, approach we would have preferred, and the one we originally started with, involved
significant use of threads, inspired by the work we did in mangos, which uses Go’s goroutines heavily.
Goroutines are excellent. Threads, it turns out, are not. Scalable, asynchronous, portable I/O is a lot
harder than it looks.
Our experience with in-kernel threads on illumos and Solaris spoiled us, and left us utterly unprepared for
cesspool that really is large amounts of userspace programming.
Instead, we have created our own, completely asynchronous core, giving us advanced multiprocessing
and concurrency capabilities, without either sacrificing portability or settling for some unhappy least
common denominator. This core is a robust foundation for NNG and handling the “Scalability
Protocols”, but if we’re being completely honest, we think this core has braod applicability for beyond
just the Scalability Protocols. It will be interesting to see if others come to the same conclusion.
Builting upon this robust foundation, we have engineered a substantial project, with capabilities far in
exceess of the original nanomsg, while still preserving compatibility with the the network protocols
that form the backbone of the nanomsg ecosystem, and even a compatible programming interface for
nanomsg library users. In addition to compatibility with nanomsg, we find that NNG has greatly
increased scalability, reliability, and usability (especially when developing concurrent applications).
NNG also has complete HTTP server and client implementations, support for TLS, and a plethora of
other capabilities. Much of this is made possible by a the aforementioned asynchronous I/O framework.
Preface
1
