[zeromq-dev] Docs

[john skaller]

On 16/01/2012, at 7:18 PM, Martin Sustrik wrote:

> On 01/15/2012 05:53 PM, Marten Feldtmann wrote:
>> I had asked the same question some days agon on this list, while working
>> on a VASmalltalk binding for this library.
>> 
>> It should be made clearer in the documentation, that one may reuse the
>> structure after the application thread has closed it.
> 
> Yes. zmq_msg_t is basically a handle. There's no much point allocating 
> it on the heap. Normally you just keep it on stack. Once it is closed, 
> it can be re-initialised.
> 
> If you have an idea how to fix the docs, feel free to suggest a patch.


I can outline an idea for discussion (or make a patch .. are the docs on GitHub?)

I would define three terms (not necessarily the ones I use here,
they just "make sense semantically" to me):

MessageContainer:  zmq_msg_t,
  Type of an an object which have an associated MessageBuffer

MessageBuffer: 
  a managed storage extent which may store a Message
  up to a particular length.

  [in ISO C Standard, a storage extent is called an object]

Message:
  A sequence of bytes of a particular length

So:
  *  A MessageContainer may, or may not have an associated MessageBuffer.
  * A MessageBuffer may, or may not  hold a Message

Now, we can define:
  * The state of a MessageContainer is initially "indeterminate".
  * If the state is "indeterminate", the state becomes "Initialised" 
    after *_msg_init is called on it
  * If the state is "initialised" it becomes "indeterminate" after zmq_msg_close
    is called on it.
  * recv, move, etc ... require the state be "initialised" and leave the state "initialised"
  * the program is undefined otherwise (this doesn't have to be stated)

We can say, a MessageContainer has an associated MessageBuffer if,
and only if, its state is "initialised".

We can also define when a MessageBuffer holds a Message:

  * After zmq_msg_init is called,  the associated MessageBuffer
    holds a zero length message
  * After zmq_msg_init_size is called .. what? I dunno?
  * After zmq_msg_init_data is called, whatever message was in the
     array of length N starting at location D (the arguments) is in
    the associated Buffer
  * After zmq_msg_move .. copy recv...

Basically, you have a simple mathematical model here, with
undefined terms involved, but basically a couple of trivial state
machines with state changes on each call.

You also need some words about zmq_msg_init_data:
is the client allowed/expected/not allowed to modify the buffer?
[Since the user retains access to it. It's already reasonably
clear the user may not delete it, that's done on the close
call which de-initialises the MessageContainer]


--
john skaller
skaller at users.sourceforge.net