From 9f13056f2f6a97652be6ef54869955676c39cf0e Mon Sep 17 00:00:00 2001 From: Jaylin Date: Sat, 8 Apr 2023 21:27:58 +0800 Subject: [PATCH 1/2] * UPDATE Readme --- README.adoc | 181 ---------------------------------------------------- README.md | 82 ++++++++++++++++++++++++ 2 files changed, 82 insertions(+), 181 deletions(-) delete mode 100644 README.adoc create mode 100644 README.md diff --git a/README.adoc b/README.adoc deleted file mode 100644 index a483dd780..000000000 --- a/README.adoc +++ /dev/null @@ -1,181 +0,0 @@ -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"] - -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 <> 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 <> 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 <> 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.]. diff --git a/README.md b/README.md new file mode 100644 index 000000000..ce2be57ba --- /dev/null +++ b/README.md @@ -0,0 +1,82 @@ + +[![Discord](https://img.shields.io/discord/931086341838622751?label=Discord&logo=discord)](https://discord.gg/xYGf3fQnES) +[![Twitter](https://img.shields.io/badge/Follow-EMQ-1DA1F2?logo=twitter)](https://twitter.com/EMQTech) +[![YouTube](https://img.shields.io/badge/Subscribe-EMQ-FF0000?logo=youtube)](https://www.youtube.com/channel/UC5FjR77ErAxvZENEWzQaO5Q) +[![Community](https://img.shields.io/badge/Community-NanoMQ-yellow?logo=github)](https://github.com/emqx/nanomq/discussions) +[![Build Status](https://img.shields.io/github/actions/workflow/status/emqx/NanoSDK/build_packages.yaml?branch=main&label=Build)](https://github.com/emqx/NanoSDK/actions) + +# NanoSDK C Client Library for the MQTT Protocol + +This repository contains the source code for the NanoSDK MQTT C client library. + +This project is a wrapping of the nanomsg-NNG(https://github.com/nanomsg/nng) +nanomsg known as https://github.com/nanomsg/nanomsg[libnanomsg], +and adds significant new capabilities like MQTT & QUIC while retaining +compatibility with the original Scalability Protocols. + +NOTE: In honor of NNG & Garrett(Creator & Maintainer), they are the cornerstone of NanoSDK. We respect all his contributions to the Open-Source world. And We create this repository only for tracking Issues/Discussions and fast-paced development while the MQTT support is missing in upstream. + + +# Introduction & Rationale + +NanoSDK is an open-source project jointly developed by EMQ and NNG. NanoSDK as a repository, it is maintained independently as the NNG version of NanoMQ (https://github.com/emqx/nanomq). At present, its master branch is a special version developed and optimized for MQTT workload and maintained independently, from which we have submitted several valuable PRs and Issues for NNG. +Therefore, to make NanoMQ compatible with NNG's SP protocol, we are committed to adding MQTT 3.1.1/5.0 protocol support for NNG at here. So that the two kinds of protocols(MQTT and SP) can be used together with NanoSDK. This is also in accordance with the RoadMap direction previously formulated by NanoMQ team. +According to the technical goals previously formulated with the NNG project maintainer - Garrett at the jointly open-source cooperation meeting, NNG will support ZeroMQ and MQTT 3.1.1/5.0 in the future. Before this really happens, this project will be maintained independently. The internal design of NanoSDK honors the programming style of the NNG framework and is compatible with the original SP protocol of NNG. At the same time, it does not affect the other features like HTTP/Websocket/TLS. + +## Advantages +Compared with other popular MQTT 3.1.1 SDK, NanoSDK has the following advantages: +1. Fully asynchronous I/O and good SMP support +NanoSDK based on NNG's asynchronous I/O, we implement the Actor-like programming model in C language. And managing to distribute the computation load among multiple CPU cores averagely. +2. High compatibility and portability +Inheriting the compatibility and easy portability of NNG, NanoSDK only relies on the native POSIX standard API and is friendly to various distributions of Linux. It can be migrated to any hardware and operating system platform easily. +3. Support multiple API styles +The programming style of the NNG framework comes with a high learning cost, and users need to have a deep understanding of the concept of AIO and Context. Therefore, we also prepared a traditional callback registration mechanism for users who are accustomed to using Paho and Mosquitto SDK. This not only reduces the programming difficulty but also reserves the advantages of NNG. +4. High throughput & Low latency +In NanoMQ's test report, its performance advantages of powerful high throughput and low latency have been reflected, and the direct successor of NanoMQ - the SDK also has excellent performance. It is cost-effective in terms of resources consumption. Unlike the traditional MQTT SDK which has only 1-2 threads, NanoSDK can make full use of system hardware resources to provide higher consumption throughput. +In most IoT solutions based on EMQX, the backend service’s insufficient consuming capability always results in message congestion, which has always been a problem for open source developers. Especially for QoS 1/2 messages, most SDKs reply Ack for QoS 1/2 messages synchronously. NanoSDK provides asynchronous Ack capability under the premise of ensuring the QoS message sequence and message retransmission mechanism, which greatly improves the throughput and consumption capacity of QoS 1/2. + +Inherited from NNG, NanoSDK is a performant & higly portable SDK. Which enable users create client application with high throughput. + +This code builds libraries which enable applications to connect to an [MQTT](http://mqtt.org) broker to publish messages, and to subscribe to topics and receive published messages. + +For MQTT broker introduction, please refer to EMQX (https://github.com/emqx/emqx) + +## Information About MQTT + +* [MQTT website](http://mqtt.org) +* [The MQTT 3.1.1 standard](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) +* [The MQTT 5.0 standard](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html) +* [OASIS Introduction to MQTT presentation](https://www.oasis-open.org/committees/download.php/49205/MQTT-OASIS-Webinar.pdf) + +## Libraries + +The NanoSDK C client comprises four variant libraries, shared or static: + + * nng/demo/mqtt- simple mqtt client + * nng/demo/mqtt_async - asynchronous MQTT client & command-linewith SSL/TLS (MQTTAsync) + * nng/demo/mqttv5- simple mqttv5 client with async API + * nng/demo/quic- simple MQTT over QUIC demo (Attention: MsQUIC needs to be installed) + +## API Documentation + +The API documentation is provided in Asciidoc format in the +`docs/man` subdirectory +The <> page is a good starting point. + +In addition, many users would like to add self-defined behavior in the callback of online and offline. Therefore, we modified the callback method of connection and disconnection to allow users to perform blocking and waiting operations in the callback without affecting the MQTT connection & pradigm itself, so as to improve the flexibility of NanoSDK. +However, it should be noted that this will consume the number of threads inside the NanoSDK. If the taskq thread is exhausted, it will still affect the operation of the entire client. Please use it cautiously. + +## Building with CMake + + ```bash + git clone https://github.com/emqx/NanoSDK ; cd NanoSDK + git submodule update --init --recursive + mkdir build && cd build + cmake -G Ninja .. + ninja + ``` +To enable MQTT over QUIC feature +```bash +-DNNG_ENABLE_QUIC=ON +``` + From a9ba2c2e8fc1849b8c018bb9ea5a811f64af1b8a Mon Sep 17 00:00:00 2001 From: Jaylin Date: Sat, 8 Apr 2023 21:33:12 +0800 Subject: [PATCH 2/2] * Add exchange link --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ce2be57ba..7ec1b36f9 100644 --- a/README.md +++ b/README.md @@ -43,11 +43,13 @@ For MQTT broker introduction, please refer to EMQX (https://github.com/emqx/emqx ## Information About MQTT +* [Learning MQTT](https://www.emqx.com/en/mqtt) +* [Realworld MQTT Applications](https://www.emqx.com/en/customers) * [MQTT website](http://mqtt.org) * [The MQTT 3.1.1 standard](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) * [The MQTT 5.0 standard](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html) * [OASIS Introduction to MQTT presentation](https://www.oasis-open.org/committees/download.php/49205/MQTT-OASIS-Webinar.pdf) - +* [MQTT Resources](https://www.emqx.com/en/resources) ## Libraries The NanoSDK C client comprises four variant libraries, shared or static: @@ -61,7 +63,7 @@ The NanoSDK C client comprises four variant libraries, shared or static: The API documentation is provided in Asciidoc format in the `docs/man` subdirectory -The <> page is a good starting point. +The `docs/man/libnng.3.adoc#,libnng(3)` page is a good starting point. In addition, many users would like to add self-defined behavior in the callback of online and offline. Therefore, we modified the callback method of connection and disconnection to allow users to perform blocking and waiting operations in the callback without affecting the MQTT connection & pradigm itself, so as to improve the flexibility of NanoSDK. However, it should be noted that this will consume the number of threads inside the NanoSDK. If the taskq thread is exhausted, it will still affect the operation of the entire client. Please use it cautiously.