3party/libzmq
0
0
Fork 0
mirror of https://github.com/zeromq/libzmq.git synced 2024-12-26 23:01:04 +08:00
Code Issues Projects Releases Wiki Activity

Problem: zmq_disconnect documentation is confusing and breaks semantics

Browse Source 
Solution: restore separate zmq_unbind documentation, adding a note that the implementation
might be shared but the semantics are different and should not be mixed.
This avoids tying the API to the implementation details which might change for some
engines.
This commit is contained in:
Luca Boccassi 2019-06-27 18:22:17 +01:00
parent eba6fb2988
commit 364561953a
2 changed files with 76 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
doc/zmq_disconnect.txt
View File

@ -25,27 +25,12 @@ associated with the endpoint will be discarded. However, if the socket's linger
period is non-zero, libzmq will still attempt to transmit these discarded messages,
until the linger period expires.
Addionally, if the disconnected endpoint was previously connected to
(as opposed to bound), the incoming message queue associated with the
endpoint will be discarded. This means that after unbinding an endpoint
using `disconnect`, it is possible to received messages originating
from that same endpoint if they were already present in the incoming message
queue before unbinding. However, this is not the case when disconnecting
from a connected endpoint.
The 'endpoint' argument is as described in linkzmq:zmq_connect[3]
NOTE: The default setting of _ZMQ_LINGER_ does not discard unsent messages;
this behaviour may cause the application to block when calling _zmq_ctx_term()_.
For details refer to linkzmq:zmq_setsockopt[3] and linkzmq:zmq_ctx_term[3].
Unbinding wild-card address from a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When a wild-card `*` 'endpoint' (described in linkzmq:zmq_tcp[7],
linkzmq:zmq_ipc[7] and linkzmq:zmq_vmci[7]) was used in _zmq_bind()_, the caller
should use the real 'endpoint' obtained from the ZMQ_LAST_ENDPOINT socket option
to unbind this 'endpoint' from a socket.
RETURN VALUE
------------
The _zmq_disconnect()_ function shall return zero if successful. Otherwise it
@ -78,37 +63,6 @@ rc = zmq_disconnect (socket, "tcp://server001:5555");
assert (rc == 0);
----
.Unbind a subscriber socket from a TCP transport
----
/* Create a ZMQ_SUB socket */
void *socket = zmq_socket (context, ZMQ_SUB);
assert (socket);
/* Connect it to the host server001, port 5555 using a TCP transport */
rc = zmq_bind (socket, "tcp://127.0.0.1:5555");
assert (rc == 0);
/* Disconnect from the previously connected endpoint */
rc = zmq_disconnect(socket, "tcp://127.0.0.1:5555");
assert (rc == 0);
----
.Unbind wild-card `*` binded socket
----
/* Create a ZMQ_SUB socket */
void *socket = zmq_socket (context, ZMQ_SUB);
assert (socket);
/* Bind it to the system-assigned ephemeral port using a TCP transport */
rc = zmq_bind (socket, "tcp://127.0.0.1:*");
assert (rc == 0);
/* Obtain real endpoint */
const size_t buf_size = 32;
char buf[buf_size];
rc = zmq_getsockopt (socket, ZMQ_LAST_ENDPOINT, buf, (size_t *)&buf_size);
assert (rc == 0);
/* Unbind socket by real endpoint */
rc = zmq_disconnect (socket, buf);
assert (rc == 0);
----
SEE ALSO
--------
linkzmq:zmq_connect[3]

79
doc/zmq_unbind.txt
View File

@ -4,7 +4,7 @@ zmq_unbind(3)
NAME
----
zmq_unbind - Another name for zmq_disconnect
zmq_unbind - Stop accepting connections on a socket
SYNOPSIS
@ -14,8 +14,81 @@ int zmq_unbind (void '*socket', const char '*endpoint');
DESCRIPTION
-----------
The _zmq_unbind()_ has the same exact behavior as _zmq_disconnect()_.
Refer to linkzmq:zmq_disconnect[3].
The _zmq_unbind()_ function shall unbind a socket specified
by the 'socket' argument from the endpoint specified by the 'endpoint'
argument.
Addionally the incoming message queue associated with the endpoint will be
discarded. This means that after unbinding an endpoint it is possible to
received messages originating from that same endpoint if they were already
present in the incoming message queue before unbinding.
The 'endpoint' argument is as described in linkzmq:zmq_bind[3]
Unbinding wild-card address from a socket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When wild-card `*` 'endpoint' (described in linkzmq:zmq_tcp[7],
linkzmq:zmq_ipc[7] and linkzmq:zmq_vmci[7]) was used in _zmq_bind()_, the caller should use
real 'endpoint' obtained from the ZMQ_LAST_ENDPOINT socket option
to unbind this 'endpoint' from a socket.
RETURN VALUE
------------
The _zmq_unbind()_ function shall return zero if successful. Otherwise it
shall return `-1` and set 'errno' to one of the values defined below.
ERRORS
------
*EINVAL*::
The endpoint supplied is invalid.
*ETERM*::
The 0MQ 'context' associated with the specified 'socket' was terminated.
*ENOTSOCK*::
The provided 'socket' was invalid.
*ENOENT*::
The endpoint supplied was not previously bound.
EXAMPLES
--------
.Unbind a subscriber socket from a TCP transport
----
/* Create a ZMQ_SUB socket */
void *socket = zmq_socket (context, ZMQ_SUB);
assert (socket);
/* Connect it to the host server001, port 5555 using a TCP transport */
rc = zmq_bind (socket, "tcp://127.0.0.1:5555");
assert (rc == 0);
/* Disconnect from the previously connected endpoint */
rc = zmq_unbind (socket, "tcp://127.0.0.1:5555");
assert (rc == 0);
----
.Unbind wild-card `*` binded socket
----
/* Create a ZMQ_SUB socket */
void *socket = zmq_socket (context, ZMQ_SUB);
assert (socket);
/* Bind it to the system-assigned ephemeral port using a TCP transport */
rc = zmq_bind (socket, "tcp://127.0.0.1:*");
assert (rc == 0);
/* Obtain real endpoint */
const size_t buf_size = 32;
char buf[buf_size];
rc = zmq_getsockopt (socket, ZMQ_LAST_ENDPOINT, buf, (size_t *)&buf_size);
assert (rc == 0);
/* Unbind socket by real endpoint */
rc = zmq_unbind (socket, buf);
assert (rc == 0);
----
NOTE
----
Note that while the implementation is similar to _zmq_disconnect()_, the
semantics are different and the two functions should not be used
interchangeably. Bound sockets should be unbound, and connected sockets should
be disconnected.
SEE ALSO
--------