From 8f900246497abcb6d233615ceba9712e67520651 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 13 Oct 2024 14:32:55 -0700 Subject: mdbook: Add some front matter material. --- docs/ref/SUMMARY.md | 4 ++ docs/ref/copyright.md | 45 ++++++++++++++++ docs/ref/dedication.md | 5 ++ docs/ref/img/staysail-bw-trans.svg | 9 ++++ docs/ref/preface.md | 107 +++++++++++++++++++++++++++++++++++++ 5 files changed, 170 insertions(+) create mode 100644 docs/ref/copyright.md create mode 100644 docs/ref/dedication.md create mode 100644 docs/ref/img/staysail-bw-trans.svg create mode 100644 docs/ref/preface.md (limited to 'docs/ref') diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index 59614493..7079144f 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -1,5 +1,9 @@ # Summary +[Copyright](./copyright.md) +[Dedication](./dedication.md) +[Preface](./preface.md) + - [API Reference](./api/index.md) - [Messages](./api/msg/index.md) diff --git a/docs/ref/copyright.md b/docs/ref/copyright.md new file mode 100644 index 00000000..5a52a4ce --- /dev/null +++ b/docs/ref/copyright.md @@ -0,0 +1,45 @@ + + +Copyright © 2024 Staysail Systems, Inc.\ +San Marcos, California, United States of America + +> If you find this book or NNG useful, please consider sponsoring +> the project. + +> [!TIP] +> This book is a work in progress, adapted from earlier sources +> and updated for the current version of NNG. + +> [!NOTE] +> +> > This document is supplied under the terms of the MIT License, a +> > copy of which should be located in the distribution where this +> > file was obtained (LICENSE.txt), and reproduced below. +> +> > Third party contributions to this document were made under the +> > same license terms, and may be covered under one of the following +> > copyrights: +> > +> > - Copyright 2018 Capitar IT Group BV. +> > - Copyright 2019 Devolutions. +> > - Copyright 2020 Dirac Research. + +## The MIT License + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), +to deal in the Software without restriction, including without limitation +the rights to use, copy, modify, merge, publish, distribute, sublicense, +and/or sell copies of the Software, and to permit persons to whom +the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS +IN THE SOFTWARE. diff --git a/docs/ref/dedication.md b/docs/ref/dedication.md new file mode 100644 index 00000000..9a0e694f --- /dev/null +++ b/docs/ref/dedication.md @@ -0,0 +1,5 @@ +# Dedication + +--- _For Jenichka_ + +_The sun always shines when you are home._ diff --git a/docs/ref/img/staysail-bw-trans.svg b/docs/ref/img/staysail-bw-trans.svg new file mode 100644 index 00000000..35f126f3 --- /dev/null +++ b/docs/ref/img/staysail-bw-trans.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/docs/ref/preface.md b/docs/ref/preface.md new file mode 100644 index 00000000..67d018f1 --- /dev/null +++ b/docs/ref/preface.md @@ -0,0 +1,107 @@ +# Preface + +> [!IMPORTANT] +> This is a _DRAFT_ version of this reference manual, +> and much is still in progress. There may be errors, +> and large omissions as content is still be moved from +> the previous ASCIIDOCTOR format and updated for NNG 2.0. + +## Preface for the First Edition + +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. + +We've tried to stay true to the core nanomsg goals about being light-weight, +liberally licensed, and implemented in C. +(After all, those were the things that drew us to nanomsg in the first place!) +In addition we added a couple of new ones. +Specifically, reliability, performance, and extensibility (in that order) +were added as core goals for the project. + +We believe that NNG represents a substantial step forward over other +messaging frameworks, and have enjoyed creating it. +We hope you find it useful. +There is still a lot more we want to do, and future release of NNG +will continue to expand it's capabilities. +We're just getting started. + +**--- Garrett D'Amore**, May 30, 2018 + +## Acknowledgements + +We would like to thank Janjaap Bos, at Capitar IT Group BV. +Without his patronage, neither NNG nor this book would be possible. + +We would also like thank Martin Sústrik for creating the original +nanomsg project, the foundation upon which all of this work is based. + +And certainly not least of all, we would like to thank the various +members of the community who have followed +and supported the NNG project in so many different ways. + +### Conventions + +Throughout this book there are occasional warnings, notices, and tips. +These are visually distinguished as follows: + +> [!TIP] +> Tips are things that the reader may find useful, such as suggestions +> for use or tim saving hints. + +> [!NOTE] +> Notes are things that the reader should be aware of, and provide +> additional information or context that may aid in the understanding +> or use of the topic. + +> [!IMPORTANT] +> Warnings are used to denote important cautionary advice, +> which should be carefully heeded. +> Ignoring such advice may lead to crashses, unexpected behavior, +> loss of revenue, or other undesirable conditions. -- cgit v1.2.3-70-g09d2