Documentation rewrite

1 files changed, 137 insertions, 90 deletions

diff --git a/doc/zmq.txt b/doc/zmq.txt
index bc2571b..21722a7 100644
--- a/doc/zmq.txt
+++ b/doc/zmq.txt
@@ -9,59 +9,69 @@ zmq - 0MQ lightweight messaging kernel
 
 SYNOPSIS
 --------
-0MQ is an extension of POSIX sockets. It is a library that augments standard
-networking sockets by special capabilities that you can otherwise get only
-by using specialised "messaging middleware" products, such as automated
-handling of connections and disconnections, delivery of a message to multiple
-destinations, load balancing messages, sophisticated message filtering etc.
+*#include <zmq.h>*
 
-0MQ is designed to be extremely fast. Expected end-to-end latencies for
-messages passed over a LAN are in tens of microseconds. Expected
-throughputs are to be measured in millions of messages per second.
+*cc* ['flags'] 'files' *-lzmq* ['libraries']
 
-0MQ is designed to be very thin. It requires no more than couple of
-pages in resident memory and is thus well suited for any environment ranging
-from small embedded devices, routers and cell phones to enterprise-scale
-data centers.
 
-0MQ runs on a wide range of operating systems and supports variety of processor
-microarchitectures.
+DESCRIPTION
+-----------
+The 0MQ lightweight messaging kernel is a library which extends the standard
+socket interfaces with features traditionally provided by specialised
+_messaging middleware_ products. 0MQ sockets provide an abstraction of
+asynchronous  _message queues_, multiple _messaging patterns_, message
+filtering (_subscriptions_), seamless access to multiple _transport protocols_
+and more.
 
-0MQ is accessible from a large set of programming languages.
+This documentation presents an overview of 0MQ concepts, describes how 0MQ
+abstracts standard sockets and provides a reference manual for the functions
+provided by the 0MQ library.
 
-0MQ is fully open sourced LGPL-licensed software.
 
-
-CONTEXT
--------
-Each 0MQ socket lives within a specific context. Creating and destroying
-context is a counterpart of library initialisation/deinitialisation as used
-elsewhere. Ability to create multiple contexts saves the day when an application
-happens to link (indirectly and involuntarily) with several instances of 0MQ.
+Context
+~~~~~~~
+Before using any 0MQ library functions the caller must initialise a 0MQ
+'context' using _zmq_init()_. The following functions are provided to handle
+initialisation and termination of a 'context':
 
 Initialise 0MQ context::
     linkzmq:zmq_init[3]
 
-Uninitialise 0MQ context::
+Terminate 0MQ context::
     linkzmq:zmq_term[3]
 
 
-MESSAGES
---------
-Message is a discrete unit of data passed between applications or components
-of the same application. 0MQ message has no internal structure, it is an opaque
-BLOB. When writing data to or reading data from the message, you are free to
-use any of the many serialisation libraries available. Alternatively, you can
-use your own serialisation code. The latter option is especially useful when
-migrating legacy applications to 0MQ - there's no need to break existing
-message formats.
+Thread safety
+^^^^^^^^^^^^^
+A 0MQ 'context' is thread safe and may be shared among as many application
+threads as the application has requested using the _app_threads_ parameter to
+_zmq_init()_, without any additional locking required on the part of the
+caller.  Each 0MQ socket belonging to a particular 'context' may only be used
+by *the thread that created it* using _zmq_socket()_.
+
+
+Multiple contexts
+^^^^^^^^^^^^^^^^^
+Multiple 'contexts' may coexist within a single application. Thus, an
+application can use 0MQ directly and at the same time make use of any number of
+additional libraries or components which themselves make use of 0MQ as long as
+the above guidelines regarding thread safety are adhered to.
+
+
+Messages
+~~~~~~~~
+A 0MQ message is a discrete unit of data passed between applications or
+components of the same application. 0MQ messages have no internal structure and
+from the point of view of 0MQ itself they are considered to be opaque BLOBs.
+
+The following functions are provided to work with messages:
 
 Initialise a message::
     linkzmq:zmq_msg_init[3]
-    linkzmq:zmq_msg_size[3]
-    linkzmq:zmq_msg_data[3]
+    linkzmq:zmq_msg_init_size[3]
+    linkzmq:zmq_msg_init_data[3]
 
-Uninitialise a message::
+Release a message::
     linkzmq:zmq_msg_close[3]
 
 Access message content::
@@ -73,10 +83,21 @@ Message manipulation::
     linkzmq:zmq_msg_move[3]
 
 
-SOCKETS
--------
-0MQ sockets are very similar to POSIX sockets. See following manual pages to
-understand them in depth.
+Sockets
+~~~~~~~
+Standard sockets present a _synchronous_ interface to either connection-mode
+reliable byte streams (SOCK_STREAM), or connection-less unreliable datagrams
+(SOCK_DGRAM). In comparison, 0MQ sockets present an abstraction of a
+asynchronous _message queue_, with the exact queueing semantics depending on
+the socket type (_messaging pattern_) in use. See linkzmq:zmq_socket[3] for the
+_messaging patterns_ provided.
+
+0MQ sockets being _asynchronous_ means that the timings of the physical
+connection setup and teardown, reconnect and effective delivery are organized
+by 0MQ itself, and that messages may be _queued_ in the event that a peer is
+unavailable to receive them.
+
+The following functions are provided to work with sockets:
 
 Creating a socket::
     linkzmq:zmq_socket[3]
@@ -91,82 +112,108 @@ Establishing a message flow::
     linkzmq:zmq_bind[3]
     linkzmq:zmq_connect[3]
 
-Sending & receiving messages::
+Sending and receiving messages::
     linkzmq:zmq_send[3]
     linkzmq:zmq_flush[3]
     linkzmq:zmq_recv[3]
 
 
-MULTIPLEXING
-------------
-0MQ allows you to handle multiple sockets (0MQ as well as standard POSIX)
-in an asynchronous manner.
-
-Poll for I/O events::
-    linkzmq:zmq_poll[3]
-
+Input/output multiplexing
+^^^^^^^^^^^^^^^^^^^^^^^^^
+0MQ provides a mechanism for applications to multiplex input/output events over
+a set containing both 0MQ sockets and standard sockets. This mechanism mirrors
+the standard _poll()_ system call, and is described in detail in
+linkzmq:zmq_poll[3].
 
-ERROR HANDLING
---------------
-0MQ defines couple of non-POSIX error codes. Use following functions to handle
-them neatly.
-
-Convert error code into human readable string::
-    linkzmq:zmq_strerror[3]
 
+Transports
+~~~~~~~~~~
+A 0MQ socket can use multiple different underlying transport mechanisms.
+Each transport mechanism is suited to a particular purpose and has its own
+advantages and drawbacks.
 
-TRANSPORTS
-----------
-0MQ allows for using different underlying transport mechanisms (even multiple
-at once). Each transport mechanism has its own advantages and drawbacks. For
-detailed description of individual mechanisms check following manual pages:
+The following transport mechanisms are provided:
 
-TCP/IP transport::
+Unicast transport using TCP::
     linkzmq:zmq_tcp[7]
 
-UDP reliable multicast transport::
-    linkzmq:zmq_udp[7]
-
-PGM reliable multicast transport::
+Reliable multicast transport using PGM::
     linkzmq:zmq_pgm[7]
 
-Inter-process transport::
+Local inter-process communication transport::
     linkzmq:zmq_ipc[7]
 
-In-process (inter-thread) transport::
+Local in-process (inter-thread) communication transport::
     linkzmq:zmq_inproc[7]
 
 
-DEVICES
--------
-Aside of the messaging library (a.k.a. messaging kernel) 0MQ provides pre-built
-executables - devices - to serve as middle nodes in complex messaging
-topologies. For detailed description of individual devices check following
-manual pages:
+Devices
+~~~~~~~
+Apart from the 0MQ library the 0MQ distribution includes 'devices' which are
+building blocks intended to serve as intermediate nodes in complex messaging
+topologies.
 
-Forwarder device for PUB/SUB messaging::
+The following devices are provided:
+
+Forwarder device for request-response messaging::
+    linkzmq:zmq_queue[1]
+
+Forwarder device for publish-subscribe messaging::
     linkzmq:zmq_forwarder[1]
 
-Streamer device for UPSTREAM/DOWNSTREAM messaging::
+Streamer device for parallelized pipeline messaging::
     linkzmq:zmq_streamer[1]
 
-Forwarder device for REQ/REP messaging::
-    linkzmq:zmq_queue[1]
 
+ERROR HANDLING
+--------------
+The 0MQ library functions handle errors using the standard conventions found on
+POSIX systems. Generally, this means that upon failure a 0MQ library function
+shall return either a NULL value (if returning a pointer) or a negative value
+(if returning an integer), and the actual error code shall be stored in the
+'errno' variable.
+
+A _zmq_strerror()_ function is provided to translate 0MQ-specific error codes
+into error message strings. For further details refer to
+linkzmq:zmq_strerror[3].
+
+
+LANGUAGE BINDINGS
+-----------------
+The 0MQ library provides interfaces suitable for calling from programs in any
+language; this documentation documents those interfaces as they would be used
+by C programmers. The intent is that programmers using 0MQ from other languages
+shall refer to this documentation alongside any documentation provided by the
+vendor of their language binding.
 
-LANGUAGES
----------
-0MQ manual pages provide info on C API. To find out how the your
-favourite language API maps to C API and thus how to find relevant manual pages,
-see following articles:
 
-$$C++$$::
-    linkzmq:zmq_cpp[7]
+C++ language binding
+~~~~~~~~~~~~~~~~~~~~
+The 0MQ distribution includes a $$C++$$ language binding, which is documented
+separately in linkzmq:zmq_cpp[7].
 
-Java::
-    linkzmq:zmq_java[7]
 
+Other language bindings
+~~~~~~~~~~~~~~~~~~~~~~~
+Other language bindings (Python, Ruby, Java and more) are provided by members
+of the 0MQ community and pointers can be found on the 0MQ website.
 
-AUTHOR
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
+
+
+RESOURCES
+---------
+Main web site: <http://www.zeromq.org/>
+
+Report bugs to the 0MQ development mailing list: <zeromq-dev@lists.zeromq.org>
+
+
+COPYING
+-------
+Free use of this software is granted under the terms of the GNU Lesser General
+Public License (LGPL). For details see the files `COPYING` and `COPYING.LESSER`
+included with the 0MQ distribution.