wait_manager: Add some prose

Change-Id: Ifa0cbed179e24bd7a840f578c91daae81268eca9

diff --git a/sessiond/src/wait_manager.hpp b/sessiond/src/wait_manager.hpp
index 3eecefb..a4aed59 100644 (file)
--- a/sessiond/src/wait_manager.hpp
+++ b/sessiond/src/wait_manager.hpp
@@ -38,6 +38,55 @@
 #include "tuple_g_variant_helpers.hpp"
 #include "tuple_hash.hpp"
 
+/* wait_manager's role is keeping all data required to handle waiting for other
+ * clients in sessiond (between performing an operation and emitting the
+ * Completed signal). This includes keeping track of performed operations and
+ * waiting clients, but also doing timeouts and making sure the clients haven't
+ * disappeared from DBus. Finally, wait_manager emits the Completed signal.
+ *
+ * Since the type of required parameters and signals changes a bit between
+ * operations, wait_manager is a template and takes parameters which modify said
+ * type. Both parameters are tuples; Primary contains the parameters that are
+ * needed to recognise a single call (often subsession ID; conceptually this is
+ * the equivalent of the primary key, hence the name), and Secondary contains
+ * all other parameters of this call. For instance, in the case of the
+ * SwitchUser operation, which is recognised by the automatically generated
+ * switch_id (uint64_t), but also is associated with the previous and current
+ * subsession IDs (both int), you should have Primary = std::tuple<uint64_t>,
+ * Secondary = std::tuple<int, int>. This does not include the operation and
+ * session_uid, as you should have one instance of wait_manager per operation
+ * and session_uid.
+ *
+ * The following operations are available:
+ * - on_client_register, which you need to call when somebody registers for
+ *   waiting,
+ * - on_start, which you should call after you perform an operations and need to
+ *   start waiting,
+ * - on_client_done, which you need to call after one of the waiting clients is
+ *   done waiting.
+ * Additionally, as mentioned before, wait_manager will use GLib to keep track
+ * of the two additional conditions:
+ * - client disappearing from DBus, which is the same as calling on_client_done
+ *   on all eligible operations,
+ * - timeout (configurable in globals.hpp) elapsing from the on_start call,
+ *   which is the same as calling on_client_done on all eligible clients.
+ *
+ * After all on_client_done (or equivalent) are called, the Completed signal is
+ * emitted, containing data from both Primary and Secondary. The name of the
+ * signal is configurable in the constructor. Note that emitting the Started
+ * signal is not a responsibility of wait_manager; this is mostly because that
+ * was the most convenient way to do so (it's easy to just emit the Started
+ * signal in the caller, and emitting Completed outside of wait_manager would
+ * require some complex callbacks that we didn't feel like doing under time
+ * pressure we had at the moment).
+ *
+ * As mentioned, wait_manager has a nontrivial amount of responsibilites,
+ * probably too much; especially because it does both logic and IO operations.
+ * Since we aren't programming in Haskell :) this is not inherently problematic,
+ * but it does mean that this code is much less testable that it could be. This
+ * might be a good TODO, but one that is likely to never actually be done, and
+ * the code is not in a horrible shape right now (though I am NOT satisfied). */
+
 template<typename Primary, typename Secondary>
 class wait_manager {
 public: