1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
|
nng(7)
======
:doctype: manpage
:manmanual: nng
:mansource: nng
:icons: font
:copyright: Copyright 2017 Garrett D'Amore <garrett@damore.org> \
Copyright 2017 Capitar IT Group BV <info@capitar.com> \
This software 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.adoc#,nng_bus(7)>> - Bus protocol
* <<nng_pair.adoc#,nng_pair(7)>> - Pair protocol
* <<nng_pub.adoc#,nng_pub(7)>> - Publisher side of publish/subscribe protocol
* <<nng_sub.adoc#,nng_sub(7)>> - Subscriber side of publish/subscribe protocol
* <<nng_rep.adoc#,nng_rep(7)>> - Reply side of request/reply protocol
* <<nng_req.adoc#,nng_req(7)>> - Request side of request/reply protocol
* <<nng_respondent.adoc#,nng_respondent(7)>> - Respondent side of survey protocol
* <<nng_surveyor.adoc#,nng_surveyor(7)>> - Surveyor side of survey protocol
Transports
~~~~~~~~~~
* <<nng_inproc.adoc#,nng_inproc(7)>> - Intra-process transport
* <<nng_ipc.adoc#,nng_ipc(7)>> - Inter-process transport
* <<nng_tcp.adoc#,nng_tcp(7)>> - TCP (and TCPv6) transport
* <<nng_zerotier.adoc#,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.adoc#,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.adoc#,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.
API
~~~
The library API is documented at <<libnng.adoc#,libnng(3)>>.
AUTHORS
-------
link:mailto:garrett@damore.org[Garrett D'Amore]
SEE ALSO
--------
<<nng_compat.adoc#,nng_compat(3)>>
COPYRIGHT
---------
Copyright 2017 mailto:garrett@damore.org[Garrett D'Amore] +
Copyright 2017 mailto:info@capitar.com[Capitar IT Group BV]
This document is supplied under the terms of the
https://opensource.org/licenses/LICENSE.txt[MIT License].
|
