> Date: Mon, 23 Jan 2017 15:27:31 +0000 > From: Alexandre Quessy <aque...@d-box.com> > To: ZeroMQ development list <zeromq-dev@lists.zeromq.org> > Subject: Re: [zeromq-dev] zmq::socket_t::send blocking > Message-ID: <a13a90d44deb45f386c5ddf93a09c49d@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-boun...@lists.zeromq.org] De la part de > Jens Auer > Envoyé : 20 janvier 2017 15:28 > À : 'ZeroMQ development list' <zeromq-dev@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 _______________________________________________ zeromq-dev mailing list zeromq-dev@lists.zeromq.org https://lists.zeromq.org/mailman/listinfo/zeromq-dev
