doc: qbloop.h: document pros/cons of using built-in event loop impl

Make the qbipcs.h module interdependence clear (also shedding light to
some semantic dependencies) as well.

Signed-off-by: Jan Pokorný <[email protected]>

include/qb/qbipcs.h

@@ -43,6 +43,12 @@ extern "C" {
  * @example ipcserver.c
  */
 
+/**
+ * Rates to be passed to #qb_ipcs_request_rate_limit.  Its exact interpretation
+ * depends on how the event loop implementation understands the concept of
+ * priorities, see the disscussion at #qb_ipcs_poll_handlers structure -- an
+ * integration point between IPC server instance and the underlying event loop.
+ */
 enum qb_ipcs_rate_limit {
 	QB_IPCS_RATE_FAST,
 	QB_IPCS_RATE_NORMAL,
@@ -104,6 +110,22 @@ typedef int32_t (*qb_ipcs_job_add_fn)(enum qb_loop_priority p,
 				      void *data,
 				      qb_loop_job_dispatch_fn dispatch_fn);
 
+/**
+ * A set of callbacks that need to be provided (only #job_add can be #NULL)
+ * whenever the IPC server is to be run (by the means of #qb_ipcs_run).
+ * It is possible to use accordingly named functions defined in qbloop.h module
+ * or integrate with other existing (like GLib's event loop) or entirely new
+ * code -- see the subtle distinction amongst the possible event loops pointed
+ * out in the introductory comment at qbloop.h.
+ *
+ * At that occasion, please note the correlation of #QB_IPCS_RATE_FAST etc.
+ * symbolic names with said advisory effect of the priorities in the native
+ * implementation.  This correspondence will not be this intuitively seemless
+ * if some other event loop implementation is hooked in given that it abids
+ * them strictly as mentioned (e.g. GLib's event loop over poll'able sources).
+ * Differences between the two paradigms should also be accounted for when
+ * the requirement to swap the event loop implementations arises.
+ */
 struct qb_ipcs_poll_handlers {
 	qb_ipcs_job_add_fn job_add;
 	qb_ipcs_dispatch_add_fn dispatch_add;

include/qb/qbloop.h

@@ -36,6 +36,26 @@ extern "C" {
  *
  * Main loop manages timers, jobs and polling sockets.
  *
+ * Only a weaker sense of priorities is implemented, alluding to distinct
+ * set of pros and cons compared to the stronger, strict approach to them
+ * as widely applied in this problem space (since the latter gives the
+ * application more control as the effect of the former can still be
+ * achieved with some reductions, whereas it is not straightforward the
+ * other way around; cf. static priority task scheduling vs. relative
+ * fine-tuning within a single priority domain with nice(2)):
+ *
+ * + implicit mitigation for deadlock-prone priority arrangements
+ *
+ * - less predictable (proportional probability based, we can talk
+ *   about an advisory effect of the priorities) responses to the arrival
+ *   of the high-ranked events (i.e. in the process of the picking the next
+ *   event to handle from the priority queue when at least two different
+ *   priorities are eligible at the moment)
+ *
+ * One practical application for this module of libqb is in combination with
+ * IPC servers based on qbipcs.h published one (the #qb_ipcs_poll_handlers
+ * structure maps fittingly to the control functions published here).
+ *
  * @example tcpserver.c
  */