[zeromq-dev] zmq::socket_t::send blocking

[James Gatannah]

> Date: Mon, 23 Jan 2017 15:27:31 +0000
> From: Alexandre Quessy <aquessy at d-box.com>
> To: ZeroMQ development list <zeromq-dev at lists.zeromq.org>
> Subject: Re: [zeromq-dev] zmq::socket_t::send blocking
> Message-ID: <a13a90d44deb45f386c5ddf93a09c49d at mail03.d-box.local>
> Content-Type: text/plain; charset="utf-8"
>
> Hi,
> Thank you for pointing me to the specific section that is relevant for me. That’s great.
> Now, this sentence is 57-word long, and I find it hard to read, since English is not my first language.
>
> Here is a proposal of a rewrite in shorter sentences. I also avoid fancy words
> words like “shall”, or “high water mark” that non-native English readers might find
> tricky to understand.

"Shall" has a long history, especially in RFCs, with a very specific
meaning. (That's really based on a much longer legal history, but that
usage seems to mostly be ignored these days).

The term "high water mark" is an important part of TCP/IP networking.
I'm not sure about the history, but a quick google search turned up
references from 1985.

They aren't really screwy idiomatic English phrases. I'm pretty sure
most natives would also find the usage odd. This is a good thing,
since it encourages people to look up the very specific technical
meaning behind them.

I'd vote that we be very cautious about changing those.

That being said, breaking that sentence into smaller pieces seems reasonable.

> Please let me know if it is accurate or not. I would happily submit a merge request if you guys point me to the right Git repository for this API documentation. Here is my text:
>
>
> If a socket is in ZMQ_PUSH mode, it will enter the mute state if ever its maximum > threshold of messages in its downstream nodes is reached.
> In mute state, if the socket has no downstream nodes, zmq_send(3) operations will block until the mute state ends.
> As soon as there is a downstream node becomes available for sending, it will do it.
> Messages are queued, therefore they will not be discarded.
> By default, this function will block until it is done sending.
> If the ZMQ_DONTWAIT flag is set, it will not block and do it later, in its I/O thread, in case it takes some time to do so.
>

Hmm. For reference, the current version is quoted near the bottom.

How about something along these lines?

"When a ZMQ_PUSH socket has no downstream nodes, or all its downstream
nodes have reached their high water mark, the ZMQ_PUSH socket enters
the mute state. In the mute state, any zmq_send(3) operations on the
socket shall block until the mute state ends. The mute state ends when
at least one downstream node becomes available for sending. Messages
are not discarded."

I'm pretty sure that retains the original meaning. I don't know
whether it's more clear to anyone (native English speaker or not).

Technical writing is hard. Part of the beauty of 0mq is that the docs
are so very well written.

(Sidenote: I really thought that trying to zmq_send with ZMQ_DONTWAIT
resulted in EAGAIN while muted...queuing it to run later only works
until the Push socket reaches its high water mark. It's been a couple
of years since I touched Push/Pull, but I remember that being an
important part of the way it works).

Just my $0.02.

Respectfully,
James


> Best,
>
>
> ALEXANDRE QUESSY
> Consultant software
>
> D-BOX Technologies Inc. | A. 2172 de la Province, Longueuil, QC J4G 1R7 CANADA | T. 450-442-3003 | W. d-box.com<http://www.d-box.com>
>
> De : zeromq-dev [mailto:zeromq-dev-bounces at lists.zeromq.org] De la part de Jens Auer
> Envoyé : 20 janvier 2017 15:28
> À : 'ZeroMQ development list' <zeromq-dev at lists.zeromq.org>
> Objet : Re: [zeromq-dev] zmq::socket_t::send blocking
>
> Hi,
>
> quoting the manual from the link in Colin’s answer:
> When a ZMQ_PUSH socket enters the mute state due to having reached the high water mark for all downstream nodes, or if there are no downstream nodes at all, then any zmq_send(3) operations on the socket shall block until the mute state ends or at least one downstream node becomes available for sending; messages are not discarded.
>
>
>
>
> Best wishes,
> Jens