notes on events

docs/sphinx/essentials.rst

@@ -3,6 +3,8 @@ Essentials
 
 Play with Maestro Core basic concepts.
 
+.. _cdo:
+
 Core Data Objects (CDOs)
 ------------------------
 
@@ -199,7 +201,7 @@ to keep track of the proceedings. Such events may be filtered using a selector
    mstro_cdo_selector_create( ..., "(has .maestro.core.cdo.name)",
                                       &selector);
 
-Subscribing to events if done with:
+Subscribing to events is done with
 
 .. code-block:: c
 
@@ -218,6 +220,9 @@ Then events may be polled
    mstro_pool_event event;
    mstro_subscription_poll(cdo_subscription, &event);
 
+.. NOTE::
+   ``mstro_subscription_poll()`` returns in *event* a list of events, where *event* is the head and where the next element is event->next.
+
 and inspected for CDO properties
 
 .. code-block:: c
@@ -228,6 +233,9 @@ and inspected for CDO properties
        cdo_name = event->offer.cdo_name;
        ...
 
+
+
+
 Groups
 ------
 

docs/sphinx/showroom.rst

@@ -7,14 +7,16 @@ Showroom
 Overview
 --------
 
-Component applications using Maestro Core offer and demand CDOs to and from the Maestro Pool, a conceptual entity which represents
-the set of resources contributed to Maestro, in particular the set of offered
-CDOs. One typical use of Maestro Core is bypassing persisent storage for
-application coupling, by way of the Maestro Pool.
+Component applications using Maestro Core offer and demand CDOs to and from the
+:ref:`Maestro Pool<cdo_management>`, a conceptual entity which represents the
+set of resources contributed to Maestro, in particular the set of offered CDOs.
+One typical use of Maestro Core is bypassing persistent storage for application
+coupling, by way of the Maestro Pool.
 
-CDOs contain data and metadata, including user-defined metadata plus data
-semantics such as data layout information and other information on the data
-usage the scheduler may take advantage of.
+:ref:`CDOs<cdo>` are basically Maestro Core currency, they contain data and metadata,
+including user-defined metadata plus data semantics such as data layout
+information and other information on the data usage the transfer scheduler may
+take advantage of.
 
 A minimal Maestro-enabled multi-app setup would consist in one producer
 application, one consumer application and one Pool Manager application, the
@@ -30,7 +32,7 @@ pool events for inspection.
 workflow, and interfacing with many useful components. In particular, they
 allow the implementation of data-driven Workflow Managers or more generally
 Execution Frameworks, meaning they can schedule jobs based on CDO availability
-and location which is indeed signaled by events. :ref:`Data
+and location which is indeed notified by events. :ref:`Data
 management<cdo_management>` (and :ref:`memory management<mamba>` as well)  is
 then effectively delegated by Execution Frameworks and applications to Maestro
 Core.
@@ -68,7 +70,7 @@ through
 
 - Logger sample application ``simple_telemetry_listener``
 
-- Archiver sample application ``simple archiver``
+- Archiver sample application ``simple_archiver``