Common Information

Cpp 接口概览

AimRT 中的 C/Cpp 接口包括两部分：

  1. 用于业务逻辑开发的接口，核心是aimrt::CoreRef句柄的使用；

  2. 用于部署运行的接口，又分为 App 模式和 Pkg 模式，核心是如何获取aimrt::CoreRef句柄并区分 AimRT 运行阶段；

Cpp 业务逻辑开发接口

AimRT 为业务逻辑开发提供了一套 CPP 接口库，CMake Target 名称：

  • aimrt::interface::aimrt_module_cpp_interface

在开发业务逻辑时只需要链接这个 CMake Target，可以与 AimRT 的实现细节相隔离。这是一个纯头文件库，只有两个依赖：

  • fmt：用于日志。如果编译器支持 C++20 的 format，可以关闭 CMake 选项AIMRT_USE_FMT_LIB，从而去掉这个依赖；

  • libunifex：用于将异步逻辑封装为协程；

该接口库核心是aimrt::CoreRef句柄，开发者可以通过此句柄来调用 AimRT 的各种能力，例如日志、RPC、Channel 等。关于aimrt::CoreRef句柄的相关信息，请参考CoreRef文档。

CPP 部署运行接口

AimRT 提供了两种部署集成方式：

  • App 模式：开发者在自己的 Main 函数中注册/创建各个模块，编译时直接将业务逻辑编译进主程序；

  • Pkg 模式：使用 AimRT 提供的aimrt_main可执行程序，在运行时根据配置文件加载动态库形式的Pkg，导入其中的Module；

两者的核心区别是如何获取aimrt::CoreRef句柄并区分 AimRT 运行阶段。两者的优劣势和适用场景请参考AimRT 中的基本概念文档里的说明。

关于这两种部署运行接口的详细信息，请参考Runtime Interface文档。

Cpp 接口中的引用类型

CPP 接口层中，大部分句柄都是一种引用类型，具有以下特点：

  • 类型命名一般以Ref结尾；

  • 这种引用类型一般需要一个 C 类型的指针来构造；

  • 这种引用类型一般比较轻量，拷贝传递不会有较大开销；

  • 这种引用类型一般都提供了一个operator bool()的重载来判断引用是否有效；

  • 调用这种引用类型中提供的接口时，如果引用为空，会抛出一个异常；

AimRT 生命周期以及接口调用时机

参考接口概述，AimRT 在运行时有三个主要的阶段：

  • Initialize 阶段

  • Start 阶段

  • Shutdown 阶段

一些接口只能在某些特定阶段里被调用。后续文档中，如果不对接口做特殊说明，则默认该接口在所有阶段都可以被调用。

大部分接口的实际表现需要根据部署运行配置而定

在逻辑实现阶段，开发者只需要知道此接口在抽象意义上代表什么功能即可，至于在实际运行时的表现，则要根据部署运行配置而定，在逻辑开发阶段也不应该关心太多。

例如，开发者可以使用log接口打印一行日志，但这个日志最终打印到文件里还是控制台上，则需要根据运行时配置而定，开发者在写业务逻辑时不需要关心。

Cpp 接口中的协程

AimRT 中为执行器、RPC 等功能提供了原生的异步回调形式的接口，同时也基于 C++20 协程和C++ executors 提案当前的一个实现库libunifex，为使用者提供了一套协程形式的接口。

关于协程接口的基本用法，将在执行器、RPC 等功能具体章节进行简单介绍。关于 C++20 协程以及 libunifex 库的进阶用法，请参考相关文档：

请注意，协程功能是一个 AimRT 框架中的一个可选项，如果使用者不想使用协程的方式，也仍然能够通过其他形式的接口使用 AimRT 框架的所有基础能力。

Cpp 接口中的协议

在 aimrt::interface::aimrt_module_cpp_interface 这个 CMake Target 中，是不包含任何特定的协议类型的。在 AimRT 中，通过aimrt_type_support_base_t类来定义一种数据类型，其中定义了一种数据类型应该实现的基本接口，包括名称、创建/销毁、序列化/反序列化等。开发者可以通过实现它们来自定义数据类型，也可以直接使用AimRT官方支持的两种数据类型：

  • Protobuf，需 CMake 引用 aimrt::interface::aimrt_module_protobuf_interface；

  • ROS2 Message，需 CMake 引用 aimrt::interface::aimrt_module_ros2_interface；

一般在 Channel 或 RPC 功能中需要使用到具体的协议类型，具体的使用方式（包括代码生成、接口使用等）请参考 Channel 或 RPC 功能的文档章节。