component_api.h

Go to the documentation of this file.

// === component_api.h =================================================================================================
//                                               Sen Infrastructure
//                   Released under the Apache License v2.0 (SPDX-License-Identifier Apache-2.0).
//                                    See the LICENSE.txt file for more information.
//                   © Airbus SAS, Airbus Helicopters, and Airbus Defence and Space SAU/GmbH/SAS.
// =====================================================================================================================
 
#ifndef SEN_KERNEL_COMPONENT_API_H
#define SEN_KERNEL_COMPONENT_API_H
 
// sen
#include "sen/core/base/compiler_macros.h"
#include "sen/core/base/duration.h"
#include "sen/core/base/move_only_function.h"
#include "sen/core/base/mutex_utils.h"
#include "sen/core/base/result.h"
#include "sen/core/base/span.h"
#include "sen/core/base/timestamp.h"
#include "sen/core/meta/type_registry.h"
#include "sen/core/meta/var.h"
#include "sen/core/obj/detail/work_queue.h"
#include "sen/core/obj/interest.h"
#include "sen/core/obj/object.h"
#include "sen/core/obj/object_list.h"
#include "sen/core/obj/object_source.h"
#include "sen/core/obj/subscription.h"
 
// kernel
#include "sen/kernel/kernel.h"
#include "sen/kernel/source_info.h"
#include "sen/kernel/tracer.h"
#include "sen/kernel/transport.h"
 
// generated code
#include "stl/sen/kernel/basic_types.stl.h"
#include "stl/sen/kernel/network_footprint.stl.h"
 
// spdlog
#include <spdlog/logger.h>
#include <spdlog/sinks/sink.h>
 
// std
#include <atomic>
#include <cstddef>
#include <cstdint>
#include <cstring>
#include <filesystem>
#include <functional>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <type_traits>
#include <utility>
#include <vector>
 
namespace sen::kernel
{

using FuncResult = Result<void, ExecError>;

using PassResult = Result<OpState, ExecError>;

using NetworkFootprintReporter = NetworkFootprint(Span<const BusAddress>) const;
 
class SessionsDiscoverer;
class RunApi;
class KernelApi;

enum class TerminalOwnership
{
  shared,
  owned
};

struct LoggerSinkRegistration
{
  bool added = false;                   
  bool ownsTerminal = false;            
  bool terminalOwnedElsewhere = false;  
  std::size_t registeredSinks = 0;      
};
 
namespace impl
{
 
class Runner;
class KernelImpl;
 
[[nodiscard]] FuncResult execLoop(Runner* runner,
                                  Duration cycleTime,
                                  std::function<void()>&& workFunction,
                                  bool logOverruns);
 
void installTransportFactory(KernelImpl* kernel, TransportFactory&& factory, uint32_t transportVersion);
 
void remoteProcessDetected(RunApi& api, const ProcessInfo& processInfo);
 
void remoteProcessLost(RunApi& api, const ProcessInfo& processInfo);
 
[[nodiscard]] std::shared_ptr<ObjectSource> getSource(Runner* runner, const BusAddress& address);
 
[[nodiscard]] SessionsDiscoverer& getSessionsDiscoverer(Runner* runner);
 
[[nodiscard]] const ProcessInfo* fetchOwnerInfo(const Object* object);
 
[[nodiscard]] ::sen::impl::WorkQueue* getWorkQueue(Runner* runner);
 
[[nodiscard]] std::shared_ptr<spdlog::logger> getOrCreateLogger(const std::string& loggerName);
 
void applyToAllLoggers(std::function<void(std::shared_ptr<spdlog::logger>)>&& func);
 
[[nodiscard]] Result<LoggerSinkRegistration, ExecError> addLoggerSink(std::shared_ptr<spdlog::sinks::sink> sink,
                                                                      TerminalOwnership terminal);
 
[[nodiscard]] FuncResult removeLoggerSink(const std::shared_ptr<spdlog::sinks::sink>& sink);
 
[[nodiscard]] FuncResult setAllLoggersLevel(spdlog::level::level_enum level);
 
[[nodiscard]] spdlog::level::level_enum getAllLoggersLevel();
 
void setCrashBannerDescriptor(int descriptor) noexcept;
 
void prepareCurrentThreadForCrashReports() noexcept;
 
}  // namespace impl

struct ComponentMonitoringInfo
{
  std::string name;
  uint32_t group = 0;
  bool requiresRealTime = false;
  std::optional<Duration> cycleTime;
  std::size_t objectCount = 0;
  std::optional<Duration> lastCycleExecutionCpuTime;

  std::optional<Duration> lastCycleComponentCpuTime;

  std::optional<Duration> lastCycleQueuedWorkCpuTime;

  std::optional<Duration> worstCycleExecutionCpuTime;

  std::optional<Duration> worstCycleComponentCpuTime;

  std::optional<Duration> lastCycleStartDelay;

  std::optional<Duration> worstStartDelay;

  std::optional<uint64_t> overrunCount;

  std::optional<uint64_t> missedFrameCount;

  std::optional<uint64_t> oversleptCount;
};

struct KernelMonitoringInfo
{
  RunMode runMode = RunMode::realTime;
  TransportStats transportStats {};
  std::vector<ComponentMonitoringInfo> components;
};

class KernelApi
{
public:
  KernelApi(Kernel& kernel, impl::Runner* runner) noexcept;
 
public:
  [[nodiscard]] CustomTypeRegistry& getTypes() noexcept;

  void requestKernelStop(int exitCode = 0);

  [[nodiscard]] std::shared_ptr<ObjectSource> getSource(const BusAddress& address);

  [[nodiscard]] std::shared_ptr<ObjectSource> getSource(const std::string& address);

  [[nodiscard]] SessionsDiscoverer& getSessionsDiscoverer() noexcept;

  [[nodiscard]] const ProcessInfo* fetchOwnerInfo(const Object* object) const noexcept;

  [[nodiscard]] const std::string& getAppName() const noexcept;

  [[nodiscard]] std::vector<BusAddress> getConfiguredBusAddresses() const;

  [[nodiscard]] ::sen::impl::WorkQueue* getWorkQueue() const noexcept;

  template <typename T, typename Bus>
  [[nodiscard]] std::shared_ptr<Subscription<T>> selectAllFrom(const Bus& bus);

  template <typename T, typename Bus>
  [[nodiscard]] std::shared_ptr<Subscription<T>> selectAllFrom(
    const Bus& bus,
    typename sen::ObjectList<T>::Callback onAdded,
    typename sen::ObjectList<T>::Callback onRemoved = nullptr);

  template <typename T, typename Bus>
  [[nodiscard]] std::shared_ptr<Subscription<T>> selectFrom(const Bus& bus,
                                                            const std::string& query,
                                                            typename sen::ObjectList<T>::Callback onAdded = nullptr,
                                                            typename sen::ObjectList<T>::Callback onRemoved = nullptr);

  [[nodiscard]] std::filesystem::path getConfigFilePath() const noexcept { return kernel_.getConfigPath(); }

  [[nodiscard]] static std::shared_ptr<spdlog::logger> getOrCreateLogger(const std::string& loggerName);

  static void applyToAllLoggers(std::function<void(std::shared_ptr<spdlog::logger>)>&& func);

  using TerminalOwnership = ::sen::kernel::TerminalOwnership;

  [[nodiscard]] static Result<LoggerSinkRegistration, ExecError> addLoggerSink(
    std::shared_ptr<spdlog::sinks::sink> sink,
    TerminalOwnership terminal = TerminalOwnership::shared);

  [[nodiscard]] static FuncResult removeLoggerSink(const std::shared_ptr<spdlog::sinks::sink>& sink);

  [[nodiscard]] static FuncResult setAllLoggersLevel(spdlog::level::level_enum level);

  static void setCrashBannerDescriptor(int descriptor) noexcept;

  static void prepareCurrentThreadForCrashReports() noexcept;

  [[nodiscard]] static spdlog::level::level_enum getAllLoggersLevel();
 
private:
  template <typename T>
  [[nodiscard]] std::string buildQuery(const BusAddress& address) const;
 
  template <typename T>
  [[nodiscard]] std::string buildQuery(std::string_view bus) const;
 
private:
  Kernel& kernel_;
  impl::Runner* runner_;
};

class ConfigGetter
{
public:
  explicit ConfigGetter(const VarMap& config) noexcept;
 
public:
  [[nodiscard]] const VarMap& getConfig() const noexcept;
 
private:
  const VarMap& config_;
};

class RegistrationApi: public ConfigGetter, public KernelApi
{
public:
  SEN_NOCOPY_NOMOVE(RegistrationApi)
 
public:
  RegistrationApi(Kernel& kernel, impl::Runner* runner, const VarMap& config) noexcept;
  ~RegistrationApi() noexcept = default;
};

class PreloadApi: public ConfigGetter, public KernelApi
{
  SEN_NOCOPY_NOMOVE(PreloadApi)
 
public:
  PreloadApi(Kernel& kernel, impl::Runner* runner, const VarMap& config) noexcept;
 
  ~PreloadApi() noexcept = default;
 
public:
  void installTransportFactory(TransportFactory&& factory, uint32_t transportVersion) const;

  void installTracerFactory(TracerFactory&& factory) const;

  void installFootprintReporter(sen::std_util::move_only_function<NetworkFootprintReporter>&& reporter);

  void installFootprintReporter(sen::std_util::move_only_function<NetworkFootprintReporter>&& offlineReporter,
                                sen::std_util::move_only_function<NetworkFootprint() const>&& runtimeReporter);
 
private:
  Kernel& kernel_;
};

class LoadApi: public ConfigGetter, public KernelApi
{
  SEN_NOCOPY_NOMOVE(LoadApi)
 
public:
  LoadApi(Kernel& kernel, impl::Runner* runner, const VarMap& config) noexcept;
 
  ~LoadApi() noexcept = default;
};

class InitApi: public ConfigGetter, public KernelApi
{
  SEN_NOCOPY_NOMOVE(InitApi)
 
public:
  InitApi(Kernel& kernel, impl::Runner* runner, const VarMap& config) noexcept;
 
  ~InitApi() noexcept = default;
};

class RunApi: public ConfigGetter, public KernelApi
{
public:
  SEN_NOCOPY_NOMOVE(RunApi)
 
public:
  RunApi(Kernel& kernel,
         impl::KernelImpl& kernelImpl,
         impl::Runner* runner,
         std::atomic_bool& stopRequested,
         const VarMap& config,
         Guarded<TimeStamp>& timePoint) noexcept;
 
  ~RunApi() noexcept = default;
 
public:
  [[nodiscard]] const std::atomic_bool& stopRequested() const noexcept;

  void drainInputs();

  void update();

  void commit();

  [[nodiscard]] FuncResult execLoop(Duration cycleTime,
                                    std::function<void()>&& func = nullptr,
                                    bool logOverruns = true);

  [[nodiscard]] TimeStamp getStartTime() const noexcept;

  [[nodiscard]] TimeStamp getTime() const noexcept;

  [[nodiscard]] std::optional<Duration> getTargetCycleTime() const noexcept;

  [[nodiscard]] ComponentMonitoringInfo fetchComponentMonitoringInfo() const;

  [[nodiscard]] KernelMonitoringInfo fetchMonitoringInfo() const;

  [[nodiscard]] Span<const ComponentInfo> getImportedPackages() const noexcept;

  [[nodiscard]] Span<const ComponentInfo> getLoadedComponents() const noexcept;

  [[nodiscard]] std::optional<uint32_t> getTransportProtocolVersion() const noexcept;

  [[nodiscard]] Tracer& getTracer() const noexcept;
 
private:
  friend void impl::remoteProcessDetected(RunApi& api, const ProcessInfo& processInfo);
 
  friend void impl::remoteProcessLost(RunApi& api, const ProcessInfo& processInfo);
 
private:
  impl::KernelImpl& kernelImpl_;
  impl::Runner* runner_;
  std::atomic_bool& stopRequested_;
  Guarded<TimeStamp>& timePoint_;
};

class UnloadApi: public ConfigGetter, public KernelApi
{
  SEN_NOCOPY_NOMOVE(UnloadApi)
 
public:
  UnloadApi(Kernel& kernel, const VarMap& config, impl::Runner* runner) noexcept;
  ~UnloadApi() noexcept = default;
};
 
//----------------------------------------------------------------------------------------------------------------------
// Inline implementation
//----------------------------------------------------------------------------------------------------------------------
 
template <typename T, typename Bus>
inline std::shared_ptr<Subscription<T>> KernelApi::selectAllFrom(const Bus& bus)
{
  auto sub = std::make_shared<Subscription<T>>();
  sub->attachTo(getSource(bus), Interest::make(buildQuery<T>(bus), getTypes()), true);
  return sub;
}
 
template <typename T, typename Bus>
inline std::shared_ptr<Subscription<T>> KernelApi::selectAllFrom(const Bus& bus,
                                                                 typename ObjectList<T>::Callback onAdded,
                                                                 typename ObjectList<T>::Callback onRemoved)
{
  auto sub = std::make_shared<Subscription<T>>();
  // Install callbacks before subscribing so they fire for objects already present.
  if (onAdded)
  {
    std::ignore = sub->list.onAdded(std::move(onAdded));
  }
  if (onRemoved)
  {
    std::ignore = sub->list.onRemoved(std::move(onRemoved));
  }
  sub->attachTo(getSource(bus), Interest::make(buildQuery<T>(bus), getTypes()), true);
  return sub;
}
 
template <typename T, typename Bus>
inline std::shared_ptr<Subscription<T>> KernelApi::selectFrom(const Bus& bus,
                                                              const std::string& query,
                                                              typename sen::ObjectList<T>::Callback onAdded,
                                                              typename sen::ObjectList<T>::Callback onRemoved)
{
  auto sub = std::make_shared<Subscription<T>>();
 
  // Install callbacks before subscribing so they fire for objects already present.
  if (onAdded)
  {
    std::ignore = sub->list.onAdded(std::move(onAdded));
  }
  if (onRemoved)
  {
    std::ignore = sub->list.onRemoved(std::move(onRemoved));
  }
  sub->attachTo(getSource(bus), Interest::make(query, getTypes()), true);
  return sub;
}
 
namespace impl
{

template <typename T>
[[nodiscard]] inline std::string_view queryTypeName()
{
  if constexpr (std::is_same_v<T, Object>)
  {
    return "*";
  }
  else
  {
    static_assert(std::is_same_v<decltype(T::meta()), ::sen::ConstTypeHandle<::sen::ClassType>>,
                  "a subscription type must be a Sen object class");
    return T::meta()->getQualifiedName();
  }
}
 
}  // namespace impl
 
template <typename T>
inline std::string KernelApi::buildQuery(const BusAddress& address) const
{
  std::string query = "SELECT ";
  query.append(impl::queryTypeName<T>());
  query.append(" FROM ");
  query.append(address.sessionName);
  query.append(".");
  query.append(address.busName);
 
  return query;
}
 
template <typename T>
inline std::string KernelApi::buildQuery(std::string_view bus) const
{
  std::string query = "SELECT ";
  query.append(impl::queryTypeName<T>());
  query.append(" FROM ");
  query.append(bus);
 
  return query;
}
 
}  // namespace sen::kernel
 
#endif  // SEN_KERNEL_COMPONENT_API_H