Merge branch 'doc-updates' of git.lucina.net:libxs

4 files changed, 192 insertions, 0 deletions

diff --git a/NEWS b/NEWS
index e69de29..3ebe6b5 100644
--- a/NEWS
+++ b/NEWS
@@ -0,0 +1,57 @@
+Crossroads I/O Release Notes
+----------------------------
+
+This file documents the major changes in between releases of Crossroads
+I/O. For a detailed list of changes please refer to Git history, or the
+ChangeLog file included with your distribution of Crossroads.
+
+
+Release 1.0.0 (15 March 2012)
+-----------------------------
+
+Initial release.  Changes listed here are as compared to libzmq release
+3.1.
+
+New features:
+
+* The io_threads argument has been removed from xs_init(), and the default
+  number of I/O threads per context is now 1.
+* Context options added - see xs_setctxopt(3):
+  * The XS_IO_THREADS context option allows the user to specify the size of
+    the worker thread pool.
+  * The XS_MAX_SOCKETS context option allows the user to specify the
+    maximum number of sockets that can exist in parallel within a context.
+* Allow setting the source address for TCP connections - see xs_tcp(7).
+* ZeroMQ drop-in compatibility mode, enabled by the --enable-libzmq option
+  to configure. This is a binary compatible emulation of the ZeroMQ 2.1.11
+  API, for details see zmq(7).
+
+Bugfixes:
+
+* Fix pgm_receiver.cpp: zmq_assert (pending_bytes == 0). (LIBZMQ-205)
+* Fix assertion in pgm_sender_t::plug(). (LIBZMQ-303)
+* Race condition in zmq_term() fixed.
+* Message loss when a SUB socket disconnects fixed.
+* Fix data loss for PUB/SUB and unidirectional transports. (LIBZMQ-268)
+* Bug in linger implementation fixed.
+* Fix IPC transport domain socket stream file not being removed when
+  connection is closed.
+* Removal of pipe from dist_t fixed.
+* Only use AI_V4MAPPED if defined, and don't use it on FreeBSD.
+
+Optimisation:
+
+* Several optimisations to reduce the memory size of PUB/SUB subscription
+  map.
+* Avoid one extra call to poll() when there are no more data to send.
+
+Build:
+
+* MSVC build updated to use MSVC2010 instead of MSVC2008.
+* configure prints out a summary of XS configuration.
+
+Self tests:
+
+* Many more tests have been added, see the tests/ subdirectory.
+* The self tests can now be run from a MSVC build, see the "tests" project.
+
diff --git a/doc/Makefile.am b/doc/Makefile.am
index fcd1b4c..7cfc637 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -6,6 +6,10 @@ MAN3 = xs_bind.3 xs_close.3 xs_connect.3 xs_init.3 \
     xs_sendmsg.3 xs_recvmsg.3 xs_getmsgopt.3 xs_setctxopt.3
 MAN7 = xs.7 xs_tcp.7 xs_pgm.7 xs_inproc.7 xs_ipc.7
 
+if BUILD_LIBZMQ
+MAN7 += zmq.7
+endif
+
 MAN_DOC = $(MAN1) $(MAN3) $(MAN7)
 
 MAN_TXT = $(MAN3:%.3=%.txt)
diff --git a/doc/xs.txt b/doc/xs.txt
index 79a2443..93ff16a 100644
--- a/doc/xs.txt
+++ b/doc/xs.txt
@@ -175,11 +175,21 @@ used by C programmers. The intent is that programmers using Crossroads from
 other languages shall refer to this documentation alongside any documentation
 provided by the vendor of their language binding.
 
+
+ZEROMQ COMPATIBILITY
+--------------------
+The Crossroads library provides an optional drop-in 'libzmq' compatibility
+library for ZeroMQ applications.  If your version of Crossroads was built with
+the `--enable-libzmq` option, you can find the compatibility library
+documentation in linkxs:zmq[7].
+
+
 AUTHORS
 -------
 The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com>
 and Martin Lucina <martin@lucina.net>.
 
+
 COPYING
 -------
 Free use of Crossroads library is granted under the terms of the GNU Lesser
diff --git a/doc/zmq.txt b/doc/zmq.txt
new file mode 100644
index 0000000..f1e1abf
--- /dev/null
+++ b/doc/zmq.txt
@@ -0,0 +1,121 @@
+zmq(7)
+======
+
+
+NAME
+----
+zmq - Crossroads I/O ZeroMQ compatibility library
+
+
+SYNOPSIS
+--------
+*#include <zmq.h>*
+
+*cc* ['flags'] 'files' *-lzmq* ['libraries']
+
+
+DESCRIPTION
+-----------
+This 'libzmq' compatibility library is provided by the Crossroads I/O project
+as a transitional drop-in replacement for existing applications and language
+bindings written for the ZeroMQ library.
+
+The interfaces provided emulate those provided by ZeroMQ release 2.1.11, and
+binary compatibility is provided for ABI version 1.0.0.
+
+Existing applications can use these interfaces as a drop-in replacement for the
+ZeroMQ-provided 'libzmq' by installing the Crossroads version of this library
+in its place.
+
+Applications can also be recompiled against this library with no code or build
+system changes.
+
+IMPORTANT: The 'libzmq' compatibility library is an optional component of
+the Crossroads project, intended as a way to ease transition of existing
+applications and language bindings to the native 'libxs' interfaces, this
+feature will not be maintained indefinitely, hence developers are strongly
+encouraged to migrate their applications to 'libxs'.
+
+CONSTANTS
+---------
+
+All constants defined by the ZeroMQ 2.1.11 version of *<zmq.h>* are also
+defined in the Crossroads version.
+
+INTERFACES
+----------
+
+Context
+~~~~~~~
+[verse]
+*void *zmq_init (int 'io_threads');*
+*int zmq_term (void '*context');*
+
+
+Sockets
+~~~~~~~
+[verse]
+*void *zmq_socket (void '*context', int 'type');*
+*int zmq_close (void '*socket');*
+*int zmq_connect (void '*socket', const char '*endpoint');*
+*int zmq_bind (void '*socket', const char '*endpoint');*
+*int zmq_setsockopt (void '*socket', int 'option_name', const void '*option_value', size_t 'option_len');*
+*int zmq_getsockopt (void '*socket', int 'option_name', void '*option_value', size_t '*option_len');*
+*int zmq_poll (zmq_pollitem_t '*items', int 'nitems', long 'timeout');*
+
+
+Messages
+~~~~~~~~
+[verse]
+*int zmq_msg_init (zmq_msg_t '*msg');*
+*int zmq_msg_init_size (zmq_msg_t '*msg', size_t 'size');*
+*int zmq_msg_init_data (zmq_msg_t '*msg', void '*data', size_t 'size', zmq_free_fn '*ffn', void '*hint');*
+*int zmq_msg_close (zmq_msg_t '*msg');*
+*int zmq_msg_copy (zmq_msg_t '*dest', zmq_msg_t '*src');*
+*int zmq_msg_move (zmq_msg_t '*dest', zmq_msg_t '*src');*
+
+
+Sending and receiving
+~~~~~~~~~~~~~~~~~~~~~
+[verse]
+*int zmq_send (void '*socket', zmq_msg_t '*msg', int 'flags');*
+*int zmq_recv (void '*socket', zmq_msg_t '*msg', int 'flags');*
+
+
+Devices
+~~~~~~~
+[verse]
+*int zmq_device (int 'device', const void '*frontend', const void '*backend');*
+
+
+Error handling
+~~~~~~~~~~~~~~
+[verse]
+*int zmq_errno (void);*
+*const char *zmq_strerror (int 'errnum');*
+
+
+Version detection
+~~~~~~~~~~~~~~~~~
+[verse]
+*void zmq_version (int '*major', int '*minor', int '*patch');*
+
+NOTE: The version numbers returned by this function are the emulated ZeroMQ API
+version, i.e. 2.1.11.
+
+
+COPYING
+-------
+Free use of Crossroads library 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 Crossroads distribution.
+
+SEE ALSO
+--------
+linkxs:xs[7]
+
+
+AUTHORS
+-------
+The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com>
+and Martin Lucina <martin@lucina.net>.