 |
VLink 2.0.0
A high-performance communication middleware
|
|
VLink 2.0.0
A high-performance communication middleware
|
本章提供所有官方示例的总览、分类结构说明和运行方法，帮助开发者快速上手 VLink 的各种使用场景。
**相关文档**：三种通信模型详解参见 03-event-model.md、04-method-model.md、05-field-model.md；序列化类型参见 06-serialization.md；传输后端参见 07-transport.md；C API 详解参见 18-c-api.md；插件系统参见 19-extensions.md。
VLink 示例目录已重新组织为 **14 个分类**，覆盖从基础库到高级功能的所有使用场景。
| 分类 | 目录 | 示例数量 | 说明 |
|---|---|---|---|
| quickstart | examples/quickstart/ | 3 | 最小化入门示例（PubSub、RPC、Field） |
| base | examples/base/ | 19 | 基础库（Logger、Timer、Bytes、线程池等） |
| communication | examples/communication/ | 7 | 三种通信模型的基础和进阶用法 |
| serialization | examples/serialization/ | 7 | 各序列化类型的独立演示 |
| url_guide | examples/url_guide/ | 9 | URL 格式与各传输后端配置指南 |
| qos | examples/qos/ | 3 | QoS 策略配置和预置 Profile |
| security | examples/security/ | 3 | AES 加密、自定义加密、SSL/TLS |
| zerocopy | examples/zerocopy/ | 4 | 零拷贝传输（SHM loan） |
| recording | examples/recording/ | 5 | Bag 录制、回放、压缩、MCAP 格式 |
| plugin | examples/plugin/ | 4 | 动态插件加载、runnable 插件（API 名为 RunablePluginInterface）、Proto 插件 |
| proxy | examples/proxy/ | 3 | 代理层 API 和服务器基础用法 |
| c_api | examples/c_api/ | 3 | 纯 C 语言绑定（PubSub、RPC、Field） |
| node_features | examples/node_features/ | 4 | 节点生命周期、MessageLoop 绑定、属性、状态 |
| samples | examples/samples/ | 8 | 默认构建的经典综合示例；dds_idl/ 当前未启用，images/ 为资源目录 |
顶层 ENABLE_EXAMPLES **默认关闭**（仅当 CMAKE_EXPORT_COMPILE_COMMANDS 或 CMAKE_CXX_CLANG_TIDY 开启时会自动置为 ON）。要构建示例，需要显式 -DENABLE_EXAMPLES=ON。在此基础上，examples/CMakeLists.txt 再通过 ENABLE_WHOLE_EXAMPLES 控制是否编译全部分类：
| 传输后端 | 额外依赖 | 运行前置条件 |
|---|---|---|
| intra:// | 无 | 无 |
| dds:// | FastDDS | 无守护进程需求 |
| ddsc:// | CycloneDDS | 无守护进程需求 |
| shm:// | Iceoryx | 先起 SHM 守护进程（首选 vlink-proxy -c；备选 iox-roudi -c） |
| shm2:// | Iceoryx2 | 无需守护进程 |
| zenoh:// | Zenoh-C | 无需守护进程（peer 模式） |
| someip:// | vsomeip + FlatBuffers（Beta） | 需启动 vsomeip routing manager |
| fdbus:// | FDBus + Protobuf（Beta） | 需启动 FDBus name server |
| mqtt:// | Paho MQTT C（Beta） | 需 MQTT Broker 运行 |
| qnx:// | QNX SDP（仅 QNX 平台） | QNX 平台 |
最小化的入门示例，每个示例只演示一种通信模型的最基本用法。
| 项目 | 说明 |
|---|---|
| hello_pubsub | Publisher + Subscriber 基本发布/订阅 |
| hello_rpc | Server + Client 基本 RPC 调用 |
| hello_field | Setter + Getter 基本字段读写 |
演示 VLink 基础库（vlink/base/）中各组件的独立用法。
| 项目 | 说明 |
|---|---|
| logger_basic | 日志基本用法（级别、宏、格式化） |
| logger_advanced | 日志高级用法（Handler、文件、Backtrace） |
| timer_basic | 定时器基本用法（周期、一次性） |
| timer_advanced | 定时器高级用法（strict 模式、优先级） |
| bytes_basic | Bytes 基本操作（创建、拷贝、比较） |
| bytes_advanced | Bytes 高级操作（Base64、CRC、压缩） |
| bytes_zerocopy | Bytes 零拷贝（shallow_copy、loan） |
| elapsed_timer | 耗时计时器 |
| deadline_timer | 截止时间检测器 |
| message_loop_basic | 事件循环基本用法 |
| message_loop_advanced | 事件循环高级用法（优先级队列） |
| multi_loop | 多事件循环并发调度 |
| thread_pool | 线程池任务提交 |
| spin_lock | 自旋锁使用 |
| graph_task | DAG 任务图调度 |
| object_pool | 对象池 |
| process | 进程信息查询 |
| schedule | 调度器 |
| utils | 工具函数（路径、线程、信号等） |
三种通信模型（Event、Method、Field）的基础和进阶用法。
| 项目 | 说明 |
|---|---|
| event_basic | Publisher/Subscriber 基本 Pub-Sub |
| event_advanced | 多订阅者、连接检测、强制发布等 |
| field_basic | Setter/Getter 基本状态同步 |
| field_advanced | 推送模式、轮询模式、监听回调 |
| method_sync | Server/Client 同步 RPC 调用（invoke 带返回值） |
| method_async | Server/Client 异步 RPC 调用（async_invoke + future） |
| method_fire_forget | Server/Client 单向请求（send，无返回值） |
每种 VLink 支持的序列化类型的独立演示。
| 项目 | 序列化类型 | 说明 |
|---|---|---|
| bytes_type | Bytes | 原始字节传输，无序列化开销 |
| string_type | std::string | UTF-8 字符串传输 |
| pod_type | 标准布局 POD 结构体 | 直接内存拷贝（kStandardType） |
| stream_type | 流式类型 | 通过 operator<</operator>> 的 stringstream |
| custom_type | 自定义类型 | 用户实现 operator>>/operator<< (Bytes) |
| dynamic_data | DynamicData | 运行时类型擦除容器 |
| intra_data | IntraData | 进程内零拷贝数据类型 |
URL 格式说明和各传输后端的配置指南。
| 项目 | 说明 |
|---|---|
| url_basics | URL 基本格式和组件解析 |
| url_environment | 通过环境变量动态配置 URL |
| url_remap | JSON URL 重映射（UrlRemap） |
| url_intra | intra:// 进程内传输 |
| url_shm | shm:// Iceoryx 共享内存传输 |
| url_dds | dds:// FastDDS 传输 |
| url_zenoh | zenoh:// Zenoh 传输 |
| url_someip | someip:// SOME/IP 车载以太网传输 |
| url_mqtt | mqtt:// MQTT 传输 |
| 项目 | 说明 |
|---|---|
| qos_basics | QoS 基本概念和参数设置 |
| qos_profiles | 预置 QoS Profile 的使用 |
| qos_history_depth | History Depth 对消息缓存的影响 |
详细的安全加密文档参见 09-security.md；SSL/TLS 相关环境变量参见 21-environment-vars.md。
| 项目 | 说明 |
|---|---|
| security_basic | 内置 AES-128-CBC 加密（set_security_key） |
| security_custom | 自定义加密回调（set_security_callbacks） |
| security_ssl | 传输层 SSL/TLS 加密（set_ssl_options） |
| 项目 | 说明 |
|---|---|
| zerocopy_loan | loan() / return_loan() 基本 API |
| zerocopy_raw_data | 零拷贝原始数据传输 |
| zerocopy_camera_frame | 零拷贝相机帧传输场景 |
| zerocopy_point_cloud | 零拷贝点云数据传输场景 |
详细的录制/回放 API 文档参见 12-bag-recording.md。
| 项目 | 说明 |
|---|---|
| record_basic | 基本 Bag 录制功能 |
| record_bag_writer | BagWriter API 详细用法 |
| record_bag_reader | BagReader API 详细用法 |
| record_compression | 压缩录制（zstd / lzav） |
| record_mcap | MCAP 格式录制 |
详细的插件系统文档参见 19-extensions.md。
| 项目 | 说明 |
|---|---|
| plugin_basic | Plugin::load<T>() 基本加载流程 |
| plugin_create | 自定义插件的创建和导出 |
| plugin_runnable | RunablePluginInterface（runnable 插件接口） |
| plugin_schema | SchemaPluginInterface 统一 schema 反射插件 |
详细的代理层文档参见 16-proxy.md。
| 项目 | 说明 |
|---|---|
| proxy_api_basic | 代理层 API 基本用法 |
| proxy_server_basic | 代理服务器基本配置和启动 |
| proxy_runnable_plugin | 代理层作为可运行插件部署 |
纯 C 语言绑定示例，覆盖三种通信模型。详细的 C API 文档及 Python/Go/Rust 绑定示例参见 18-c-api.md。
| 项目 | 说明 |
|---|---|
| c_pubsub | C API Publisher/Subscriber（Event 模型） |
| c_rpc | C API Server/Client（Method 模型） |
| c_field | C API Setter/Getter（Field 模型） |
节点生命周期详见 02-node-lifecycle.md；状态事件详见 17-discovery.md。
| 项目 | 说明 |
|---|---|
| lifecycle | 节点生命周期管理（init/deinit/interrupt） |
| message_loop_binding | 将节点绑定到 MessageLoop 进行回调调度 |
| properties | 节点属性（set_property/get_property） |
| status_monitoring | 节点状态监控（register_status_handler） |
samples/ 目录保留了项目早期的综合示例，每个示例演示完整的端到端场景。这些示例在默认配置下即被编译（不需要 ENABLE_WHOLE_EXAMPLES）。
| 示例名 | 目录 | 涉及传输 | 序列化 | 通信模型 | 说明 |
|---|---|---|---|---|---|
| helloworld | examples/samples/helloworld/ | 多后端（可切换） | Protobuf | Method + Event | 最全面的入门示例，推荐首先阅读 |
| ping_pong | examples/samples/ping_pong/ | 多后端（可切换） | Bytes（POD） | Event（双向） | 端到端延迟测量 |
| shm_raw | examples/samples/shm_raw/ | shm:// | Bytes（原始） | Method + Event + Field | 零拷贝 + 安全加密全模型演示 |
| dds_idl | examples/samples/dds_idl/ | dds:// | FastDDS IDL | Method + Event | FastDDS 原生 IDL 类型（CDR 序列化） |
| ddsc_proto | examples/samples/ddsc_proto/ | ddsc:// | Protobuf | Method + Event + Field | CycloneDDS + Protobuf 全模型演示 |
| dds_dynamic | examples/samples/dds_dynamic/ | dds:// | DynamicData | Method + Event | 运行时类型擦除，一个 URL 传多类型 |
| pub_sub_fbs | examples/samples/pub_sub_fbs/ | ddsc:// | FlatBuffers（Pub 用 UserT，Sub 用 User*） | Event（Pub + Sub） | pub 用 MessageLoop + Timer 每 500ms 连续发布；sub 用 FlatBuffers 指针类型零拷贝读取 |
| someip_flat | examples/samples/someip_flat/ | someip:// | FlatBuffers | Method + Event + Field | SOME/IP 车载以太网场景（Beta） |
| fdbus_proto | examples/samples/fdbus_proto/ | fdbus:// | Protobuf | Method + Event + Field | FDBus IPC（Android/Linux）（Beta） |
pub_sub_fbs 当前的运行方式是：
1.16.1