stories

docs/sphinx/stories.rst

@@ -3,6 +3,8 @@ Users' Stories
 
 "How can I do [...] with Maestro Core?"
 
+.. _user-metadata:
+
 User metadata
 -------------
 
@@ -48,6 +50,7 @@ attributes<metadata>`.
                            ".maestro.my-namespace.my-key",
                            &value, ...);
 
+.. _story_cherry:
 
 Cherry-pick CDOs of interest based on metadata
 ----------------------------------------------
@@ -115,6 +118,8 @@ consumer CDO thanks to their identical name, and transparently performs the
 transformation on the DEMANDer, and ensures the CDO is in the requested layout
 when the DEMAND returns.
 
+.. _withdraw-early:
+
 Not let producers withdraw early
 --------------------------------
 
@@ -152,3 +157,28 @@ which means the consumer here, upon receiving the ``offer`` event, may
 ``declare`` and ``require`` the CDO associated with the event, before it may be
 ``withdrawn``, because the producer component cannot proceed, in that the
 ``mstro_cdo_offer`` is not returning before receiving the ``offer_ack``.
+
+Making sure an app is up and running with Maestro core
+------------------------------------------------------
+
+CDOs may also be used as semaphores in a sense. An app may notify its readiness
+with an empty CDO
+
+.. code-block:: c
+
+    mstro_cdo_declare(CDO_READY_NAME, MSTRO_ATTR_DEFAULT, &cdo_ready);
+    mstro_cdo_offer(cdo_ready);
+
+And typically ``withdraw`` and ``dispose`` at the very end, when it is
+effectively not *ready* to work anymore. On the other side, apps willing to
+check its readiness would
+
+.. code-block:: c
+
+    mstro_cdo_declare(CDO_READY_NAME, MSTRO_ATTR_DEFAULT, &cdo_ready);
+    mstro_cdo_require(cdo_ready);
+    mstro_cdo_demand(cdo_ready);
+    mstro_cdo_dispose(cdo_ready);
+
+When ``demand`` returns, the probing app is certain the sender is *ready*.
+