lib: document frrzmq in its header file

Signed-off-by: David Lamparter <equinox@opensourcerouting.org>

diff --git a/lib/frr_zmq.h b/lib/frr_zmq.h
index d37824522b793318e14014c50f64ef0fb3d24ffd..69c6f8580dbb6bb68adc69a8af191d8a295ac6dd 100644 (file)
--- a/lib/frr_zmq.h
+++ b/lib/frr_zmq.h
@@ -23,7 +23,21 @@
 #include "thread.h"
 #include <zmq.h>
 
-/* libzmq's context */
+/* linking/packaging note:  this is a separate library that needs to be
+ * linked into any daemon/library/module that wishes to use its
+ * functionality.  The purpose of this is to encapsulate the libzmq
+ * dependency and not make libfrr/FRR itself depend on libzmq.
+ *
+ * libfrrzmq should be put in LDFLAGS/LIBADD *before* either libfrr or
+ * libzmq, and both of these should always be listed, e.g.
+ *   foo_LDFLAGS = libfrrzmq.la libfrr.la $(ZEROMQ_LIBS)
+ */
+
+/* libzmq's context
+ *
+ * this is mostly here as a convenience, it has IPv6 enabled but nothing
+ * else is tied to it;  you can use a separate context without problems
+ */
 extern void *frrzmq_context;
 
 extern void frrzmq_init (void);
@@ -31,6 +45,7 @@ extern void frrzmq_finish (void);
 
 #define debugargdef const char *funcname, const char *schedfrom, int fromln
 
+/* core event registration, one of these 2 macros should be used */
 #define frrzmq_thread_add_read_msg(m,f,a,z) funcname_frrzmq_thread_add_read( \
                                m,f,NULL,a,z,#f,__FILE__,__LINE__)
 #define frrzmq_thread_add_read_part(m,f,a,z) funcname_frrzmq_thread_add_read( \
@@ -38,6 +53,29 @@ extern void frrzmq_finish (void);
 
 struct frrzmq_cb;
 
+/* Set up a POLLIN notification to be called from the libfrr main loop.
+ * This has the following properties:
+ *
+ * - since ZeroMQ works with edge triggered notifications, it will loop and
+ *   dispatch as many events as ZeroMQ has pending at the time libfrr calls
+ *   into this code
+ * - due to this looping (which means it non-single-issue), the callback is
+ *   also persistent.  Do _NOT_ re-register the event inside of your
+ *   callback function.
+ * - either msgfunc or partfunc will be called (only one can be specified)
+ *   - msgfunc is called once for each incoming message
+ *   - if partfunc is specified, the message is read and partfunc is called
+ *     for each ZeroMQ multi-part subpart.  Note that you can't send replies
+ *     before all parts have been read because that violates the ZeroMQ FSM.
+ * - you can safely cancel the callback from within itself
+ * - installing a callback will check for pending events (ZMQ_EVENTS) and
+ *   may schedule the event to run as soon as libfrr is back in its main
+ *   loop.
+ *
+ * TODO #1: add ZMQ_POLLERR / error callback
+ * TODO #2: add frrzmq_check_events() function to check for edge triggered
+ *          things that may have happened after a zmq_send() call or so
+ */
 extern struct frrzmq_cb *funcname_frrzmq_thread_add_read(
                struct thread_master *master,
                void (*msgfunc)(void *arg, void *zmqsock),