procedure.h

Go to the documentation of this file.

#pragma once
 
// The full header, not json_fwd: ProgressStep holds a json by value (see its `value` member).
#include <cstdint>
#include <mutex>
#include <nlohmann/json.hpp>
#include <optional>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
 
namespace mm::node {
 
enum class ProgressStatus : uint8_t {
  kIdle,       
  kRunning,    
  kSucceeded,  
  kFailed,     
};
 
constexpr std::string_view toString(ProgressStatus status) {
  switch (status) {
    case ProgressStatus::kIdle:
      return "idle";
    case ProgressStatus::kRunning:
      return "running";
    case ProgressStatus::kSucceeded:
      return "succeeded";
    case ProgressStatus::kFailed:
      return "failed";
  }
  return "unknown";
}
 
enum class ProcedureStatus : uint8_t {
  kIdle,       
  kRunning,    
  kSucceeded,  
  kFailed,     
  kCancelled,  
};
 
constexpr std::string_view toString(ProcedureStatus status) {
  switch (status) {
    case ProcedureStatus::kIdle:
      return "idle";
    case ProcedureStatus::kRunning:
      return "running";
    case ProcedureStatus::kSucceeded:
      return "succeeded";
    case ProcedureStatus::kFailed:
      return "failed";
    case ProcedureStatus::kCancelled:
      return "cancelled";
  }
  return "unknown";
}
 
struct ProgressStep {
  std::string id;                                 
  ProgressStatus status = ProgressStatus::kIdle;  
  nlohmann::json value;                           
  std::optional<std::string> error;               
};
void to_json(nlohmann::json& j, const ProgressStep& step);
 
struct ProcedureSnapshot {
  ProcedureStatus status = ProcedureStatus::kIdle;  
 
  uint32_t runCount = 0;
 
  std::optional<int64_t> startedAt;   
  std::optional<int64_t> finishedAt;  
  std::vector<ProgressStep> steps;    
 
  std::optional<std::string> error;
};
void to_json(nlohmann::json& j, const ProcedureSnapshot& snapshot);
 
ProcedureSnapshot idleSnapshot(std::vector<ProgressStep> steps);
 
std::vector<ProgressStep> stepsFrom(std::initializer_list<std::string_view> ids);
 
enum class ParameterType : uint8_t {
  kInteger,      
  kBoolean,      
  kEnum,         
  kByteArray,    
  kString,       
  kStringArray,  
  kFile,         
};
 
constexpr std::string_view toString(ParameterType type) {
  switch (type) {
    case ParameterType::kInteger:
      return "integer";
    case ParameterType::kBoolean:
      return "boolean";
    case ParameterType::kEnum:
      return "enum";
    case ParameterType::kByteArray:
      return "byteArray";
    case ParameterType::kString:
      return "string";
    case ParameterType::kStringArray:
      return "stringArray";
    case ParameterType::kFile:
      return "file";
  }
  return "unknown";
}
 
struct ParameterOption {
  nlohmann::json value;  
  std::string title;     
};
void to_json(nlohmann::json& j, const ParameterOption& option);
 
struct ProcedureParameter {
  std::string name;         
  std::string title;        
  std::string description;  
  ParameterType type = ParameterType::kInteger;
 
  nlohmann::json defaultValue;
 
  std::optional<int64_t> minValue;       
  std::optional<int64_t> maxValue;       
  std::optional<size_t> length;          
  std::vector<ParameterOption> options;  
 
  bool required() const { return defaultValue.is_null(); }
};
void to_json(nlohmann::json& j, const ProcedureParameter& parameter);
 
ProcedureParameter integerParameter(std::string name, std::string title, std::string description,
                                    nlohmann::json defaultValue, int64_t minValue,
                                    int64_t maxValue);
 
ProcedureParameter booleanParameter(std::string name, std::string title, std::string description,
                                    nlohmann::json defaultValue);
 
ProcedureParameter enumParameter(std::string name, std::string title, std::string description,
                                 nlohmann::json defaultValue, std::vector<ParameterOption> options);
 
ProcedureParameter byteArrayParameter(std::string name, std::string title, std::string description,
                                      size_t length);
 
ProcedureParameter stringParameter(std::string name, std::string title, std::string description,
                                   nlohmann::json defaultValue);
 
ProcedureParameter stringArrayParameter(std::string name, std::string title,
                                        std::string description, nlohmann::json defaultValue);
 
ProcedureParameter fileParameter(std::string name, std::string title, std::string description,
                                 nlohmann::json defaultValue);
 
struct ProcedureDescriptor {
  std::string name;   
  std::string title;  
  std::string description;           
  std::vector<std::string> caveats;  
  bool movesMotor = false;           
  bool requiresEnabled = false;      
 
  std::vector<ProcedureParameter> parameters;
 
  std::vector<ProgressStep> steps;
};
void to_json(nlohmann::json& j, const ProcedureDescriptor& descriptor);
 
class ProgressReporter {
 public:
  explicit ProgressReporter(std::vector<ProgressStep> steps) : steps_(std::move(steps)) {}
 
  void start(std::string_view id);
 
  void succeed(std::string_view id);
 
  template <typename T>
  void succeed(std::string_view id, const T& value) {
    succeed(id, nlohmann::json(value));
  }
 
  void succeed(std::string_view id, nlohmann::json value);
 
  void fail(std::string_view id, std::string error);
 
  std::vector<ProgressStep> steps() const;
 
 private:
  mutable std::mutex mutex_;
  std::vector<ProgressStep> steps_;
};
 
}  // namespace mm::node