Coroutine.h

Go to the documentation of this file.

/*
MIT License
 
Copyright (c) 2018 Brian T. Park
 
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
 
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
*/
 
#ifndef ACE_ROUTINE_COROUTINE_H
#define ACE_ROUTINE_COROUTINE_H
 
#include <stdint.h> // UINT16_MAX
#include <Print.h> // Print
#include <AceCommon.h> // PrintStr<>
#include "CoroutineProfiler.h"
#include "ClockInterface.h"
#include "compat.h" // PROGMEM
 
class __FlashStringHelper;
class AceRoutineTest_statusStrings;
class SuspendTest_suspendAndResume;
 
// https://stackoverflow.com/questions/295120
#if defined(__GNUC__) || defined(__clang__)
  #define ACE_ROUTINE_DEPRECATED __attribute__((deprecated))
#elif defined(_MSC_VER)
  #define ACE_ROUTINE_DEPRECATED __declspec(deprecated)
#else
  #pragma message("WARNING: Implement ACE_ROUTINE_DEPRECATED for this compiler")
  #define ACE_ROUTINE_DEPRECATED
#endif
 
#define COROUTINE(...) \
    GET_COROUTINE(__VA_ARGS__, COROUTINE2, COROUTINE1)(__VA_ARGS__)
 
#define GET_COROUTINE(_1, _2, NAME, ...) NAME
 
#define COROUTINE1(name) \
struct Coroutine_##name : ace_routine::Coroutine { \
  Coroutine_##name(); \
  int runCoroutine() override; \
} name; \
Coroutine_##name :: Coroutine_##name() { \
} \
int Coroutine_##name :: runCoroutine()
 
#define COROUTINE2(className, name) \
struct className##_##name : className { \
  className##_##name(); \
  int runCoroutine() override; \
} name; \
className##_##name :: className##_##name() { \
} \
int className##_##name :: runCoroutine()
 
#define EXTERN_COROUTINE(...) \
    GET_EXTERN_COROUTINE(\
        __VA_ARGS__, EXTERN_COROUTINE2, EXTERN_COROUTINE1)(__VA_ARGS__)
 
#define GET_EXTERN_COROUTINE(_1, _2, NAME, ...) NAME
 
#define EXTERN_COROUTINE1(name) \
struct Coroutine_##name : ace_routine::Coroutine { \
  Coroutine_##name(); \
  int runCoroutine() override; \
}; \
extern Coroutine_##name name
 
#define EXTERN_COROUTINE2(className, name) \
struct className##_##name : className { \
  className##_##name(); \
  int runCoroutine() override; \
}; \
extern className##_##name name
 
#define COROUTINE_BEGIN() \
    void* p = this->getJump(); \
    if (p != nullptr) { \
      goto *p; \
    }
 
#define COROUTINE_LOOP() \
   COROUTINE_BEGIN(); \
   while (true) \
 
#define COROUTINE_YIELD_INTERNAL() \
    do { \
      __label__ jumpLabel; \
      this->setJump(&& jumpLabel); \
      return 0; \
      jumpLabel: ; \
    } while (false)
 
#define COROUTINE_YIELD() \
    do { \
      this->setYielding(); \
      COROUTINE_YIELD_INTERNAL(); \
      this->setRunning(); \
    } while (false)
 
#define COROUTINE_AWAIT(condition) \
    do { \
      this->setYielding(); \
      do { \
        COROUTINE_YIELD_INTERNAL(); \
      } while (!(condition)); \
      this->setRunning(); \
    } while (false)
 
#define COROUTINE_DELAY(delayMillis) \
    do { \
      this->setDelayMillis(delayMillis); \
      this->setDelaying(); \
      do { \
        COROUTINE_YIELD_INTERNAL(); \
      } while (!this->isDelayExpired()); \
      this->setRunning(); \
    } while (false)
 
#define COROUTINE_DELAY_MICROS(delayMicros) \
    do { \
      this->setDelayMicros(delayMicros); \
      this->setDelaying(); \
      do { \
        COROUTINE_YIELD_INTERNAL(); \
      } while (!this->isDelayMicrosExpired()); \
      this->setRunning(); \
    } while (false)
 
#define COROUTINE_DELAY_SECONDS(delaySeconds) \
    do { \
      this->setDelaySeconds(delaySeconds); \
      this->setDelaying(); \
      do { \
        COROUTINE_YIELD_INTERNAL(); \
      } while (!this->isDelaySecondsExpired()); \
      this->setRunning(); \
    } while (false)
 
#define COROUTINE_END() \
    do { \
      __label__ jumpLabel; \
      this->setEnding(); \
      this->setJump(&& jumpLabel); \
      jumpLabel: ; \
      return 0; \
    } while (false)
 
namespace ace_routine {
 
extern const __FlashStringHelper* const sStatusStrings[] PROGMEM;
 
// Forward declaration of CoroutineSchedulerTemplate<T>
template <typename T> class CoroutineSchedulerTemplate;
 
template <typename T_CLOCK, typename T_DELAY>
class CoroutineTemplate {
  friend class CoroutineSchedulerTemplate<CoroutineTemplate<T_CLOCK, T_DELAY>>;
  friend class ::AceRoutineTest_statusStrings;
  friend class ::SuspendTest_suspendAndResume;
 
  public:
    static const uint8_t kNameTypeCString = 0;
 
    static const uint8_t kNameTypeFString = 1;
 
  public:
    virtual int runCoroutine() = 0;
 
    virtual void setupCoroutine() {}
 
    int runCoroutineWithProfiler() {
      if (mProfiler) {
        uint32_t startMicros = coroutineMicros();
        runCoroutine();
        uint32_t elapsedMicros = coroutineMicros() - startMicros;
        mProfiler->updateElapsedMicros(elapsedMicros);
        return 0;
      } else {
        return runCoroutine();
      }
    }
 
    uint8_t getNameType() const { return mNameType; }
 
    void setName(const char* name) {
      mNameType = kNameTypeCString;
      mName = name;
    }
 
    void setName(const __FlashStringHelper* name) {
      mNameType = kNameTypeFString;
      mName = name;
    }
 
    const char* getCName() const { return (const char*) mName; }
 
    const __FlashStringHelper* getFName() const {
      return (const __FlashStringHelper*) mName;
    }
 
    void printNameTo(Print& printer, uint8_t maxLen = 0) const {
      // Need to go through this contortion because vsnprintf() does not support
      // flash string parameters, so I can't use something like "%12.12s" with
      // a flash string.
      ace_common::PrintStr<64> pname;
 
      if (mName == nullptr) {
        pname.print("0x");
        pname.print((uintptr_t) this, 16);
      } else if (mNameType == kNameTypeCString) {
        pname.print((const char*) mName);
      } else {
        pname.print((const __FlashStringHelper*) mName);
      }
 
      // Print name, truncated to maxLen or padded to maxLen.
      if (maxLen) {
        if (pname.length() < maxLen) {
          printer.write(pname.cstr());
          for (uint8_t i = pname.length(); i < maxLen; i++) {
            printer.write(' ');
          }
        } else {
          // NOTE: Must cast to (const uint8_t*) because the ATtiny85 core does
          // not have a version of write() that accepts a (const char*), in
          // contrast to every other Arduino Core.
          printer.write((const uint8_t*) pname.cstr(), maxLen);
        }
      } else {
        printer.write(pname.cstr());
      }
    }
 
    void suspend() {
      if (isDone()) return;
      mStatus = kStatusSuspended;
    }
 
    void resume() {
      if (mStatus != kStatusSuspended) return;
 
      // We lost the original state of the coroutine when suspend() was called
      // but the coroutine will automatically go back into the original state
      // when Coroutine::runCoroutine() is called because COROUTINE_YIELD(),
      // COROUTINE_DELAY() and COROUTINE_AWAIT() are written to restore their
      // status.
      mStatus = kStatusYielding;
    }
 
    void reset() {
      mStatus = kStatusYielding;
      mJumpPoint = nullptr;
    }
 
    bool isDelayExpired() const {
      T_DELAY nowMillis = coroutineMillis();
      T_DELAY elapsed = nowMillis - mDelayStart;
      return elapsed >= mDelayDuration;
    }
 
    bool isDelayMicrosExpired() const {
      T_DELAY nowMicros = coroutineMicros();
      T_DELAY elapsed = nowMicros - mDelayStart;
      return elapsed >= mDelayDuration;
    }
 
    bool isDelaySecondsExpired() const {
      T_DELAY nowSeconds = coroutineSeconds();
      T_DELAY elapsed = nowSeconds - mDelayStart;
      return elapsed >= mDelayDuration;
    }
 
    bool isSuspended() const { return mStatus == kStatusSuspended; }
 
    bool isYielding() const { return mStatus == kStatusYielding; }
 
    bool isDelaying() const { return mStatus == kStatusDelaying; }
 
    bool isRunning() const { return mStatus == kStatusRunning; }
 
    bool isEnding() const { return mStatus == kStatusEnding; }
 
    bool isTerminated() const { return mStatus == kStatusTerminated; }
 
    bool isDone() const {
      return mStatus == kStatusEnding || mStatus == kStatusTerminated;
    }
 
    void setupCoroutine(const char* /*name*/) ACE_ROUTINE_DEPRECATED {}
 
    void setupCoroutine(const __FlashStringHelper* /*name*/)
        ACE_ROUTINE_DEPRECATED {}
 
    void setProfiler(CoroutineProfiler* profiler) { mProfiler = profiler; }
 
    CoroutineProfiler* getProfiler() const { return mProfiler; }
 
    static CoroutineTemplate** getRoot() {
      // Use a static variable inside a function to solve the static
      // initialization ordering problem.
      static CoroutineTemplate* root;
      return &root;
    }
 
    CoroutineTemplate** getNext() { return &mNext; }
 
  protected:
    typedef uint8_t Status;
 
    static const Status kStatusSuspended = 0;
 
    static const Status kStatusYielding = 1;
 
    static const Status kStatusDelaying = 2;
 
    static const Status kStatusRunning = 3;
 
    static const Status kStatusEnding = 4;
 
    static const Status kStatusTerminated = 5;
 
    CoroutineTemplate() {
      insertAtRoot();
    }
 
    ~CoroutineTemplate() = default;
 
    Status getStatus() const { return mStatus; }
 
    void statusPrintTo(Print& printer) {
      printer.print((const __FlashStringHelper*)
          pgm_read_ptr(&sStatusStrings[mStatus]));
    }
 
    void setJump(void* jumpPoint) { mJumpPoint = jumpPoint; }
 
    void* getJump() const { return mJumpPoint; }
 
    void setRunning() { mStatus = kStatusRunning; }
 
    void setYielding() { mStatus = kStatusYielding; }
 
    void setDelaying() { mStatus = kStatusDelaying; }
 
    void setEnding() { mStatus = kStatusEnding; }
 
    void setTerminated() { mStatus = kStatusTerminated; }
 
    void setDelayMillis(T_DELAY delayMillis) {
      mDelayStart = coroutineMillis();
 
      // If delayMillis is a compile-time constant, the compiler seems to
      // completely optimize away this bounds checking code.
      mDelayDuration = (delayMillis >= UINT16_MAX / 2)
          ? UINT16_MAX / 2
          : delayMillis;
    }
 
    void setDelayMicros(T_DELAY delayMicros) {
      mDelayStart = coroutineMicros();
 
      // If delayMicros is a compile-time constant, the compiler seems to
      // completely optimize away this bounds checking code.
      mDelayDuration = (delayMicros >= UINT16_MAX / 2)
          ? UINT16_MAX / 2
          : delayMicros;
    }
 
    void setDelaySeconds(T_DELAY delaySeconds) {
      mDelayStart = coroutineSeconds();
 
      // If delaySeconds is a compile-time constant, the compiler seems to
      // completely optimize away this bounds checking code.
      mDelayDuration = (delaySeconds >= UINT16_MAX / 2)
          ? UINT16_MAX / 2
          : delaySeconds;
    }
 
    static unsigned long coroutineMillis() {
      return T_CLOCK::millis();
    }
 
    static unsigned long coroutineMicros() {
      return T_CLOCK::micros();
    }
 
    static unsigned long coroutineSeconds() {
      return T_CLOCK::seconds();
    }
 
  private:
    // Disable copy-constructor and assignment operator
    CoroutineTemplate(const CoroutineTemplate&) = delete;
    CoroutineTemplate& operator=(const CoroutineTemplate&) = delete;
 
    void insertAtRoot() {
      CoroutineTemplate** root = getRoot();
      mNext = *root;
      *root = this;
    }
 
  protected:
    CoroutineTemplate* mNext = nullptr;
 
    void* mJumpPoint = nullptr;
 
    const void* mName = nullptr;
 
    uint8_t mNameType = kNameTypeCString;
 
    Status mStatus = kStatusYielding;
 
    T_DELAY mDelayStart;
 
    T_DELAY mDelayDuration;
 
    CoroutineProfiler* mProfiler = nullptr;
};
 
using Coroutine = CoroutineTemplate<ClockInterface, uint16_t>;
 
}
 
#endif