Add conceptual overview doc.

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]