diff options
Diffstat (limited to 'docs/nng.adoc')
| -rw-r--r-- | docs/nng.adoc | 154 |
1 files changed, 0 insertions, 154 deletions
diff --git a/docs/nng.adoc b/docs/nng.adoc deleted file mode 100644 index 2d0f6567..00000000 --- a/docs/nng.adoc +++ /dev/null @@ -1,154 +0,0 @@ -= nng(7) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng - nanomsg next generation - -== SYNOPSIS - -*cc* ['flags'] 'files' *-lnng* ['libraries'] - -== DESCRIPTION - -The _nng_ library provides a common messaging framework intended to -solve common communication problems in distributed applications. -It offers a number of _protocols_, and also a number of _transports_. - -The _protocols_ implement the semantics associated with particular -communications scenarios, such as RPC style services, service discovery, -publish/subscribe, and so forth. - -The _transports_ provide support for underlying transport methods, such -as TCP, IPC, websockets, and so forth. - -The _nng_ library is designed to permit easy creation of new _transports_ and, -to a lesser extent, new _protocols_. - -The _nng_ library is wire compatible with the SP protocols described in -the nanomsg project; projects using -https://github.com/nanomsg/nanomsg[_libnanomsg_] can inter-operate with -nng as well as other conforming implementations. (One such implementation -is https://github.com/go-mangos/mangos[_mangos_].) Applications using _nng_ -which wish to communicate with older libraries must ensure that they only -use protocols or transports offered by the earlier library. - -The _nng_ library also offers a compatible API, permitting legacy code to -be recompiled or relinked against _nng_. When doing this, support for -certain enhancements or features will likely be absent, requiring the -application developer to use the new-style API. - -The _nng_ library is implemented in pure C; if you need bindings for -other languages please check the http://nanomsg.org/[website]. - -== Protocols - -* <<nng_bus#,nng_bus(7)>> - Bus protocol -* <<nng_pair#,nng_pair(7)>> - Pair protocol -* <<nng_pub#,nng_pub(7)>> - Publisher side of publish/subscribe protocol -* <<nng_pull#,nng_pull(7)>> - Pull side of pipeline protocol -* <<nng_push#,nng_push(7)>> - Push side of pipeline protocol -* <<nng_sub#,nng_sub(7)>> - Subscriber side of publish/subscribe protocol -* <<nng_rep#,nng_rep(7)>> - Reply side of request/reply protocol -* <<nng_req#,nng_req(7)>> - Request side of request/reply protocol -* <<nng_respondent#,nng_respondent(7)>> - Respondent side of survey protocol -* <<nng_surveyor#,nng_surveyor(7)>> - Surveyor side of survey protocol - -== Transports - -* <<nng_inproc#,nng_inproc(7)>> - Intra-process transport -* <<nng_ipc#,nng_ipc(7)>> - Inter-process transport -* <<nng_tls#,nng_tls(7)>> - TLSv1.2 over TCP transport -* <<nng_tcp#,nng_tcp(7)>> - TCP (and TCPv6) transport -* <<nng_ws#,nng_ws(7)>> - WebSocket transport -* <<nng_zerotier#,nng_zerotier(7)>> - ZeroTier transport - -== Conceptual Overview - -_nng_ presents a _socket_ view of networking. The sockets are constructed -using protocol-specific functions, as a given socket implements precisely -one _nng_ protocol. - -Each socket can be used to send and receive messages (if the protocol) -supports it, and implements the appropriate protocol semantics. For -example, <<nng_sub#,nng_sub(7)>> sockets automatically filter incoming -messages to discard those for topics that have not been subscribed. - -_nng_ sockets are message oriented, so that messages are either delivered -wholly, or not at all. Partial delivery is not possible. Furthermore, -_nng_ does not provide any other delivery or ordering guarantees; -messages may be dropped or reordered. (Some protocols, such as -<<nng_req#,nng_req(7)>> may offer stronger guarantees by -performing their own retry and validation schemes.) - -Each socket can have zero, one, or many "endpoints", which are either -_listeners_ or _dialers_. (A given socket may freely choose whether it uses -listeners, dialers, or both.) These "endpoints" provide access to -underlying transports, such as TCP, etc. - -Each endpoint is associated with a URL, which is a service address. For -dialers, this will be the service address that will be contacted, whereas -for listeners this is where the listener will bind and watch for new -connections. - -Endpoints do not themselves transport data. They are instead responsible -for the creation of _pipes_, which can be thought of as message-oriented, -connected, streams. Pipes frequently correspond to a single underlying -byte stream -- for example both IPC and TCP transports implement their -pipes using a 1:1 relationship with a connected socket. - -Endpoints create pipes as needed. Listeners will create them when a new -client connection request arrives, and dialers will generally create one, -then wait for it to disconnect before reconnecting. - -Most applications should not have to worry about endpoints or pipes at -all; the socket abstraction should provide all the functionality needed -other than in a few specific circumstances. - -=== URLs - -The _nng_ library uses universal resource locators (URLs) -following the format specified in -https://tools.ietf.org/html/rfc3986[RFC 3986], -including some schemes that are unique -to SP. -The URLs used in _nng_ are canonicalized as follows, mostly in -accordance with -https://tools.ietf.org/html/rfc3986#section-6.2.2[RFC 3986 6.2.2]: - - . The URL is parsed into scheme, userinfo, host, port, path, query and - fragment components. (Not all of these members are necessarily present.) - . The scheme, hostname, and port if present, are converted to lower case. - . Percent-encoded values for - https://tools.ietf.org/html/rfc3986#section-2.3[unreserved characters] - converted to their unencoded forms. - . Additionally URL percent-encoded values for characters in the path - and with numeric values larger than 127 (i.e. not ASCII) are decoded. - . The resulting path is checked for invalid UTF-8 sequences, consisting - of surrogate pairs, illegal byte sequences, or overlong encodings. - If this check fails, then the entire URL is considered invalid. - . Path segments consisting of `.` and `..` are resolved as per - https://tools.ietf.org/html/rfc3986#section-6.2.2.3[RFC 3986 6.2.2.3]. - . Further, empty path segments are removed, meaning that duplicate - slash (`/`) separators are removed from the path. - -Note that steps 4, 5, and 7 are not specified by RFC 3986, but performing -them is believed to improve both the usability and security of _nng_ -applications, without violating RFC 3986 itself. - -== API - -The library API is documented at <<libnng#,libnng(3)>>. - -== SEE ALSO - -<<libnng#,libnng(3)>>, -<<nng_compat#,nng_compat(3)>> |