[zeromq-dev] conventions in bindings

[Pieter Hintjens]

On Thu, Feb 2, 2012 at 11:27 PM, Martin Sustrik <sustrik at 250bpm.com> wrote:

> The POSIX specification deliberately uses term "message" to reference
> all these types of messages. The idea being that socket API should be
> able to work on any particular layer of the stack (e.g. IP sockets vs.
> TCP sockets).

Yes, and similarly the term "frame" works at various levels. It would
be silly to have to invent a different term for the frame contents, a
frame with flags, a frame with flags and size. All of these are
"frames" with the same overall semantics at different layers.

The main confusion is really just one point: POSIX tends to use
"message" as a single unit of transfer. 0MQ has multi-part messages.
The 0MQ API reference speaks of "messages" with both these hats on at
once. It should choose. If it wants to be a POSIX clone, we can use
"message" systematically to mean one frame/packet/part. We then need a
new term for a multipart message. The fact that a 0MQ low-level
message is also a frame can be explained in the wire protocol spec.

My recommendation is to leave the core API speaking like POSIX, and
the higher API speaking like applications. This means using "message"
in libzmq and in the reference manual, to mean one frame, and to use
"multipart message" in the cases where it's necessary. Anyone who is
confused about zmq_msg_t being a container for various things just
needs to grok that it's a lifecycle thing. It's an API construct. It
be empty. Write some code, it'll all become clear.

And then at the higher level, use "message" as applications do, ie.
for multipart messages, and rename single parts to "frame" for
clarity. "strings" are just C nonsense since it's a real pain to deal
with binary data.

tl;dr:

- libzmq docs should speak of "message" and "multipart message" for
coherence with POSIX
- zmq_msg_t is accurately named, as is obvious to anyone who's used it in anger
- higher level bindings should speak of "frame" and "message" for
coherence with application semantics
- if you can find a simpler plausible fix, I'll buy you a beer in
Portland. Heck, two beers.

-Pieter

Ps. I can repeat this explanation ad-nauseam, it's not random but has
come from deconstructing the semantics over two years in hundreds of
applications.