UiApp.hpp

Go to the documentation of this file.

#pragma once
 
#include <atomic>
#include <config_store.hpp>
#include <functional>
#include <memory>
#include <string>
#include <thread>
#include <utility>
 
#include "AppContext.h"
#include "bus/UiBusClient.hpp"
 
namespace lacte::ui {
 
// Базовый класс UI, который работает в собственном потоке внутри процесса
// приложения. Строит и владеет СОБСТВЕННЫМ клиентом (см. UiBusClient.hpp) на
// ОДНОЙ общей шине, которую строит LacteApp (см. AppContext::bus) —
// LacteApp всегда передаёт этому классу только AppContext&, но никогда уже
// готовый клиент. Start() запускает его (порождает поток, который
// присоединяется к шине и выполняет UI), а Stop() останавливает — либо
// можно просто дать ему разрушиться (RAII: деструктор сам останавливает
// поток и дожидается его завершения). Конкретный UI (консольный,
// framebuffer) реализует только Exec(): подключается к бэкенду через
// ConnectBus(), а затем вызывает методы напрямую на Hub()/Runtime()
// (UiBusClient.hpp) — отдельного фасада клиента нет, поскольку собственные
// методы UiBusClient уже говорят всё, что могло бы туда добавиться.
// Приложение (LacteApp) владеет одним экземпляром на каждый режим --ui; UI
// общается с бэкендом только через шину, поэтому остаётся самодостаточной,
// переносимой единицей.
class UiApp {
 public:
  // Хуки на стороне отрисовки, которыми управляет бэкенд, проталкивая
  // команды: UI сам определяет, что означают "enable/disable" и "изменение
  // aeration" для его виджетов. Любой из них может быть пустым (например,
  // для UI, который только опрашивает состояние).
  struct Callbacks {
    std::function<void(bool enabled)> on_enabled;
    std::function<void(int aeration)> on_aeration;
  };
 
  // `ctx` объединяет ОДНУ общую шину, которую строит LacteApp (см.
  // LacteApp::RunImpl()), и собственный живой ConfigStore LacteApp (см.
  // AppContext.h) — этот UI строит и владеет СОБСТВЕННЫМ клиентом на
  // `ctx.bus` (см. UiBusClient::create()), а не получает уже готовый; сам
  // `ctx` должен жить дольше этого UI. `address`/`name` — это
  // адрес/интроспекционное имя собственного клиента этого UI (см.
  // AppConfig::K_UI_BUS_ADDRESS/kUiBusNodeName). Конкретный UI читает из
  // `ctx.config` любые нужные ему пути к устройствам/настройки (см.
  // FramebufferUi::Exec()); UI, которому нечего оттуда читать, как
  // ConsoleUi, просто никогда не вызывает Config().
  explicit UiApp(const AppContext& ctx, const uint32_t address,
                 const std::string& name)
      : m_bus_(bus::UiBusClient::create(ctx.bus, address, name, ctx.app_name)),
        m_config_(ctx.config),
        m_shared_bus_(ctx.bus) {}
  virtual ~UiApp() { stop(); }
 
  UiApp(const UiApp&) = delete;
  auto operator=(const UiApp&) -> UiApp& = delete;
 
  // Порождает поток UI и немедленно возвращает управление.
  void start();
 
  // Сигнализирует UI остановиться и дожидается завершения его потока.
  // Идемпотентен; деструктор тоже его вызывает.
  void stop();
 
  // Вызывается (из собственного потока UI, сразу после возврата из Exec())
  // всякий раз, когда UI прекращает работу ПО СОБСТВЕННОЙ ИНИЦИАТИВЕ —
  // пользователь нажал Quit/'q', либо — в те времена, когда консольный
  // режим ConsoleUi был основан на FTXUI, а не на сегодняшнем простом ANSI
  // (см. файловый doc-комментарий ConsoleUi.cpp) — СОБСТВЕННАЯ обработка
  // SIGINT в FTXUI молча завершала цикл экрана раньше, чем реальный
  // обработчик сигналов этого приложения вообще успевал сработать.
  // Позволяет владеющему приложению (LacteApp) трактовать "UI завершился"
  // как "пожалуйста, останови всё приложение целиком" — раньше завершение
  // потока UI было полностью невидимо для остальной части приложения;
  // воспроизведено вживую (на том старом консольном UI на базе FTXUI):
  // нажатие 'q' (или ровно одно нажатие Ctrl+C, пока работал цикл FTXUI)
  // закрывало UI на экране, но оставляло процесс бэкенда бесконечно
  // работать в фоне без интерфейса — второй Ctrl+C требовался только
  // потому, что временная подмена обработчика сигналов в FTXUI к тому
  // моменту уже автоматически восстановила настоящий обработчик
  // приложения. По-прежнему нужен в общем виде и сегодня (любой UI —
  // собственная 'q' простого ANSI-консольного UI, framebuffer-UI — всё
  // ещё может завершиться по своей инициативе), хотя конкретное
  // взаимодействие FTXUI/SIGINT, которое это мотивировало, к ConsoleUi
  // больше не относится. Должен быть установлен ДО Start(), а не после —
  // иначе поток UI в принципе может оказаться уже за пределами Exec() к
  // тому моменту, когда вызывающий код доберётся до установки этого
  // колбэка.
  void set_on_exit(std::function<void()> on_exit) {
    m_on_exit_ = std::move(on_exit);
  }
 
 protected:
  virtual auto exec()
      -> int = 0;  // собственный цикл UI; выполняется в потоке UI  //
 
  // Строит runtime этого UI и подписывает его на собственный клиент (см.
  // UiBusClient::subscribe_runtime()) — с этого момента Runtime() валиден.
  // subscribe_runtime() захватывает только weak_ptr на runtime, поэтому
  // этот UI (и его runtime) можно уничтожить в любом порядке относительно
  // клиента, на который он подписан, без риска висячего колбэка.
  void connect_bus(Callbacks callbacks);
 
  [[nodiscard]] auto hub() const -> bus::UiBusClient& { return *m_bus_; }
  [[nodiscard]] auto runtime() const -> bus::UiRuntime& { return *m_runtime_; }
 
  [[nodiscard]] auto config() const -> insitech::config::ConfigStore<>& {
    return m_config_;
  }
 
  // Сама ОДНА общая шина (а не собственный клиент этого UI на ней) —
  // позволяет конкретному UI по запросу вывести отчёт интроспекции шины
  // (см. `IHub::print_table_report()`), не имея собственного
  // `AppContext&` (этот UI его никогда не хранит — почему сохраняются
  // только `m_bus_`/`m_config_`, см. doc-комментарий этого конструктора).
  [[nodiscard]] auto shared_bus() const -> insitech::bus::IHub& {
    return m_shared_bus_;
  }
 
  // Флаг работы, который должен опрашивать цикл UI и который переключает
  // Stop(). Передаётся циклам, чтобы UI мог и сам себя остановить
  // (например, по клавише выхода), сбросив его.
  auto run_flag() -> std::atomic_bool& { return m_run_flag_; }
 
 private:
  std::shared_ptr<bus::UiBusClient> m_bus_;
  insitech::config::ConfigStore<>& m_config_;
  insitech::bus::IHub& m_shared_bus_;
  std::atomic_bool m_run_flag_{false};
  std::shared_ptr<bus::UiRuntime> m_runtime_;
  std::thread m_thread_;
  std::function<void()> m_on_exit_;
};
 
}  // namespace lacte::ui