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 skal...@users.sourceforge.net _______________________________________________ zeromq-dev mailing list zeromq-dev@lists.zeromq.org http://lists.zeromq.org/mailman/listinfo/zeromq-dev