From 437db5a6c8348faa551a41b5ddb38072bd6924cb Mon Sep 17 00:00:00 2001 From: Martin Lucina Date: Thu, 29 Mar 2012 14:53:01 +0200 Subject: Documentation updates for 1.0.1 Signed-off-by: Martin Lucina --- NEWS | 42 +++++++++++++++++++++++++++++++++++------- README | 35 +++++++++++++++++++++++++++-------- doc/xs_getsockopt.txt | 16 ++++++++-------- doc/xs_setsockopt.txt | 15 +++++++-------- include/xs.h | 3 ++- 5 files changed, 79 insertions(+), 32 deletions(-) diff --git a/NEWS b/NEWS index 3ebe6b5..b484ba5 100644 --- a/NEWS +++ b/NEWS @@ -6,27 +6,55 @@ 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.1 (29 March 2012) +----------------------------- + +This is a bug fix release, with the only new addition being the XS_KEEPALIVE +socket option for enabling TCP keepalives. + +New features:: +* XS_KEEPALIVE options added + +Bugfixes:: +* Fix race condition in find_endpoint +* Small ommision in session creation mechanism +* Reconnect test fixed +* OpenVMS tests fixed +* Send identities on reconnect +* Make REQ session state machine aware of reconnections +* Error handling during connect +* Ignore distorted timeouts on Windows in debug mode +* Add long comment about security problem on Windows platform +* Signaler's global event is now accessible by everyone +* Handle duplicate identities decently +* wireformat test added +* Fixed issue LIBZMQ-345 - race condition in ctx.socket/term allows segfault +* Add missing header. +* Use strncpy() instead of strcpy(). +* Documentation updates. + + Release 1.0.0 (15 March 2012) ----------------------------- Initial release. Changes listed here are as compared to libzmq release 3.1. -New features: +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 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 + - 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: +Bugfixes:: * Fix pgm_receiver.cpp: zmq_assert (pending_bytes == 0). (LIBZMQ-205) * Fix assertion in pgm_sender_t::plug(). (LIBZMQ-303) @@ -39,18 +67,18 @@ Bugfixes: * Removal of pipe from dist_t fixed. * Only use AI_V4MAPPED if defined, and don't use it on FreeBSD. -Optimisation: +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: +Build:: * MSVC build updated to use MSVC2010 instead of MSVC2008. * configure prints out a summary of XS configuration. -Self tests: +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/README b/README index 25f36ed..0f9afe7 100644 --- a/README +++ b/README @@ -59,15 +59,33 @@ NOTE: Enabling this option will *overwrite* any existing installation of Reporting Bugs -------------- -To report a bug, sign up to the Crossroads I/O development discussion group -at and post a topic or send an email -describing your problem. +To report a bug, send an email describing your problem to the Crossroads +mailing list. To make sure your bug report won't be missed, you can file a +report in the bug tracker at . -Prefix the subject of your post with `[BUG]` to catch the developers -attention. +To help Crossroads developers to fix the bug, please try to provide a minimal +test program, ideally written in C, that reproduces the problem you are +reporting. -To ensure that your report is dealt with promptly, please attach a minimal -test case reproducing the bug, ideally written in C. +NOTE: The bug tracker exists primarily to track bugs and pertinent data (test +cases, crash logs, etc.). You should not use it for _discussion_. In the bug +tracker your audience will be very limited. Mailing list serves the purpose of +discussing bugs much better. + + +Contributing to the Project +--------------------------- + +Before contributing to the project make sure you understand the legal +implications of doing so. These are outlined on the Crossroads I/O website at +. + +To submit your contribution, send it as a patch (using git format-patch, diff, +or similar) to the mailing list. Make sure to use your real name, and prefix +the subject of your post with `[PATCH]`. + +All contributions will be reviewed and, if they pass review, accepted. For more +details refer to the website at . Resources @@ -81,7 +99,8 @@ mailing list. Vist to join or view archives of previous discussion. Extensive documentation is provided with the distribution. Refer to -doc/xs.html, or "man xs" after you have installed libxs on your system. +`doc/xs.html`, or the 'xs(7)' manual page after you have installed libxs on +your system. Further resources, language bindings, tutorials, and more can be found on the Crossroads website at . diff --git a/doc/xs_getsockopt.txt b/doc/xs_getsockopt.txt index c113f16..99d9376 100644 --- a/doc/xs_getsockopt.txt +++ b/doc/xs_getsockopt.txt @@ -121,7 +121,7 @@ XS_IDENTITY: Set socket identity ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The 'XS_IDENTITY' option shall retrieve the identity of the specified 'socket'. Socket identity is used only by request/reply pattern. Namely, it can be used -in tandem with ROUTER socket to route messages to the peer with specific +in tandem with a 'XS_XREP' socket to route messages to the peer with specific identity. Identity should be at least one byte and at most 255 bytes long. Identities @@ -338,7 +338,7 @@ hosts. Option value type:: int Option value unit:: boolean Default value:: 1 (true) -Applicable socket types:: all, when using TCP transports. +Applicable socket types:: all, when using TCP transport. XS_FD: Retrieve file descriptor associated with the socket @@ -390,18 +390,18 @@ Option value unit:: N/A (flags) Default value:: N/A Applicable socket types:: all -XS_KEEPALIVE: Use TCP keepalives -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When set to `1` TCP keepalives are enabled. This option can be used to prevent -the infrastructure (VPNs and similar) to terminate connections with no activity. -The keepalive period as such is normally a global OS setting. +XS_KEEPALIVE: Enable transport keepalives +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When set to `1`, this option enables use of protocol keepalives on the +'socket', if supported by the underlying transport protocol. [horizontal] Option value type:: int Option value unit:: boolean Default value:: 0 (false) -Applicable socket types:: all, when using TCP transports. +Applicable socket types:: all, when using TCP transport. RETURN VALUE diff --git a/doc/xs_setsockopt.txt b/doc/xs_setsockopt.txt index e9a7050..e07d9dd 100644 --- a/doc/xs_setsockopt.txt +++ b/doc/xs_setsockopt.txt @@ -126,7 +126,7 @@ XS_IDENTITY: Set socket identity ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The 'XS_IDENTITY' option shall set the identity of the specified 'socket'. Socket identity is used only by request/reply pattern. Namely, it can be used -in tandem with ROUTER socket to route messages to the peer with specific +in tandem with a 'XS_XREP' socket to route messages to the peer with specific identity. Identity should be at least one byte and at most 255 bytes long. Identities @@ -346,20 +346,19 @@ applications connect to and accept connections from both IPv4 and IPv6 hosts. Option value type:: int Option value unit:: boolean Default value:: 1 (true) -Applicable socket types:: all, when using TCP transports. +Applicable socket types:: all, when using TCP transport. -XS_KEEPALIVE: Use TCP keepalives -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +XS_KEEPALIVE: Enable transport keepalives +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When set to `1` TCP keepalives are enabled. This option can be used to prevent -the infrastructure (VPNs and similar) to terminate connections with no activity. -The keepalive period as such is normally a global OS setting. +When set to `1`, this option enables use of protocol keepalives on the +'socket', if supported by the underlying transport protocol. [horizontal] Option value type:: int Option value unit:: boolean Default value:: 0 (false) -Applicable socket types:: all, when using TCP transports. +Applicable socket types:: all, when using TCP transport. RETURN VALUE diff --git a/include/xs.h b/include/xs.h index b47358b..039d62f 100644 --- a/include/xs.h +++ b/include/xs.h @@ -158,7 +158,7 @@ XS_EXPORT int xs_setctxopt (void *context, int option, const void *optval, /* Crossroads socket definition. */ /******************************************************************************/ -/* Socket types. */ +/* Socket types. */ #define XS_PAIR 0 #define XS_PUB 1 #define XS_SUB 2 @@ -171,6 +171,7 @@ XS_EXPORT int xs_setctxopt (void *context, int option, const void *optval, #define XS_XPUB 9 #define XS_XSUB 10 +/* Legacy socket type aliases. */ #define XS_ROUTER XS_XREP #define XS_DEALER XS_XREQ -- cgit v1.2.3