# Runtime Interface


## 相关链接

代码文件：
- {{ '[aimrt_core.h]({}/src/runtime/core/aimrt_core.h)'.format(code_site_root_path_url) }}

参考示例：
- {{ '[helloworld]({}/src/examples/cpp/helloworld)'.format(code_site_root_path_url) }}
  - {{ '[helloworld_app_registration_mode]({}/src/examples/cpp/helloworld/app/helloworld_app_registration_mode)'.format(code_site_root_path_url) }}
  - {{ '[helloworld_app]({}/src/examples/cpp/helloworld/app/helloworld_app)'.format(code_site_root_path_url) }}
  - {{ '[normal_publisher_app]({}/src/examples/cpp/pb_chn/app/normal_publisher_app)'.format(code_site_root_path_url) }}
  - {{ '[normal_subscriber_app]({}/src/examples/cpp/pb_chn/app/normal_subscriber_app)'.format(code_site_root_path_url) }}


## 简介

如果说逻辑开发阶段的 C++ 接口主要是让用户开发具体的业务逻辑，那么本文档所介绍的**运行时接口**则是让用户决定如何部署、集成、运行这些业务逻辑。

AimRT 提供了两种部署集成方式：
- **App 模式**：开发者在自己的 Main 函数中注册/创建各个模块，编译时直接将业务逻辑编译进主程序；
- **Pkg 模式**：使用 AimRT 提供的**aimrt_main**可执行程序，在运行时根据配置文件加载动态库形式的`Pkg`，导入其中的`Module`；


两者的优劣势和适用场景请参考[AimRT 中的基本概念](../concepts/concepts.md)文档里的说明。


无论采用哪种方式都不影响业务逻辑，且两种方式可以共存，也可以比较简单的进行切换，实际采用哪种方式需要根据具体场景进行判断。


关于`aimrt::CoreRef`句柄的相关信息，请参考[CoreRef](./core_ref.md)文档。

## App 模式

开发者直接引用 CMake Target：**aimrt::runtime::core**，然后即可使用{{ '[core/aimrt_core.h]({}/src/runtime/core/aimrt_core.h)'.format(code_site_root_path_url) }}文件中的`aimrt::runtime::core::AimRTCore`类，在 App 模式下需要使用的核心接口如下：

```cpp
namespace aimrt::runtime::core {

class AimRTCore {
 public:
  struct Options {
    std::string cfg_file_path;
  };

 public:
  void Initialize(const Options& options);

  void Start();
  std::future<void> AsyncStart();

  void Shutdown();

  // ...

  module::ModuleManager& GetModuleManager();

  // ...
};

}  // namespace aimrt::runtime::core
```

接口使用说明如下：
- `void Initialize(const Options& options)`：用于初始化框架。
  - 接收一个`AimRTCore::Options`作为初始化参数。其中最重要的项是`cfg_file_path`，用于设置配置文件路径。
  - 如果初始化失败，会抛出一个异常。
- `void Start()`：启动框架。
  - 如果启动失败，会抛出一个异常。
  - 必须在 Initialize 方法之后调用，否则行为未定义。
  - 如果启动成功，会阻塞当前线程，并将当前线程作为本`AimRTCore`实例的主线程。
- `std::future<void> AsyncStart()`：异步启动框架。
  - 如果启动失败，会抛出一个异常。
  - 必须在 Initialize 方法之后调用，否则行为未定义。
  - 如果启动成功，会返回一个`std::future<void>`句柄，在外部可以调用该句柄的`wait`方法阻塞等待结束。
  - 该方法会在内部新启动一个线程作为本`AimRTCore`实例的主线程。
- `void Shutdown()`：停止框架。
  - 可以在任意线程、任意阶段调用此方法，也可以调用任意次数。
  - 调用此方法后，`Start`方法将在执行完主线程中的所有任务后，退出阻塞。
  - 需要注意，有时候业务会阻塞住主线程中的任务，导致`Start`方法无法退出阻塞、优雅结束整个框架，此时需要在外部强制 kill。


开发者可以在自己的 Main 函数中创建一个`AimRTCore`实例，依次调用其`Initialize`、`Start`/`AsyncStart`方法，并可以自己捕获`Ctrl-C`信号来调用`Shutdown`方法，以实现`AimRTCore`实例的优雅退出。

`AimRTCore`类型的`GetModuleManager`方法可以返回一个`ModuleManager`句柄，可以用来注册或创建模块，App 模式下需要使用其提供的`RegisterModule`接口或`CreateModule`接口：
```cpp
namespace aimrt::runtime::core::module {

class ModuleManager {
 public:
  void RegisterModule(const aimrt_module_base_t* module);

  const aimrt_core_base_t* CreateModule(std::string_view module_name);
};

}  // namespace aimrt::runtime::core::module
```

`RegisterModule`和`CreateModule`代表了 App 模式下编写逻辑的两种方式：**注册模块**方式与**创建模块**方式，前者仍然需要编写一个继承于`ModuleBase`类的业务模块类，后者则更加自由。

### 注册模块

通过`RegisterModule`可以直接注册一个标准模块。开发者需要先实现一个继承于`ModuleBase`基类的`Module`，然后在`AimRTCore`实例调用`Initialize`方法之前注册该`Module`实例，在此方式下仍然有一个比较清晰的`Module`边界。


关于`ModuleBase`基类的相关信息，请参考[ModuleBase](./module_base.md)文档。


以下是一个简单的例子，开发者需要编写的`main.cc`文件如下：
```cpp
#include <csignal>

#include "core/aimrt_core.h"
#include "aimrt_module_cpp_interface/module_base.h"

AimRTCore* global_core_ptr_ = nullptr;

void SignalHandler(int sig) {
  if (global_core_ptr_ && (sig == SIGINT || sig == SIGTERM)) {
    global_core_ptr_->Shutdown();
    return;
  }
  raise(sig);
};

class HelloWorldModule : public aimrt::ModuleBase {
 public:
  HelloWorldModule() = default;
  ~HelloWorldModule() override = default;

  ModuleInfo Info() const override {
    return ModuleInfo{.name = "HelloWorldModule"};
  }

  bool Initialize(aimrt::CoreRef core) override { return true; }
  bool Start() override { return true; }
  void Shutdown() override {}
};

int32_t main(int32_t argc, char** argv) {
  signal(SIGINT, SignalHandler);
  signal(SIGTERM, SignalHandler);

  // Create AimRTCore ins
  AimRTCore core;
  global_core_ptr_ = &core;

  // Register module
  HelloWorldModule helloworld_module;
  core.GetModuleManager().RegisterModule(helloworld_module.NativeHandle());

  // Initialize AimRTCore ins
  AimRTCore::Options options;
  options.cfg_file_path = "path/to/cfg/xxx_cfg.yaml";
  core.Initialize(options);

  // Start AimRTCore ins, will block here
  core.Start();

  // Shutdown AimRTCore ins
  core.Shutdown();

  return 0;
}
```

编译上面示例的`main.cc`，直接启动编译后的可执行文件即可运行进程，按下`ctrl-c`后即可停止进程。


详细示例代码请参考：
- {{ '[helloworld_app_registration_mode]({}/src/examples/cpp/helloworld/app/helloworld_app_registration_mode)'.format(code_site_root_path_url) }}


### 创建模块

在`AimRTCore`实例调用`Initialize`方法之后，通过`CreateModule`可以创建一个模块，并返回一个`aimrt::CoreRef`句柄，开发者可以直接基于此句柄调用一些框架的方法，比如 RPC 或者 Log 等。在此方式下没有一个比较清晰的`Module`边界，不利于大型项目的组织，一般仅用于快速做一些小工具。



以下是一个简单的例子，实现了一个发布 channel 消息的功能，开发者需要编写的`main.cc`文件如下：
```cpp
#include "core/aimrt_core.h"

#include "aimrt_module_cpp_interface/core.h"
#include "aimrt_module_protobuf_interface/channel/protobuf_channel.h"

#include "event.pb.h"

int32_t main(int32_t argc, char** argv) {
  // Create AimRTCore ins
  AimRTCore core;

  // Initialize AimRTCore ins
  AimRTCore::Options options;
  options.cfg_file_path = "path/to/cfg/xxx_cfg.yaml";
  core.Initialize(options);

  // Create module
  aimrt::CoreRef core_handle(core.GetModuleManager().CreateModule("HelloWorldModule"));

  // Register a msg type for publish
  auto publisher = core_handle.GetChannelHandle().GetPublisher("test_topic");
  aimrt::channel::RegisterPublishType<ExampleEventMsg>(publisher);

  // Start AimRTCore ins
  auto fu = core.AsyncStart();

  // Publish a message
  ExampleEventMsg msg;
  msg.set_msg("example msg");
  aimrt::channel::Publish(publisher, msg);

  // Wait for seconds
  std::this_thread::sleep_for(std::chrono::seconds(5));

  // Shutdown AimRTCore ins
  core.Shutdown();

  // Wait for complete shutdown
  fu.wait();

  return 0;
}
```

编译上面示例的`main.cc`，直接启动编译后的可执行文件即可运行进程，该进程将在发布一个消息后，等待一段时间并退出。

更多示例请参考：
- {{ '[helloworld_app]({}/src/examples/cpp/helloworld/app/helloworld_app)'.format(code_site_root_path_url) }}
- {{ '[normal_publisher_app]({}/src/examples/cpp/pb_chn/app/normal_publisher_app)'.format(code_site_root_path_url) }}
- {{ '[normal_subscriber_app]({}/src/examples/cpp/pb_chn/app/normal_subscriber_app)'.format(code_site_root_path_url) }}


## Pkg 模式

### 创建 Pkg

开发者可以引用 CMake Target：**aimrt::interface::aimrt_pkg_c_interface**，在其中的头文件{{ '[aimrt_pkg_c_interface/pkg_main.h]({}/src/interface/aimrt_pkg_c_interface/pkg_main.h)'.format(code_site_root_path_url) }}中，定义了几个要实现的接口：

```cpp
#ifdef __cplusplus
extern "C" {
#endif

// Get the num of modules in the pkg
size_t AimRTDynlibGetModuleNum();

// Get the list of module names in the pkg
const aimrt_string_view_t* AimRTDynlibGetModuleNameList();

// Create a module with the name
const aimrt_module_base_t* AimRTDynlibCreateModule(aimrt_string_view_t module_name);

// Destroy module
void AimRTDynlibDestroyModule(const aimrt_module_base_t* module_ptr);

#ifdef __cplusplus
}
#endif
```

其中，`aimrt_module_base_t`可以由继承了`ModuleBase`基类的派生类获得。关于`ModuleBase`基类的相关信息，请参考[ModuleBase](./module_base.md)文档。


通过这些接口，AimRT 框架运行时可以从 Pkg 动态库中获取想要的模块。开发者需要在一个`C/CPP`文件中实现这些接口来创建一个 Pkg。


这些接口是纯 C 形式的，所以理论上只要开发者将 Pkg 的符号都隐藏起来，不同 Pkg 之间可以做到较好的兼容性。如果开发者使用 C++，也可以使用{{ '[aimrt_pkg_c_interface/pkg_macro.h]({}/src/interface/aimrt_pkg_c_interface/pkg_macro.h)'.format(code_site_root_path_url) }}文件中的一个简单的宏来封装这些细节，用户只需要实现一个包含所有模块构造方法的静态数组即可。


以下是一个简单的示例，开发者需要编写如下的`pkg_main.cc`文件：

```cpp
#include "aimrt_pkg_c_interface/pkg_macro.h"
#include "bar_module.h"
#include "foo_module.h"

static std::tuple<std::string_view, std::function<aimrt::ModuleBase*()>> aimrt_module_register_array[]{
    {"FooModule", []() -> aimrt::ModuleBase* { return new FooModule(); }},
    {"BarModule", []() -> aimrt::ModuleBase* { return new BarModule(); }}};

AIMRT_PKG_MAIN(aimrt_module_register_array)
```

### 启动 Pkg

将上面的示例`pkg_main.cc`编译为动态库后，即可使用 AimRT 提供的**aimrt_main**可执行程序启动进程，通过配置中指定的路径来加载 Pkg 动态库。示例配置如下：
```yaml
aimrt:
  module:
    pkgs:
      - path: /path/to/your/pkg/libxxx_pkg.so
```

有了配置文件之后，通过以下示例命令启动 AimRT 进程，按下`ctrl-c`后即可停止进程：
```shell
./aimrt_main --cfg_file_path=/path/to/your/cfg/xxx_cfg.yaml
```


AimRT官方提供**aimrt_main**可执行程序接收一些参数作为 AimRT 运行时的初始化参数，这些参数功能如下：

|  参数项               |  类型     | 默认值                |作用  | 示例 |
|  ----                 | ----      | ----                | ----  | ----  |
| cfg_file_path         | string    | ""                  | 配置文件路径。  |  --cfg_file_path=/path/to/your/xxx_cfg.yaml |
| dump_cfg_file         | bool      | false               | 是否 Dump 配置文件。 |  --dump_cfg_file=true |
| dump_cfg_file_path    | string    | "./dump_cfg.yaml"   | Dump 配置文件的路径。 |  --dump_cfg_file_path=/path/to/your/xxx_dump_cfg.yaml |
| dump_init_report      | bool      | false               | 是否 Dump 初始化报告。<br>请注意，仅当初始化成功后才有初始化报告。 |  --dump_init_report=true |
| dump_init_report_path | string    | "./init_report.txt" | Dump 初始化报告的路径。 |  --dump_init_report_path=/path/to/your/xxx_init_report.txt |
| register_signal       | bool      | true                | 是否注册 sigint 和 sigterm 信号，用于触发 Shutdown。 |  --register_signal=true |
| running_duration      | int32     | 0                   | 本次运行时间，单位：s。如果为 0 则表示一直运行。 |  --running_duration=10 |


开发者也可以使用`./aimrt_main --help`命令查看这些参数功能。