deprecate zmq_ctx_destroy in favor of zmq_ctx_term

in order to avoid logical collisions with pre-existing notions of context destruction in bindings (czmq, pyzmq).

builds/redhat/zeromq.spec.in

@@ -113,6 +113,7 @@ This package contains ZeroMQ related development libraries and header files.
 %{_mandir}/man3/zmq_ctx_get.3.gz
 %{_mandir}/man3/zmq_ctx_new.3.gz
 %{_mandir}/man3/zmq_ctx_set.3.gz
+%{_mandir}/man3/zmq_ctx_term.3.gz
 %{_mandir}/man3/zmq_msg_recv.3.gz
 %{_mandir}/man3/zmq_errno.3.gz
 %{_mandir}/man3/zmq_getsockopt.3.gz

doc/Makefile.am

 MAN3 = zmq_bind.3 zmq_unbind.3 zmq_connect.3 zmq_disconnect.3 zmq_close.3 \
-    zmq_ctx_new.3 zmq_ctx_destroy.3 zmq_ctx_get.3 zmq_ctx_set.3 \
+    zmq_ctx_new.3 zmq_ctx_term.3 zmq_ctx_destroy.3 zmq_ctx_get.3 zmq_ctx_set.3 \
     zmq_msg_init.3 zmq_msg_init_data.3 zmq_msg_init_size.3 \
     zmq_msg_move.3 zmq_msg_copy.3 zmq_msg_size.3 zmq_msg_data.3 zmq_msg_close.3 \
     zmq_msg_send.3 zmq_msg_recv.3 \

doc/zmq.txt

@@ -42,7 +42,7 @@ Work with context properties::
     linkzmq:zmq_ctx_get[3]
 
 Destroy a 0MQ context::
-    linkzmq:zmq_ctx_destroy[3]
+    linkzmq:zmq_ctx_term[3]
 
 Monitor a 0MQ context::
     linkzmq:zmq_ctx_set_monitor[3]

doc/zmq_ctx_destroy.txt

@@ -4,7 +4,7 @@ zmq_ctx_destroy(3)
 
 NAME
 ----
-zmq_ctx_destroy - destroy a 0MQ context
+zmq_ctx_destroy - terminate a 0MQ context
 
 
 SYNOPSIS
@@ -36,7 +36,7 @@ Context termination is performed in the following steps:
 For further details regarding socket linger behavior refer to the _ZMQ_LINGER_
 option in linkzmq:zmq_setsockopt[3].
 
-This function replaces the deprecated function linkzmq:zmq_term[3].
+This function is deprecated by linkzmq:zmq_ctx_term[3].
 
 
 RETURN VALUE

doc/zmq_ctx_new.txt

@@ -41,7 +41,7 @@ SEE ALSO
 linkzmq:zmq[7]
 linkzmq:zmq_ctx_set[3]
 linkzmq:zmq_ctx_get[3]
-linkzmq:zmq_ctx_destroy[3]
+linkzmq:zmq_ctx_term[3]
 
 
 AUTHORS

doc/zmq_ctx_term.txt

+zmq_ctx_term(3)
+==================
+
+
+NAME
+----
+zmq_ctx_term - destroy a 0MQ context
+
+
+SYNOPSIS
+--------
+*int zmq_ctx_term (void '*context');*
+
+
+DESCRIPTION
+-----------
+The _zmq_ctx_term()_ function shall destroy the 0MQ context 'context'.
+
+Context termination is performed in the following steps:
+
+1. Any blocking operations currently in progress on sockets open within
+   'context' shall return immediately with an error code of ETERM.  With the
+   exception of _zmq_close()_, any further operations on sockets open within
+   'context' shall fail with an error code of ETERM.
+
+2. After interrupting all blocking calls, _zmq_ctx_term()_ shall _block_ until the
+   following conditions are satisfied:
+
+   * All sockets open within 'context' have been closed with _zmq_close()_.
+
+   * For each socket within 'context', all messages sent by the application
+     with _zmq_send()_ have either been physically transferred to a network
+     peer, or the socket's linger period set with the _ZMQ_LINGER_ socket
+     option has expired.
+
+For further details regarding socket linger behavior refer to the _ZMQ_LINGER_
+option in linkzmq:zmq_setsockopt[3].
+
+This function replaces the deprecated function linkzmq:zmq_term[3].
+
+
+RETURN VALUE
+------------
+The _zmq_ctx_term()_ function shall return zero if successful. Otherwise
+it shall return `-1` and set 'errno' to one of the values defined below.
+
+
+ERRORS
+------
+*EFAULT*::
+The provided 'context' was invalid.
+*EINTR*::
+Termination was interrupted by a signal. It can be restarted if needed.
+
+
+SEE ALSO
+--------
+linkzmq:zmq[7]
+linkzmq:zmq_init[3]
+linkzmq:zmq_close[3]
+linkzmq:zmq_setsockopt[3]
+
+
+AUTHORS
+-------
+This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>

doc/zmq_term.txt

@@ -36,7 +36,7 @@ Context termination is performed in the following steps:
 For further details regarding socket linger behaviour refer to the _ZMQ_LINGER_
 option in linkzmq:zmq_setsockopt[3].
 
-This function is deprecated by linkzmq:zmq_ctx_destroy[3].
+This function is deprecated by linkzmq:zmq_ctx_term[3].
 
 RETURN VALUE
 ------------

include/zmq.h

@@ -163,13 +163,14 @@ ZMQ_EXPORT const char *zmq_strerror (int errnum);
 #define ZMQ_MAX_SOCKETS_DFLT 1024
 
 ZMQ_EXPORT void *zmq_ctx_new (void);
-ZMQ_EXPORT int zmq_ctx_destroy (void *context);
+ZMQ_EXPORT int zmq_ctx_term (void *context);
 ZMQ_EXPORT int zmq_ctx_set (void *context, int option, int optval);
 ZMQ_EXPORT int zmq_ctx_get (void *context, int option);
 
 /*  Old (legacy) API                                                          */
 ZMQ_EXPORT void *zmq_init (int io_threads);
 ZMQ_EXPORT int zmq_term (void *context);
+ZMQ_EXPORT int zmq_ctx_destroy (void *context);
 
 
 /******************************************************************************/

src/zmq.cpp

@@ -163,7 +163,7 @@ void *zmq_ctx_new (void)
     return ctx;
 }
 
-int zmq_ctx_destroy (void *ctx_)
+int zmq_ctx_term (void *ctx_)
 {
     if (!ctx_ || !((zmq::ctx_t*) ctx_)->check_tag ()) {
         errno = EFAULT;
@@ -225,7 +225,12 @@ void *zmq_init (int io_threads_)
 
 int zmq_term (void *ctx_)
 {
-    return zmq_ctx_destroy (ctx_);
+    return zmq_ctx_term (ctx_);
+}
+
+int zmq_ctx_destroy (void *ctx_)
+{
+    return zmq_ctx_term (ctx_);
 }
 
 

tests/test_connect_delay.cpp

@@ -101,7 +101,7 @@ int main (void)
     rc = zmq_close (to);
     assert (rc == 0);
 
-    rc = zmq_ctx_destroy(context);
+    rc = zmq_ctx_term(context);
     assert (rc == 0);
 
     // TEST 2
@@ -172,7 +172,7 @@ int main (void)
     rc = zmq_close (to);
     assert (rc == 0);
     
-    rc = zmq_ctx_destroy(context);
+    rc = zmq_ctx_term(context);
     assert (rc == 0);
 
     // TEST 3
@@ -219,7 +219,7 @@ int main (void)
     rc = zmq_close (to);
     assert (rc == 0);
     
-    rc = zmq_ctx_destroy(context2);
+    rc = zmq_ctx_term(context2);
     assert (rc == 0);
     
     // Give time to process disconnect
@@ -252,9 +252,9 @@ int main (void)
     rc = zmq_close (from);
     assert (rc == 0);
 
-    rc = zmq_ctx_destroy(context);
+    rc = zmq_ctx_term(context);
     assert (rc == 0);
     
-    rc = zmq_ctx_destroy(context2);
+    rc = zmq_ctx_term(context2);
     assert (rc == 0);
 }

tests/test_disconnect_inproc.cpp

@@ -114,7 +114,7 @@ int main(int argc, char** argv) {
     zmq_close(pubSocket) && printf("zmq_close: %s", zmq_strerror(errno));
     zmq_close(subSocket) && printf("zmq_close: %s", zmq_strerror(errno));
   
-    zmq_ctx_destroy(context);
+    zmq_ctx_term(context);
     return 0;
 }