From 6ed4ba46d60833dd9414b55c8314732eb2d18345 Mon Sep 17 00:00:00 2001
From: Christopher Haine <chaine@hpe.com>
Date: Tue, 6 Sep 2022 18:23:37 +0200
Subject: [PATCH] stories
---
docs/sphinx/stories.rst | 30 ++++++++++++++++++++++++++++++
1 file changed, 30 insertions(+)
diff --git a/docs/sphinx/stories.rst b/docs/sphinx/stories.rst
index 96f9bdfa..7068d898 100644
--- a/docs/sphinx/stories.rst
+++ b/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*.
+
--
GitLab