[zeromq-dev] conventions in bindings

Gary Wright at2002+zmq at me.com
Thu Feb 2 02:19:20 CET 2012

On Feb 1, 2012, at 6:58 AM, Pieter Hintjens wrote:

> On Wed, Feb 1, 2012 at 12:43 AM, john skaller
> <skaller at users.sourceforge.net> wrote:
>>> In terms of nomenclature, should bindings follow the czmq convention of using Frame to refer to a message part, or Message, following libzmq?
> Yes, I'd definitely recommend using the czmq terminology. All words
> have multiple meanings, but as long as we are consistent within our
> universe, it'll be OK.  "Frame" is the natural term for one message
> part since it does actually represent one 0MQ wire level frame.
> "Message" is the right term for a collection of 1 or more frames.
> These two map cleanly to the semantics we expect to get. 0MQ's API doc
> is confusing because it uses "message" for both concepts.
> This terminology has evolved over a long time from use in the Guide
> and there have been no issues raised with it, so I'd encourage its
> adoption. Anything more complex is going to be more, not less,
> confusing.

As a newbie to ZMQ I have found it a bit confusing to understand
when 'message' means a complete series of message parts vs. a single
part vs. a data structure designed to facilitate memory management
of shared buffers containing ZMQ message parts (zmq_msg_t).


The Guide talks about 0MQ 'strings' as being length delimited,
illustrates 'frames' as having a length header but ignores the
flags byte, talks about zmq_msg 'items' as well as message 'objects'
yet zmq_msg_t is actually a C struct. It refers to zmq_send as sending
'messages' (not message items or frames). It sometimes uses zmq_msg_t
with 'buffer' terminology (e.g.  "use zmq_msg_init(3) to create an
empty message').  The API naming is oriented around messages
(e.g. zmq_mst_t, zmq_msg_init, zmq_msg_size, etc), but it is
actually parts/fragments/frames that are being sent and received
(vs. entire messages).

I'm pretty comfortable with networking/messaging/memory management
issues so I wasn't totally lost but the inconsistency is a bit of
a distraction.

Regarding 'frames', I understand the 'water under the bridge' point
of view here but it is somewhat unusual to call the higher-level
PDU (protocol data unit) a frame.

The ZMQ 'wire' format (http://rfc.zeromq.org/spec:15) is a nice
description of the framing that ZMQ uses when sending message parts,
but the frame header, including the length byte(s) and flag bytes,
are not directly visible at the API level (i.e. you don't actually
have to worry about constructing the this header before sending
data or ignoring the header on received data).  The 'parts' that a
user of the API see are something other than 'frames' and just
consist of the user-data.

As an analogy, consider DNS messages sent via UDP.  A user-level
message is wrapped in a UDP datagram (muxing and data integrity),
which is wrapped in an IP packet (routing), which is wrapped in an
Ethernet frame (direct communication with peer) before being
transmitted.  At the socket/api level we talk about DNS messages not
frames.  At the socket level, the UDP, IP, and Ethernet headers
aren't visible.

I'm probably being a bit pedantic, but here is how I have resolved
the terminology in my mind, even though it sometimes clashes with
the names used in the API and/or some of the language bindings. If
I'm confused, please tell me:

  the PDU sent between ZMQ endpoints consisting of one or more fragments
  The total length of a message (# of fragments *or* # of bytes) is
  not encoded in the message itself by ZMQ.

  A length delimitated blob and a flag indicating if the fragment
  is the last fragment of a message or not. The API (libzmq) is
  designed around sending and receiving fragments (vs. entire messages).

  the 'wire' format for a ZMQ fragment, not directly visible via
  the API, used to delimit fragments on various byte oriented

I'm still digesting how to think about 'envelopes' in network
layering terms.  They are really link-level source routes that
are managed at the user level so they break all sorts of layering
and encapsulation 'rules'. I think that is a good thing because
I view ZMQ as a pretty low-level toolkit for constructing messaging

Gary Wright

More information about the zeromq-dev mailing list