activity.hpp

Go to the documentation of this file.

/*
  ACTIVITY.hpp  -  elementary operation to be handled by the scheduler

  Copyright (C)         Lumiera.org
    2023,               Hermann Vosseler <Ichthyostega@web.de>

  This program is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License as
  published by the Free Software Foundation; either version 2 of
  the License, or (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

*/


#ifndef SRC_VAULT_GEAR_ACTIVITY_H_
#define SRC_VAULT_GEAR_ACTIVITY_H_


#include "vault/common.hpp"
#include "vault/gear/job.h"
#include "lib/time/timevalue.hpp"
#include "lib/meta/function.hpp"
#include "lib/util.hpp"


namespace vault{
namespace gear {
  
  using lib::time::TimeValue;
  using lib::time::TimeVar;
  using lib::time::Offset;
  
  namespace error = lumiera::error;
  

  class ManifestationID
    {
      uint32_t id_;
      
    public:
      ManifestationID (uint32_t rawID =0)
        : id_{rawID}
        { }
      // standard copy operations acceptable
      
      explicit operator uint32_t()  const { return id_;}
      explicit operator bool()      const { return id_ != 0; }
      
      friend bool operator== (ManifestationID const& a, ManifestationID const& b) { return a.id_ == b.id_; }
      friend bool operator!= (ManifestationID const& a, ManifestationID const& b) { return not (a == b);   }
    };
  HashVal hash_value (ManifestationID const& id);
  
  class Activity;
  
  
  namespace activity { 
    
    class Instant
      {
        int64_t microTick_;
        
      public:
        Instant()  =default;  // @suppress("Class members should be properly initialized")
        
        Instant(TimeValue time)
          : microTick_{_raw(time)}
        { }
        
        operator TimeVar()  const
          {
            return TimeValue{microTick_};
          }
        
        // default copy acceptable
      };
    
    
    enum Proc {PASS  
              ,SKIP  
              ,WAIT  
              ,KICK  
              ,HALT  
              };
    
    
    class Hook
      {
      public:
        virtual ~Hook();  
        
        virtual Proc activation ( Activity& thisHook
                                , Time now
                                , void* executionCtx)  =0;
        
        virtual Proc notify     ( Activity& thisHook
                                , Time now
                                , void* executionCtx)  =0;
        
        virtual Time getDeadline() const               =0;
        
        virtual std::string
        diagnostic()  const
          {
            return "Activity::Hook";
          }
        
        operator std::string()  const
          {
            return diagnostic();
          }
      };
    
    
    template<class EXE>
    constexpr void
    _verify_usable_as_ExecutionContext ()
    {
      ASSERT_MEMBER_FUNCTOR (&EXE::post, Proc(Time, Time, Activity*, EXE&));
      ASSERT_MEMBER_FUNCTOR (&EXE::work, void(Time, size_t));
      ASSERT_MEMBER_FUNCTOR (&EXE::done, void(Time, size_t));
      ASSERT_MEMBER_FUNCTOR (&EXE::tick, Proc(Time));
      
      ASSERT_MEMBER_FUNCTOR (&EXE::getSchedTime, Time());
    }
    
  }//(End)namespace activity
  
  
  
  
  /*********************************************/
  class Activity
    {
      using Instant = activity::Instant;
      
    public:
      enum Verb {INVOKE     
                ,WORKSTART  
                ,WORKSTOP   
                ,NOTIFY     
                ,GATE       
                ,POST       
                ,FEED       
                ,HOOK       
                ,TICK       
                };
      
      const Verb verb_;
      
      Activity* next;
      
      
      /* === Activity Data Arguments === */
      
      struct Feed
        {
          uint64_t one;
          uint64_t two;
        };
      
      struct Timing
        {
          Instant instant;                
          size_t  quality;
        };
      
      struct Callback
        {
          activity::Hook* hook;
          size_t  arg;
        };
      
      struct Condition
        {
          int     rest;     
          Instant dead;     
          
          bool isDead (Time now)  const { return dead <= now;}
          bool isHold ()          const { return rest > 0;   }
          bool isFree (Time now)  const { return not (isHold() or isDead(now)); }
          Time getDeadline()      const { return Time{dead}; }
          void incDependencies()        { ++rest; }
          
          Time
          lockPermanently()
            {
              auto oldDeadline{dead};
              dead = Time::MIN;
              return Time{oldDeadline};
            }
        };
      
      struct TimeWindow
        {
          Instant life;
          Instant dead;
        };
      
      struct Invocation
        {
          JobFunctor* task;
          Instant     time;
        };
      
      struct Notification
        {
          Activity* target;
          Instant   timing;
        };
      
      
      union ArgumentData
        {
                Feed feed;
              Timing timing;
            Callback callback;
           Condition condition;
          TimeWindow timeWindow;
          Invocation invocation;
        Notification notification;
        };
      ArgumentData data_;
      
      
      explicit
      Activity (Verb verb)  noexcept
        : verb_{verb}
        , next{nullptr}
        {
          setDefaultArg (verb);
        }
      
      // using default copy/assignment
      
      
      /* ==== special case initialisation ==== */
      
      Activity (uint64_t o1, uint64_t o2)  noexcept
        : Activity{FEED}
        {
          data_.feed.one = o1;
          data_.feed.two = o2;
        }
      
      Activity (JobFunctor& job, Time nominalTime, Activity& feed)  noexcept
        : Activity{INVOKE}
        {
          data_.invocation.task = &job;
          data_.invocation.time = nominalTime;
          next = &feed;
        }
      
      explicit
      Activity (Activity* target, Time limitWhen =Time::ANYTIME)  noexcept
        : Activity{NOTIFY}
        {
          data_.notification.target = target;
          data_.notification.timing = limitWhen;
        }
      
      explicit
      Activity (int expectNotifications, Time deadline = Time::NEVER)  noexcept
        : Activity{GATE}
        {
          data_.condition.rest = expectNotifications;
          data_.condition.dead = deadline;
        }
      
      Activity (Time when, Activity* followUp)  noexcept
        : verb_{POST}
        , next{followUp}
        {
          data_.timeWindow = {when,when};
        }
      
      Activity (Time start, Time after, Activity* followUp)  noexcept
        : verb_{POST}
        , next{followUp}
        {
          data_.timeWindow = {start,after};
        }
      
      Activity (activity::Hook& callback, size_t arg)  noexcept
        : Activity{HOOK}
        {
          data_.callback.hook = &callback;
          data_.callback.arg = arg;
        }
      
      Activity()  noexcept
        : Activity{TICK}
        { }
      
      operator std::string()  const;
      
      std::string showVerb()  const;
      std::string showData()  const;
      
      
      /********************************************************/
      template<class EXE>
      activity::Proc activate (Time now, EXE& executionCtx);
      
      template<class EXE>
      activity::Proc dispatch (Time now, EXE& executionCtx);
      
      
      /* === special case access and manipulation === */
      bool
      is (Activity::Verb expectedVerb)  const
        {
          return expectedVerb == this->verb_;
        }
      
      void
      incDependencies()
        {
          REQUIRE (is (GATE));
          data_.condition.incDependencies();
        }
      
      void
      setNotificationTarget (Activity* target, Time limitStart =Time::ANYTIME)
        {
          REQUIRE (is (NOTIFY));
          data_.notification.target = target;
          data_.notification.timing = limitStart;
        }
      
      Time
      constrainedStart (Time start)   
        {
          return is(POST)? util::max (start, Time{data_.timeWindow.life})
                         : start;
        }
      
      Time
      constrainedDeath (Time death)   
        {
          return is(POST)? util::min (death, Time{data_.timeWindow.dead})
                         : death;
        }
      
      
    private:
      void
      setDefaultArg (Verb verb)  noexcept
        {
          data_ = {0,0};
          switch (verb) {
            case INVOKE:
              data_.invocation.time = Time::ANYTIME;
              break;
            case WORKSTART:
            case WORKSTOP:
              data_.timing.instant = Time::NEVER;
              break;
            case GATE:
              data_.condition.rest = 1;
              data_.condition.dead = Time::NEVER;
              break;
            case POST:
              data_.timeWindow.life = Time::ANYTIME;
              data_.timeWindow.dead = Time::NEVER;
              break;
            default:
              break;
            }
        }
      
      
      activity::Proc
      invokeFunktor (Time)  noexcept
        {
          REQUIRE (verb_ == INVOKE);
          REQUIRE (next);
          REQUIRE (next->verb_ == FEED);
          REQUIRE (next->next);
          REQUIRE (next->next->verb_ == FEED);
          REQUIRE (data_.invocation.task);
          
          JobClosure& functor = static_cast<JobClosure&> (*data_.invocation.task);      
          lumiera_jobParameter param;
          param.nominalTime = _raw(Time{data_.invocation.time});
          param.invoKey.code.w1 = next->data_.feed.one;
          param.invoKey.code.w2 = next->data_.feed.two;
          try {
              functor.invokeJobOperation (param);
            }
          ON_EXCEPTION_RETURN (activity::HALT, "Render Job invocation");
          //
          return activity::PASS;
        }
      
      
      template<class EXE>
      activity::Proc
      signalStart (Time now, EXE& executionCtx)
        {
          executionCtx.work (now, data_.timing.quality);
          return activity::PASS;
        }
      
      template<class EXE>
      activity::Proc
      signalStop (Time now, EXE& executionCtx)
        {
          executionCtx.done (now, data_.timing.quality);
          return activity::PASS;
        }
      
      template<class EXE>
      activity::Proc
      checkGate (Time now, EXE&)
        {
          REQUIRE (GATE == verb_);
          if (data_.condition.isDead(now))  // beyond deadline
            return activity::SKIP;
          if (data_.condition.isHold())     // prerequisite count not(yet) fulfilled -> block further activation
            return activity::SKIP;
          else
            return activity::PASS;
        }
      
      activity::Proc
      receiveGateNotification (Time now)
        {
          REQUIRE (GATE == verb_);
          if (data_.condition.rest > 0)
            {
              --data_.condition.rest;
              // maybe the Gate has been opened by this notification?
              if (data_.condition.isFree(now))
                {//yes => activate gated chain but lock redundant invocations
                  data_.condition.lockPermanently();
                  return activity::PASS;
            }   }
          return activity::SKIP;
        }
      
      template<class EXE>
      activity::Proc
      postSelf (Time now, EXE& executionCtx)
        {
          REQUIRE (next);
          if (is(POST))
            return executionCtx.post (Time{data_.timeWindow.life},Time{data_.timeWindow.dead}, this, executionCtx);
          else
            return executionCtx.post (now,Time::NEVER, this, executionCtx);
        }
      
      template<class EXE>
      activity::Proc
      postNotify (Time now, EXE& executionCtx)
        {
          REQUIRE (is(NOTIFY));
          Activity* target = data_.notification.target;
          REQUIRE (target);
          REQUIRE (not target->is(HOOK) or target->data_.callback.hook);
          Time startHint = target->is(GATE) or
                           target->is(HOOK)? Time{data_.notification.timing}
                                           : now;
          Time deadline  = target->is(GATE)? target->data_.condition.getDeadline()
                         : target->is(HOOK)? target->data_.callback.hook->getDeadline()
                                           : Time::NEVER;
          // indirectly forward to Activity::dispatch()
          return executionCtx.post (startHint,deadline, target, executionCtx);
        }
      
      template<class EXE>
      activity::Proc
      callHook (Time now, EXE& executionCtx)
        {
          return data_.callback.hook? data_.callback.hook->activation(*this, now, &executionCtx)
                                    : activity::PASS;
        }
      
      template<class EXE>
      activity::Proc
      notifyHook (Time now, EXE& executionCtx)
        {
          return data_.callback.hook? data_.callback.hook->notify (*this, now, &executionCtx)
                                    : activity::PASS;
        }
      
      template<class EXE>
      activity::Proc
      doTick (Time now, EXE& executionCtx)
        {
          return executionCtx.tick (now);
        }
    };
  
  
  
  
  template<class EXE>
  activity::Proc
  Activity::activate (Time now, EXE& executionCtx)
  {
    activity::_verify_usable_as_ExecutionContext<EXE>();
    
    switch (verb_) {
      case INVOKE:
        return invokeFunktor (now);
      case WORKSTART:
        return signalStart (now, executionCtx);
      case WORKSTOP:
        return signalStop (now, executionCtx);
      case NOTIFY:
        return postNotify (now, executionCtx);
      case POST:
        return postSelf  (now, executionCtx);
      case GATE:
        return checkGate (now, executionCtx);
      case FEED:
        return activity::PASS;
      case HOOK:
        return callHook (now, executionCtx);
      case TICK:
        return doTick (now, executionCtx);
      default:
        NOTREACHED ("uncovered Activity verb in activation function.");
      }
  }
  

  template<class EXE>
  activity::Proc
  Activity::dispatch (Time now, EXE& executionCtx)
  {
    activity::_verify_usable_as_ExecutionContext<EXE>();
    
    switch (verb_) {
      case POST:
      case FEED:      // signal just to proceed with next...
        return activity::PASS;
      case GATE:
        return receiveGateNotification (now);
      case HOOK:
        return notifyHook (now, executionCtx);
      default:
        return activate (now, executionCtx);
      }
  }
  
  
}} // namespace vault::gear
#endif /*SRC_VAULT_GEAR_ACTIVITY_H_*/