From b3b6f7524c8a83b87dc7347d9cffbc00eeefb4f6 Mon Sep 17 00:00:00 2001
From: Ichthyostega <prg@ichthyostega.de>
Date: Sat, 2 Sep 2023 22:36:02 +0200
Subject: [PATCH] Activity-Lang: outline for wiring async IO activities

...relies on the same building pattern, with the notable difference
that the chain is severed, providing an additional NOTIFY as re-entrance point
---
 src/vault/gear/activity-lang.hpp             |  9 +++++
 src/vault/gear/activity-term.hpp             | 12 ++++++
 tests/vault/gear/scheduler-activity-test.cpp | 34 ++++++++++++++++-
 wiki/thinkPad.ichthyo.mm                     | 40 +++++++++++++++++++-
 4 files changed, 91 insertions(+), 4 deletions(-)

diff --git a/src/vault/gear/activity-lang.hpp b/src/vault/gear/activity-lang.hpp
index f98864c80..181ca0c23 100644
--- a/src/vault/gear/activity-lang.hpp
+++ b/src/vault/gear/activity-lang.hpp
@@ -86,6 +86,15 @@ namespace gear {
           return setupActivityScheme (activity::Term::CALC_JOB, job, start, deadline);
         }
       
+      /**
+       * Builder-API: initiate definition of IO data loading activities.
+       */
+      activity::Term
+      buildAsyncLoadJob (Job job, Time start, Time deadline)
+        {
+          return setupActivityScheme (activity::Term::LOAD_JOB, job, start, deadline);
+        }
+      
       /**
        * Builder-API: initiate definition of internal/planning job.
        */
diff --git a/src/vault/gear/activity-term.hpp b/src/vault/gear/activity-term.hpp
index acdda11fd..5161ac687 100644
--- a/src/vault/gear/activity-term.hpp
+++ b/src/vault/gear/activity-term.hpp
@@ -87,6 +87,7 @@ namespace gear {
         Activity* post_{nullptr};
         
         Activity* gate_{nullptr};
+        Activity* callback_{nullptr};
         
         
       public:
@@ -126,6 +127,17 @@ namespace gear {
             return *post_;
           }
         
+        /**
+         * @return re-entrance point for completion after async IO.
+         * @remark initiate follow-up processing by ActivityLang::dispatchChain().
+         */
+        Activity&
+        callback()
+          {
+            REQUIRE (callback_, "Activity Term properly configured for async IO");
+            return *callback_;
+          }
+        
         /**
          * Builder operation: block this Term waiting for prerequisite notification.
          * @param notificationSrc an `NOTIFY`-Activity to attach the notification-link
diff --git a/tests/vault/gear/scheduler-activity-test.cpp b/tests/vault/gear/scheduler-activity-test.cpp
index 6b4c2b467..1aab8eeb8 100644
--- a/tests/vault/gear/scheduler-activity-test.cpp
+++ b/tests/vault/gear/scheduler-activity-test.cpp
@@ -457,7 +457,7 @@ namespace test {
       
       
       /** @test usage scenario: Activity graph for a simple render job
-       *        - build a activity term based on the »CalculationJob« wiring template
+       *        - build an activity term based on the »CalculationJob« wiring template
        *        - dispatch the generated Activity chain and verify sequence of invocations
        */
       void
@@ -581,16 +581,46 @@ namespace test {
                                                              .arg("<0, until -85401592:56:01.825"));         // ... but the Gate has been closed permanently (by setting the deadline to Time::MIN)
           CHECK (detector.ensureNoInvocation("testJob")                                                      // ==>  no further invocation
                          .afterInvocation("trigger").seq(2));
+          
+//        cout << detector.showLog()<<endl; // HINT: use this for investigation...
         }
       
       
       
       /** @test TODO usage scenario: Activity graph for an async Job
-       * @todo WIP 8/23 🔁 define ⟶ implement
+       *        - use a simple [calculation job term](\ref #scenario_RenderJob) as follow-up receiver
+       *        - build an activity Term based on the »Async Load Job« wiring and link it to the receiver
+       *        - also retrieve the Activity record used as re-entrance point after completing async IO
+       * @todo WIP 8/23 ✔ define 🔁 implement
        */
       void
       scenario_IOJob()
         {
+          Time nominal{7,7};
+          
+          Time start{0,1};
+          Time dead{0,10};
+          
+          ActivityDetector detector;
+          Job loadJob{detector.buildMockJob("loadJob", nominal, 12345)};
+          Job calcJob{detector.buildMockJob("calcJob", nominal, 54321)};
+
+          BlockFlowAlloc bFlow;
+          ActivityLang activityLang{bFlow};
+          
+          auto followup = activityLang.buildCalculationJob (calcJob, start,dead);
+          auto loadTerm = activityLang.buildAsyncLoadJob (loadJob, start,dead)
+                                      .appendNotificationTo (followup);
+          
+          Activity& anchor = loadTerm.post();
+          Activity& notify = loadTerm.callback();
+          
+          ActivityLang::dispatchChain (anchor, detector.executionCtx);
+          
+          detector.incrementSeq();
+          ActivityLang::dispatchChain (notify, detector.executionCtx);
+          
+          cout << detector.showLog()<<endl;
         }
       
       
diff --git a/wiki/thinkPad.ichthyo.mm b/wiki/thinkPad.ichthyo.mm
index bbadf5070..1d3a16013 100644
--- a/wiki/thinkPad.ichthyo.mm
+++ b/wiki/thinkPad.ichthyo.mm
@@ -77644,8 +77644,12 @@ Date:&#160;&#160;&#160;Thu Apr 20 18:53:17 2023 +0200<br/>
 </node>
 </node>
 <node CREATED="1693178794380" ID="ID_491437643" MODIFIED="1693178801062" TEXT="optional / on-demand">
-<node CREATED="1693178805562" ID="ID_1048207081" MODIFIED="1693178814853" TEXT="Gate falls Notify aufgeschaltet"/>
-<node CREATED="1693178815720" ID="ID_1614785974" MODIFIED="1693178820772" TEXT="Gate falls Deadline definiert"/>
+<node COLOR="#338800" CREATED="1693178805562" ID="ID_1048207081" MODIFIED="1693686526300" TEXT="Gate falls Notify aufgeschaltet">
+<icon BUILTIN="button_ok"/>
+</node>
+<node BACKGROUND_COLOR="#eee5c3" COLOR="#990000" CREATED="1693686465783" ID="ID_1698611033" MODIFIED="1693686530330" TEXT="Callback-Notify f&#xfc;r async IO">
+<icon BUILTIN="flag-yellow"/>
+</node>
 </node>
 </node>
 <node BACKGROUND_COLOR="#d2beaf" COLOR="#5c4d6e" CREATED="1693223697516" ID="ID_1843732510" MODIFIED="1693268995911" TEXT="Problem: Deadline bestimmen">
@@ -80276,6 +80280,9 @@ Date:&#160;&#160;&#160;Thu Apr 20 18:53:17 2023 +0200<br/>
 <node BACKGROUND_COLOR="#eee5c3" COLOR="#990000" CREATED="1693323299522" ID="ID_392906930" MODIFIED="1693323317032" TEXT="Grundstruktur verdrahten">
 <icon BUILTIN="flag-yellow"/>
 </node>
+<node BACKGROUND_COLOR="#eee5c3" COLOR="#990000" CREATED="1693684632678" ID="ID_1092577366" LINK="#ID_1698611033" MODIFIED="1693686505258" TEXT="Zugriff auf den Callback-Trigger">
+<icon BUILTIN="flag-yellow"/>
+</node>
 <node BACKGROUND_COLOR="#eee5c3" COLOR="#990000" CREATED="1693432167704" ID="ID_1355575152" MODIFIED="1693432176339" TEXT="Anh&#xe4;ngen einer Folge-Notification">
 <icon BUILTIN="flag-yellow"/>
 </node>
@@ -82804,6 +82811,35 @@ Date:&#160;&#160;&#160;Thu Apr 20 18:53:17 2023 +0200<br/>
 <linktarget COLOR="#b22e63" DESTINATION="ID_1493396541" ENDARROW="Default" ENDINCLINATION="-1383;-51;" ID="Arrow_ID_847435526" SOURCE="ID_48632766" STARTARROW="None" STARTINCLINATION="-753;40;"/>
 <icon BUILTIN="flag-yellow"/>
 </node>
+<node BACKGROUND_COLOR="#d2beaf" COLOR="#5c4d6e" CREATED="1693684904305" ID="ID_887857937" MODIFIED="1693684935612" TEXT="Entscheidung: nominal time oder explizite Framenummer">
+<icon BUILTIN="yes"/>
+<icon BUILTIN="hourglass"/>
+<node CREATED="1693684958202" ID="ID_1211986246" MODIFIED="1693685119943" TEXT="Framenummer w&#xe4;re die offensichtliche L&#xf6;sung">
+<richcontent TYPE="NOTE"><html>
+  <head/>
+  <body>
+    <p>
+      und zwar &#187;point and shot&#171; &#8212; es mu&#223; genau die Implementierungs-Framenummer sein, die dann f&#252;r die Verarbeitung wirklich gebraucht wird (und welche ist das?? ... wer wei&#223; das???)
+    </p>
+  </body>
+</html></richcontent>
+<icon BUILTIN="smiley-oh"/>
+</node>
+<node CREATED="1693684939893" ID="ID_1837303645" MODIFIED="1693685363183" TEXT="mein Bauchgef&#xfc;hl sagt: Zeit ist generischer">
+<richcontent TYPE="NOTE"><html>
+  <head/>
+  <body>
+    <p>
+      da hinter der Invocation stets ein JobFunctor steht, der &#252;ber eine Closure Zugriff auf konkrete Kontext-Informationen hat &#8212; das einzige Prinzip in der f&#252;r Lumiera entwickelten offenen Daten-Architektur ist, da&#223; alles zu Berechnende <i>zeitlich eingeordnet werden kann. </i>Damit sollte jedwede Aktivit&#228;t anhand der Zeitangabe im Stande sein, ihre konkrete Parametrisierung abzuleiten. Das Wichtige dabei: <b>diese Ableitung bleibt ein lokales Detail</b>. Der Planungs-Proze&#223; mu&#223; es &#252;berhaupt nicht wissen
+    </p>
+  </body>
+</html></richcontent>
+</node>
+<node BACKGROUND_COLOR="#d2beaf" COLOR="#5c4d6e" CREATED="1693685364237" ID="ID_186112523" MODIFIED="1693685388978" TEXT="letztlich erst mit wachsender Praxis zu entscheiden">
+<icon BUILTIN="yes"/>
+<icon BUILTIN="hourglass"/>
+</node>
+</node>
 </node>
 <node BACKGROUND_COLOR="#eee5c3" COLOR="#990000" CREATED="1692108072539" ID="ID_1827409996" MODIFIED="1692108369187" TEXT="Umgang mit Fehlern">
 <arrowlink COLOR="#6f6ea7" DESTINATION="ID_774705986" ENDARROW="Default" ENDINCLINATION="-559;-416;" ID="Arrow_ID_1863875541" STARTARROW="None" STARTINCLINATION="-199;23;"/>