group being a `char *` is logically a text type, which needs an encoding.
Declare in the API that groups shall be UTF8-encoded,
matching the `zmq_msg_gets` API, which is the other user-facing `char *` API,
which has the same definition.
This allows bindings to provide text-type APIs,
which they cannot do if arbitrary bytes are allowed
Linux now supports Virtual Routing and Forwarding (VRF) as per:
https://www.kernel.org/doc/Documentation/networking/vrf.txt
In order for an application to bind or connect to a socket with an
address in a VRF, they need to first bind the socket to the VRF device:
setsockopt(sd, SOL_SOCKET, SO_BINDTODEVICE, dev, strlen(dev)+1);
Note "dev" is the VRF device, eg. VRF "blue", rather than an interface
enslaved to the VRF.
Add a new socket option, ZMQ_BINDTODEVICE, to bind a socket to a device.
In general, if a socket is bound to a device, eg. an interface, only
packets received from that particular device are processed by the socket.
If device is a VRF device, then subsequent binds/connects to that socket
use addresses in the VRF routing table.
Solution:
* Document the new behaviour when generating 'ZMQ_POLLOUT' events
for ZMQ_ROUTER sockets with 'ZMQ_ROUTER_MANDATORY' set to `1`
* Add clarifications for 'ZMQ_ROUTER' socket when
'ZMQ_ROUTER_MANDATORY' is set to `1`
Problem: GSSAPI NAMETYPE options were not documented in man
pages for zmq_getsockopt() and zmq_setsockopt().
Solution: add new options to these manual pages.
Problem: the ZMQ_GSSAPI_PRINCIPAL socket option is described
as mandatory in the zmq_gssapi(7) manual page. In fact it
is optional.
Solution: Describe ZMQ_GSSAPI_PRINCIPAL as optional.
If unspecified, default credentials are used.
Solution: add a note pointing out that when new events are added the
ZMQ_EVENT_ALL mask will start returning them, so applications that
can't handle that transparently should not use it and instead pick
only the event types they want.
Creating a new event type and having monitors with ZMQ_EVENT_ALL
return them will not be considered a backward incompatible change
even though the flow of events will change.
Solution: fix it.
The documentation first states that the ZMQ_SNDMORE flag is ignored on
data frames. Then it states that omitting the ZMQ_SNDMORE flag has
consequences. The example HTTP server code further muddies the situation
with a similar comment.
The implementation of ZMQ_STREAM only accepts two-part messages.
The first part is an identity frame while the second and last part is
the data frame.
As with any multipart message, all parts except the last need the
ZMQ_SNDMORE flag. The second and last part would normally omit the
ZMQ_SNDMORE flag to mark the end of the multipart message.
However, the ZMQ_STREAM implementation ignores the ZMQ_SNDMORE flag on
the data frame rather than requiring that it be omitted. The latter
behaviour would have been more consistent with the other ZeroMQ
sockets.
Solution:
- Update formatting and remove redundant parts from ZMQ_PROBE_ROUTER,
ZMQ_USE_FD, ZMQ_TCP_MAXRT, ZMQ_TCP_TOS
- Only cosmetic changes to the content
- These changes already merged on api.zeromq.org by me
Problem: when using ZMQ_REQ_RELAXED + ZMQ_REQ_CORRELATE and two 'send' are
executed in a row and no server is available at the time of the sends,
then the internal request_id used to identify messages gets corrupted and
the two messages end up with the same request_id. The correlation no
longer works in that case and you may end up with the wrong message.
Solution: make a copy of the request_id instance member before sending it
down the pipe.
Solution: add the document files to the MAN_DOC and MAN_HTML targets
in doc/Makefile.am only if BUILD_DOC and INSTALL_MAN are set,
otherwise leave the targets empty to avoid errors in make distcheck.
And I'm on a reasonably sized laptop. I think allocating INT_MAX
memory is dangerous in a test case.
Solution: expose this as a context option. I've used ZMQ_MAX_MSGSZ
and documented it and implemented the API. However I don't know how
to get the parent context for a socket, so the code in zmq.cpp is
still unfinished.
These options are confusing and redundant. Their names suggest
they apply to the tcp:// transport, yet they are used for all
stream protocols. The methods zmq::set_tcp_receive_buffer and
zmq::set_tcp_send_buffer don't use these values at all, they use
ZMQ_SNDBUF and ZMQ_RCVBUF.
Solution: merge these new options into ZMQ_SNDBUF and ZMQ_RCVBUF.
This means defaulting these two options to 8192, and removing the
new options. We now have ZMQ_SNDBUF and ZMQ_RCVBUF being used both
for TCP socket control, and for input/output buffering.
Note: the default for SNDBUF and RCVBUF are otherwise 4096.
This option has a few issues. The name is long and clumsy. The
functonality is not smooth: one must set both this and
ZMQ_XPUB_VERBOSE at the same time, or things will break mysteriously.
Solution: rename to ZMQ_XPUB_VERBOSER and make an atomic option.
That is, implicitly does ZMQ_XPUB_VERBOSE.
Solution: be more explicit in the code, and in the zmq_recv man
page (which is the most unobvious case). Assert if length is not
zero and buffer is nonetheless null.
Solution: add new [set|get]sockopt ZMQ_PRE_ALLOCATED_FD to allow
users to let ZMQ use a pre-allocated file descriptor instead of
allocating a new one. Update [set|get]sockopt documentation and
test accordingly.
The main use case for this feature is a socket-activated systemd
service. For more information about this feature see:
http://0pointer.de/blog/projects/socket-activation.html
These sockets don't handle multipart data, so if callers send it,
they drop frames, and things break silently.
Solution: if the caller tries to use ZMQ_SNDMORE, return -1 and
set errno to EINVAL.
VMCI transport allows fast communication between the Host
and a virtual machine, between virtual machines on the same host,
and within a virtual machine (like IPC).
It requires VMware to be installed on the host and Guest Additions
to be installed on a guest.
Without this change, a segmentation fault is likely to occur when using the proposed snippet of code, as `*address[size]` is equivalent to `*(address[size])`, not `(*address)[size]` as clearly intended.
REQ-REP barely work, and DEALER-ROUTER are misnamed. As we move to
formalizing CLIENT-SERVER, we can deprecate request-reply.
Solution: move this section to the end of the man page, and mark as
"will be deprecated".
The order of zmq_bind() and zmq_connect() is no longer important
for the inproc transport since libzmq 4.0. This updates this
in the zmq_inproc manpage.
Fixes not receiving unsubscription messages in XPUB socket with
ZMQ_XPUB_VERBOSE and using a XSUB-XPUB proxy in front.
This adds two modifications:
- It adds a new flag, ZMQ_XPUB_VERBOSE_UNSUBSCRIBE, to enable verbose
unsubscription messages, necessary when using a XSUB/XPUB proxy.
- It adds a boolean switch to zmq::mtrie_t::rm () to control if the
callback is invoked every time or only in the last removal. Necessary
when a pipe is terminated and the verbose mode for unsubscriptions is
enabled.
Set the ZMQ_HEARTBEAT_TIMEOUT to default to the value of
ZMQ_HEARTBEAT_IVL if it's not explicitly set.
Change the units of ZMQ_HEARTBEAT_TTL to milliseconds in the API
and round down to the nearest decisecond so that all the options
are using the same units.
Make the maximum heartbeat TTL match the spec (6553 seconds)
Pull request #1426 now allow for changing the watermark
after and connect() or a bind(). This patch reflect the
change in the documentation.
Also closes#1416.
zmq_term and zmq_ctx_destroy are just aliases for zmq_ctx_term. that
being the case use 'terminate' in the description for all three so there
isn't any confusion about behavior.
also update the deprecates list in zmq_ctx_term to include
zmq_ctx_destroy.
ZMQ_INVERT_MATCHING reverses the PUB/SUB prefix matching. The subscription
list becomes a rejection list. The PUB socket sends messages to all
connected (X)SUB sockets that do not have any matching subscription.
Whenever the option is used on a PUB/XPUB socket, any connecting SUB
sockets must also set it or they will reject everything the publisher
sends them. XSUB sockets are unaffected because they do not filter out
incoming messages.
Symptom is that ZMQ_STREAM sockets in 4.1.0 and 4.1.1 generate zero
sized messages on each new connection, unlike 4.0.x which did not do
this.
Person who made this commit also changed test cases so that contract
breakage did not show. Same person was later banned for persistently
poor form in CZMQ contributions.
Solution: enable connect notifications on ZMQ_STREAM sockets using a
new ZMQ_STREAM_NOTIFY setting. By default, socket does not deliver
notifications, and behaves as in 4.0.x.
Fixes#1316
Allows non-C/C++ based clients easy access to the peer's IP address via
zmq_msg_gets(&msg, "Peer-Address") instead of zmq_msg_get(&msg, ZMQ_SRCFD)
followed by calls to getpeername and getnameinfo
zmq_atomic_counter_dec returned a 'bool' value, yet this isn't
defined by standard, so causes compile errors in upstream code.
Solution: return an int that can be safely converted to bool if
needed by bindings.
Solution: as libzmq already provides this across all platforms,
expose an atomic counter API. I've not wrapped atomic pointers,
though someone who needs this may want to do so.
Solution: set defaults back to infinity, and add new context
option, ZMQ_BLOCKY that the user can set to false to get a
less surprising behavior on context termination. Eg.
zmq_ctx_set (ctx, ZMQ_BLOCKY, false);
Solution: document this with a clear warning. It would be
nicer perhaps to change the default LINGER to e.g. a few
seconds. However this could break existing applications.
This commit adds a ZMQ_POLLPRI flag that maps to poll()'s POLLPRI
flag.
This flags does nothing for OMQ sockets. It's only useful for raw
file descriptor (be it socket or file).
This flag does nothing if poll() is not the underlying polling
function. So it is Linux only.
Solution: document the limit of 113 chars including ipc://. We might
fix this in libzmq by shortening an over-long IPC pathname into a
unique string; so long as this is done consistently in bind and in
connect, it will save applications from weird failures when they
use external data to generate IPC pathnames.
Solution: change setsockopts on printable keys to expect 41, nor 40
bytes. Code still accepts 40 bytes for compatibility, and copies the
key to a well-terminated string before using it.
Fixes#1148
As libzmq is compiled with optional transports and security mechanisms,
there is no clean way for applications to determine what capabilities
are actually available in a given libzmq instance.
Solution: provide an API specifically for capability reporting. The
zmq_has () method is meant to be open ended. It accepts a string so
that we can add arbitrary capabilities without breaking existing
applications.
zmq.h also defines ZMQ_HAS_CAPABILITIES when this method is provided.
Applications that use ZMQ_IDENTITY can be trapped by the artificial
restriction on not using a binary zero as first byte. It's specially
nasty on random generated identities, e.g. UUIDs, as the chance of a
binary zero is low, so it will pass 255 out of 256 times.
Solution: remove the restriction.
Added modifiers reflect the following properties:
- zmq_msg_gets () does not mutate property parameter
- zmq_msg_gets () returns a pointer to memory the caller should not
modify
Specifically:
* zmq_event_t should not be used internally in libzmq, it was
meant to be an outward facing structure.
* In 4.x, zmq_event_t does not correspond to monitor events, so
I removed the structure entirely.
* man page for zmq_socket_monitor is incomplete and the example
code was particularly nasty.
* test_monitor.cpp needed rewriting, it was not clean.
Issues adressed:
- The actual data was never read from the socket, causing all even
numbered loop iterations to fail
- The socket variable was called server once
The new options allows querying the maximum allowed number of sockets.
This is system dependent and cannot be encoded in the include file as a
preprocessor macro: for ZMQ_USE_SELECT, this depends on the FD_SETSIZE
macro at time of library compilation, not at time of include file use.
When a ZMQ_STREAM socket connection is broken (intentionally, via `shutdown()`
or accidentally via client crash or network failure), there is no way for the
application to dertermine that it should drop per-connection data (such as
buffers).
This contribution makes sure the application receives a 0-length message to
notify it that the connection has been broken. This is symmetric with the
process of closing the connection from within the application (where the
application sends a 0-length message to tell ZeroMQ to close the connection).
Conflicts:
CMakeLists.txt
- This seems redundant; is there a use case for NOT providing
the IPC credentials to the ZAP authenticator?
- More, why is IPC authentication done via libzmq instead of ZAP?
Is it because we're missing the transport type on the ZAP request?
Another take on LIBZMQ-568 to allow filtering IPC connections, this time
using ZAP. This change is backward compatible. If the
ZMQ_ZAP_IPC_CREDS option is set, the user, group, and process IDs of the
peer process are appended to the address (separated by colons) of a ZAP
request; otherwise, nothing changes. See LIBZMQ-568 and zmq_setsockopt
documentation for more information.
Documentation examples for zmq_msg_get and zmq_msg_more functions have an
incorrect call to zmq_msg_close function - with 'zmq_msg_t' as a parameter
despite 'zmq_msg_t *' is required, so it is impossible to compile these
examples properly.
Also for zmq_msg_get example - declaration of zmq_msg_t variable is added
(like it is done in other examples).
* ZMQ_REQ_STRICT was negative option (default 1) which goes against
the standard, where defaults are zero. I renamed this to
ZMQ_REQ_RELAXED.
* ZMQ_REQ_REQUEST_IDS felt clumsy and describes the technical solution
rather than the problem/requirement. I changed to ZMQ_REQ_CORRELATE
which seems more explicit.
* Removed redundant Z85 code and include files from project
* Simplified use of headers in test cases (now they all just use testutil.hpp)
* Export zmq_z85_encode() and zmq_z85_decode() in API
* Added man pages for these two functions
On ZMQ_CURVE_xxxKEY fetches, would return 41 bytes into caller's 40-byte
buffer. Now these fetches only return 41 bytes if the caller explicitly
provides a 41-byte buffer (i.e. the option size is 41).
