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

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

include/qb/qbloop.h

@@ -36,6 +36,24 @@ extern "C" {
  *
  * Main loop manages timers, jobs and polling sockets.
  *
+ * To be noted that local implementation of the event loop does care about
+ * priorities, these are rather advisory, however.  For the true real-world
+ * systems with requirements of deterministic responses, you may be better
+ * served with these priorities strictly separated and abided, which is the
+ * case, e.g., with GLib's event loop over poll'able sources.  On the other
+ * hand, for early stages and timing/priority non-criticial SW, it is a good
+ * choice, since it implicitly mitigates deadlock-prone priority arrangement
+ * issues (beware, it may as well provide a false sense of correctness for
+ * the client SW, bitting once swapped for something strict as mentioned).
+ *
+ * An example of practical application of this module of libqb is in
+ * combination with IPC servers based on qbipcs.h published one, whereby
+ * the #qb_ipcs_poll_handlers structure maps nicely to control functions
+ * offered here.  At that occasion, please note the original alignment
+ * of #QB_IPCS_RATE_FAST etc. symbolic names with the advisory effect of the
+ * priorities there, which gets semantically skewed once the implementation
+ * strictly abiding them is used instead of this native event loop.
+ *
  * @example tcpserver.c
  */