[zeromq-dev] question about the documentation to provide when adding a set of functions

[Laurent Alebarde]

Thanks Pieter for your remarks. For many reasons, I closed the pull 
requests. I have just pushed the new code to my repository. No more 'n'. 
I think it is 'nice' code now and ready for a pull-request as soon as we 
have closed this discussion.

About the name 'chain', it refers to the ability to chain several 
proxies in the same thread. So having all sockets in the same poll. 
'open_chain' means the polling loop is opened. In existing proxy 
functions, they are blocking with an internal loop. With 'open_chain', 
there is a time_out parameter which do not block plus the internal loop 
is exited. This gives you the opportunity to have end-points (client, 
worker) in the same poll than proxy sockets. So you can write a full 
protocol layer or one test application in a single thread.

Philosophically, I would say that the more specialized are functions, 
longer their names should be.

Concerning the documentation, I have written one for the family 
functions and refered to it in other proxy functions:

https://github.com/lalebarde/libzmq/blob/master/doc/zmq_proxy_open_chain.txt

I have tried to stick to 0MQ API construction (your mind may have been 
connected to mine this week-end).

If you have another suggestion for 'zmq_proxy_open_chain' that makes 
more sense for you, I will change it. But with my explanations and 
justifications, I find it right IMHO and have no other suggestion myself.

Here is the proxy API for now (in red what concerns zmq_proxy_open_chain):

ZMQ_EXPORT int zmq_proxy (void *frontend, void *backend, void *capture);
ZMQ_EXPORT int zmq_proxy_steerable (void *frontend, void *backend, void 
*capture, void *control);
ZMQ_EXPORT int zmq_proxy_hook (void *frontend, void *backend, void 
*capture, void *hook, void *control);
ZMQ_EXPORT int zmq_proxy_chain (void **frontends_, void **backends_, 
void *capture_, void **hooks_, void *control_);

typedef struct zmq_proxy_open_chain_t {unsigned char _ [496];} 
zmq_proxy_open_chain_t; // 128 with dynamic allocation
ZMQ_EXPORT int zmq_proxy_open_chain_init (zmq_proxy_open_chain_t 
**proxy_open_chain_, void **open_endpoints_,
         void **frontends_, void **backends_, void *capture_, void 
**hooks_, void *control_, long time_out_);
ZMQ_EXPORT int zmq_proxy_open_chain_set_socket_events_mask 
(zmq_proxy_open_chain_t *proxy_open_chain_, size_t socket_index, int state);
ZMQ_EXPORT int zmq_proxy_open_chain_poll (zmq_proxy_open_chain_t 
*proxy_open_chain_);
ZMQ_EXPORT int zmq_proxy_open_chain_close (zmq_proxy_open_chain_t 
**proxy_open_chain_);

typedef int (*zmq_hook_f)(void *frontend, void *backend, void *capture, 
zmq_msg_t* msg_, size_t n_, void *data_);
typedef struct zmq_proxy_hook_t {
     void *data;
     zmq_hook_f front2back_hook;
     zmq_hook_f back2front_hook;
} zmq_proxy_hook_t;

Internally, the core engine is the class zmq::proxy_t, which replaces 
the function zmq::proxy. All this stuff enable very concise applicative 
code when developing protocols.

Cheers,


Laurent




Le 05/02/2014 12:05, Pieter Hintjens a écrit :
> Conventionally we have one man page per method.
>
> We also have a standard for API construction, which you can see used
> in zmq_ctx - new/destroy, etc. Please stick to this unless you have
> _absolute_ reasons for doing it differently.
>
> Before you write the man pages, can you improve the names?
> "zmq_proxy_open_chain" is a long name and somewhat mysterious. You may
> find a name that is more descriptive of what this object actually is
> (it's not clear to me yet). Do we have closed chains? If not, why is
> "open" relevant? What is the chain? A chain of proxies? I'm baffled
> (and too lazy to look at the code).
>
> The code (I finally looked at it) uses "proxy chain".
>
> Also the code is... not nice.
>
>      if (!hook_)
>          hook_ = no_hooks;
>      else
>          for (size_t i = 0; i < n; i++)
>              if (!hook_[i]) // Check if a hook is used
>                  hook_[i] = &dummy_hook;
>
> I know we don't do code reviews but this is old-style "let's forget
> about variable names and just assume we're using FORTRAN 78 registers"
> stuff. It's nasty. What is 'n'?
>
> I'd really enjoy seeing *nice* code. There's a style guide at
> http://zeromq.org/docs:style.
>
> -Pieter
>
>
>
>
> On Tue, Feb 4, 2014 at 11:34 PM, Laurent Alebarde <l.alebarde at free.fr> wrote:
>> Hi Devs,
>>
>> I have finished to develop zmq_proxy_open_chain. This one comes with a few
>> functions, in particular the one to sleep/awake a socket.
>>
>> typedef struct zmq_proxy_open_chain_t {unsigned char _ [496];}
>> zmq_proxy_open_chain_t;
>> ZMQ_EXPORT int zmq_proxy_open_chain_init (zmq_proxy_open_chain_t
>> **proxy_open_chain_, void **open_endpoints_,
>>          void **frontends_, void **backends_, void *capture_, void **hooks_,
>> void *control_, long time_out_);
>> ZMQ_EXPORT int zmq_proxy_open_chain_set_socket_events_mask
>> (zmq_proxy_open_chain_t *proxy_open_chain_, size_t socket_index, int state);
>> ZMQ_EXPORT int zmq_proxy_open_chain (zmq_proxy_open_chain_t
>> *proxy_open_chain_);
>> ZMQ_EXPORT int zmq_proxy_open_chain_close (zmq_proxy_open_chain_t
>> **proxy_open_chain_);
>>
>> I have just to update the doc before pushing and pull-request.
>>
>> Shall I provide one doc per function, or one only, or the same several times
>> with one copy per function ?
>>
>> Cheers,
>>
>>
>> Laurent
>>
>>
>> _______________________________________________
>> zeromq-dev mailing list
>> zeromq-dev at lists.zeromq.org
>> http://lists.zeromq.org/mailman/listinfo/zeromq-dev
>>
> _______________________________________________
> zeromq-dev mailing list
> zeromq-dev at lists.zeromq.org
> http://lists.zeromq.org/mailman/listinfo/zeromq-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.zeromq.org/pipermail/zeromq-dev/attachments/20140205/a1626214/attachment.htm>