Adapt documentation of event subscription methods

Explain illegal proxy building in callbacks
Offer suggestions for how to avoid this issue

1 files changed, 11 insertions, 1 deletions

diff --git a/src/CommonAPI/Event.h b/src/CommonAPI/Event.h
index b86f58c..b032da9 100644
--- a/src/CommonAPI/Event.h
+++ b/src/CommonAPI/Event.h
@@ -43,7 +43,12 @@ class Event {
 	/**
 	 * \brief Subscribe a listener to this event
 	 *
-	 * Subscribe a listener to this event
+	 * Subscribe a listener to this event.
+	 * ATTENTION: You should not build new proxies or register services in callbacks
+	 * from events. This can cause a deadlock or assert. Instead, you should set a
+	 * trigger for your application to do this on the next iteration of your event loop
+	 * if needed. The preferred solution is to build all proxies you need at the
+	 * beginning and react to events appropriatly for each.
 	 *
 	 * @param listener A listener to be added
 	 * @return A token identifying this subscription
@@ -54,6 +59,11 @@ class Event {
      * \brief Subscribe a cancellable listener to this event
      *
      * Subscribe a cancellable listener to this event
+     * ATTENTION: You should not build new proxies or register services in callbacks
+     * from events. This can cause a deadlock or assert. Instead, you should set a
+     * trigger for your application to do this on the next iteration of your event loop
+     * if needed. The preferred solution is to build all proxies you need at the
+     * beginning and react to events appropriatly for each.
      *
      * @param listener A cancellable listener to be added
      * @return A token identifying this subscription