Failure case behavior unclear in zmq_msg_send documentation

[rotty]

Issue description

The documentation on zmq_msg_send is unclear about what happens to the provided message in the failure case. The manpage states:

The zmq_msg_t structure passed to zmq_msg_send() is nullified during the call. If you want to send the same message to multiple sockets you have to copy it (e.g. using zmq_msg_copy()).

This seems to contradict the following snippet, which indicates that the message stays the responsibility of the caller in the failure case:

A successful invocation of zmq_msg_send() does not indicate that the message has been transmitted to the network, only that it has been queued on the socket and 0MQ has assumed responsibility for the message. You do not need to call zmq_msg_close() after a successful zmq_msg_send().

The question here is whether it is safe to assume that the message content stays available to the caller in the failure case. A particularly important case is EAGAIN -- it would be quite unfortunate if the caller had to reconstruct the message if it could not be sent simply to a timeout, although it would be unfortunate if that happened for any error, IMO.

I have not really attempted to dig into the code to verify this one way or the other, as it's not easy to follow given the inheritance hierarchy for sockets and other things going on.

It would be awesome if someone could confirm that my suspicion is right, and the message is preserved in all failure cases. I'd be willing to come up with a PR to clarify the wording in the documentation in that case.

This question originally came up in an issue in the Rust zmq crate, which provides bindings to libzmq:

erickt/rust-zmq#211

Environment

• libzmq version: 4.3.1 (or current master, text is unchanged)

[bluca]

It's implied: "NOTE: A successful invocation of zmq_msg_send() does not indicate that the
message has been transmitted to the network, only that it has been queued on
the 'socket' and 0MQ has assumed responsibility for the message. You do not need
to call zmq_msg_close() after a successful zmq_msg_send()."

In the successful case you don't need to call close and the library takes ownership. If it's not successful, the library hasn't taken ownership.

Feel free to send a PR to clarify the text.

[rotty]

Thanks for the quick response! I will try to submit a PR soonish.