183 lines
7.9 KiB
Text
183 lines
7.9 KiB
Text
ifdef::env-github[]
|
|
:note-caption: :information_source:
|
|
:important-caption: :heavy_exclamation_mark:
|
|
endif::[]
|
|
= nng - nanomsg-next-gen
|
|
|
|
// Note: This README is optimized for display with Asciidoctor, or
|
|
// on the github status page. An HTML version is in the same directory
|
|
// and may be more pleasantly formatted for human readers (when opened
|
|
// in a browser).
|
|
|
|
// Note: If you're updating this file, don't forget to re-run asciidoctor
|
|
// to update the aforementioned HTML file!
|
|
|
|
image:https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg[Stand With Ukraine,link="https://stand-with-ukraine.pp.ua"]
|
|
image:https://img.shields.io/github/actions/workflow/status/nanomsg/nng/linux.yml?branch=master&logoColor=grey&logo=ubuntu&label=[Linux Status,link="https://github.com/nanomsg/nng/actions"]
|
|
image:https://img.shields.io/github/actions/workflow/status/nanomsg/nng/windows.yml?branch=master&logoColor=grey&logo=windows&label=[Windows Status,link="https://github.com/nanomsg/nng/actions"]
|
|
image:https://img.shields.io/github/actions/workflow/status/nanomsg/nng/darwin.yml?branch=master&logoColor=grey&logo=apple&label=[macOS Status,link="https://github.com/nanomsg/nng/actions"]
|
|
image:https://img.shields.io/codecov/c/github/nanomsg/nng?logo=codecov&logoColor=grey&label=[Coverage,link="https://codecov.io/gh/nanomsg/nng"]
|
|
image:https://img.shields.io/discord/639573728212156478?label=&logo=discord[Discord,link="https://discord.gg/Xnac6b9"]
|
|
image:https://img.shields.io/static/v1?label=&message=docs&logo=asciidoctor&logoColor=silver&color=blue[Manual,link="https://nng.nanomsg.org/man"]
|
|
image:https://img.shields.io/github/license/nanomsg/nng.svg?logoColor=silver&logo=open-source-initiative&label=&color=blue[MIT License,link="https://github.com/nanomsg/nng/blob/master/LICENSE.txt"]
|
|
image:https://img.shields.io/github/v/tag/nanomsg/nng.svg?logo=github&label=[Latest version,link="https://github.com/nanomsg/nng/releases"]
|
|
|
|
Please see <<UKRAINE#,here>> for an important message for the people of Russia.
|
|
|
|
NOTE: If you are looking for the legacy version of nanomsg, please
|
|
see the https://github.com/nanomsg/nanomsg[nanomsg] repository.
|
|
|
|
This project is a rewrite of the Scalability Protocols
|
|
library known as https://github.com/nanomsg/nanomsg[libnanomsg],
|
|
and adds significant new capabilities, while retaining
|
|
compatibility with the original.
|
|
|
|
It may help to think of this as "nanomsg-next-generation".
|
|
|
|
== NNG: Lightweight Messaging Library
|
|
|
|
NNG, like its predecessors http://nanomsg.org[nanomsg] (and to some extent
|
|
http://zeromq.org/[ZeroMQ]), is a lightweight, broker-less library,
|
|
offering a simple API to solve common recurring messaging problems,
|
|
such as publish/subscribe, RPC-style request/reply, or service discovery.
|
|
The API frees the programmer from worrying about details like connection
|
|
management, retries, and other common considerations, so that they
|
|
can focus on the application instead of the plumbing.
|
|
|
|
NNG is implemented in C, requiring only C99 and CMake to build.
|
|
It can be built as a shared or a static library, and is readily
|
|
embeddable. It is also designed to be easy to port to new platforms
|
|
if your platform is not already supported.
|
|
|
|
== License
|
|
|
|
NNG is licensed under a liberal, and commercial friendly, MIT license.
|
|
The goal to the license is to minimize friction in adoption, use, and
|
|
contribution.
|
|
|
|
== Enhancements (Relative to nanomsg)
|
|
|
|
Here are areas where this project improves on "nanomsg":
|
|
|
|
[horizontal]
|
|
*Reliability*:: NNG is designed for production use from the beginning. Every
|
|
error case is considered, and it is designed to avoid crashing except in cases
|
|
of gross developer error. (Hopefully we don't have any of these in our own
|
|
code.)
|
|
|
|
*Scalability*:: NNG scales out to engage multiple cores using a bespoke
|
|
asynchronous I/O framework, using thread pools to spread load without
|
|
exceeding typical system limits.
|
|
|
|
*Maintainability*:: NNG's architecture is designed to be modular and
|
|
easily grasped by developers unfamiliar with the code base. The code
|
|
is also well documented.
|
|
|
|
*Extensibility*:: Because it avoids ties to file descriptors, and avoids
|
|
confusing interlocking state machines, it is easier to add new protocols
|
|
and transports to NNG. This was demonstrated by the addition of the
|
|
TLS and ZeroTier transports.
|
|
|
|
*Security*:: NNG provides TLS 1.2 and ZeroTier transports, offering
|
|
support for robust and industry standard authentication and encryption.
|
|
In addition, it is hardened to be resilient against malicious attackers,
|
|
with special consideration given to use in a hostile Internet.
|
|
|
|
*Usability*:: NNG eschews slavish adherence parts of the more complex and
|
|
less well understood POSIX APIs, while adopting the semantics that are
|
|
familiar and useful. New APIs are intuitive, and the optional support
|
|
for separating protocol context and state from sockets makes creating
|
|
concurrent applications vastly simpler than previously possible.
|
|
|
|
== Compatibility
|
|
|
|
This project offers both wire compatibility and API compatibility,
|
|
so most nanomsg users can begin using NNG right away.
|
|
|
|
Existing nanomsg and https://github.com/nanomsg/mangos[mangos] applications
|
|
can inter-operate with NNG applications automatically.
|
|
|
|
That said, there are some areas where legacy nanomsg still offers
|
|
capabilities NNG lacks -- specifically enhanced observability with
|
|
statistics, and tunable prioritization of different destinations
|
|
are missing, but will be added in a future release.
|
|
|
|
Additionally, some API capabilities that are useful for foreign
|
|
language bindings are not implemented yet.
|
|
|
|
Some simple single threaded, synchronous applications may perform better under
|
|
legacy nanomsg than under NNG. (We believe that these applications are the
|
|
least commonly deployed, and least interesting from a performance perspective.
|
|
NNG's internal design is slightly less efficient in such scenarios, but it
|
|
greatly benefits when concurrency or when multiple sockets or network peers
|
|
are involved.)
|
|
|
|
== Supported Platforms
|
|
|
|
NNG supports Linux, macOS, Windows (Vista or better), illumos, Solaris,
|
|
FreeBSD, Android, and iOS. Most other POSIX platforms should work out of
|
|
the box but have not been tested. Very old versions of otherwise supported
|
|
platforms might not work.
|
|
|
|
== Requirements
|
|
|
|
To build this project, you will need a C99 compatible compiler and
|
|
http://www.cmake.org[CMake] version 3.13 or newer.
|
|
|
|
We recommend using the https://ninja-build.org[Ninja] build
|
|
system (pass "-G Ninja" to CMake) when you can.
|
|
(And not just because Ninja sounds like "NNG" -- it's also
|
|
blindingly fast and has made our lives as developers measurably better.)
|
|
|
|
If you want to build with TLS support you will also need
|
|
https://tls.mbed.org[mbedTLS]. See <<docs/BUILD_TLS.adoc#>> for details.
|
|
|
|
== Quick Start
|
|
|
|
With a Linux or UNIX environment:
|
|
|
|
[source,sh]
|
|
----
|
|
$ mkdir build
|
|
$ cd build
|
|
$ cmake -G Ninja ..
|
|
$ ninja
|
|
$ ninja test
|
|
$ ninja install
|
|
----
|
|
|
|
== API Documentation
|
|
|
|
The API documentation is provided in Asciidoc format in the
|
|
`docs/man` subdirectory, and also
|
|
https://nanomsg.github.io/nng[online].
|
|
The <<docs/man/libnng.3.adoc#,libnng(3)>> page is a good starting point.
|
|
|
|
You can also purchase a copy of the
|
|
http://staysail.tech/books/nng_reference/index.html[__NNG Reference Manual__].
|
|
(It is published in both electronic and printed formats.)
|
|
Purchases of the book help fund continued development of NNG.
|
|
|
|
== Example Programs
|
|
|
|
Some demonstration programs have been created to help serve as examples.
|
|
These are located in the `demo` directory.
|
|
|
|
== Legacy Compatibility
|
|
|
|
A legacy libnanomsg compatible API is available, and while it offers
|
|
less capability than the modern NNG API, it may serve as a transition aid.
|
|
Please see <<docs/man/nng_compat.3compat.adoc#,nng_compat(3)>> for details.
|
|
|
|
== Commercial Support
|
|
|
|
Commercial support for NNG is available.
|
|
|
|
Please contact mailto:info@staysail.tech[Staysail Systems, Inc.] to
|
|
inquire further.
|
|
|
|
== Commercial Sponsors
|
|
|
|
The development of NNG has been made possible through the generous
|
|
sponsorship of https://www.capitar.com[Capitar IT Group BV] and
|
|
http://staysail.tech[Staysail Systems, Inc.].
|