diff options
| -rw-r--r-- | docs/nng.adoc | 51 |
1 files changed, 48 insertions, 3 deletions
diff --git a/docs/nng.adoc b/docs/nng.adoc index e09cd014..44fc7c7c 100644 --- a/docs/nng.adoc +++ b/docs/nng.adoc @@ -65,9 +65,6 @@ Protocols * <<nng_respondent.adoc#,nng_respondent(7)>> - Respondent side of survey protocol * <<nng_surveyor.adoc#,nng_surveyor(7)>> - Surveyor side of survey protocol - -* <<nng_surveyor.adoc,nng_surveyor(7)>> - Survey/Respond protocol - Transports ~~~~~~~~~~ @@ -76,6 +73,54 @@ Transports * <<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] |