diff --git a/docs/sphinx/stories.rst b/docs/sphinx/stories.rst index 96f9bdfa96a5f20a77e3e8a8aaf74d856adaa83f..7068d8984d3a4657bc3a88afb1c38bd58324a30d 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*. +