跳到內容

第一個跨程序訊息

文件對應版本v0.2.0/main 穩定版

這篇接續第一個運行模組,讓兩個 Module 交換訊息:sender 負責發送計數,receiver 收到後印出內容。

使用上一篇的 open-vinc-examples,不需要重新下載。以下命令都從專案根目錄執行,也就是看得到 framework/、modules/ 與 messages/ 的位置。

選擇 Python 時,請先完成準備 Python 範例。C++ 工具準備見建置指南。

這次使用專案根目錄的 CMakeLists.txt,建置兩個計數 Module:

終端機視窗
cmake -S . -B build/debug -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build/debug

建置完成後,下一步會執行 build/debug/Vinc.exe。

在 PowerShell 開啟中央的 Vinc Shell:

終端機視窗
.\build\debug\Vinc.exe

中央已啟動內建 Web UI 與 Recorder;這篇要操作的 sender、receiver 還沒建立。

接下來的命令輸入在 Vinc Shell,不是 PowerShell。先啟動 Subscriber:

counterSubscriber

等待看見 ready receiver 與 Started receiver,再啟動 Publisher:

counterPublisher

等待看見 ready sender 與 Started sender。啟動時輸入 ModuleType,之後操作使用實例名稱:

用途 ModuleType 實例名稱
接收訊息 counterSubscriber receiver
發送訊息 counterPublisher sender

在 Vinc Shell 輸入:

sender send

等待接收端印出這行內容;實際輸出還會包含來源前綴:

received sequence=1 publisher=sender

這表示 receiver 收到序號為 1 的訊息,發布者是 sender。

接著查詢接收數量:

receiver status

輸出會包含:

received=1

請等到接收輸出出現後再查詢。若要再送一筆,重複輸入 sender send,等待接收端印出下一個序號後再查詢。

接下來閱讀程式,看看這筆訊息如何從 sender 到達 receiver。

messages/CounterSample.msg 定義要傳送的資料:

messages/CounterSample.msg
uint64_t sequence;

messages/CounterSample.msg · e165aed

sequence 是計數值。同一份定義可供兩種語言使用:

建置時產生 vinc::CounterSample 型別與 <vinc_messages/CounterSample.hpp>。

modules/publisher.cpp
#include <vinc/vinc.hpp>
#include <vinc_messages/CounterSample.hpp>
#include <cstdint>
#include <iostream>
#include <optional>
#include <string>
#include <utility>
#include <vector>
class CounterPublisher final
: public vinc::BaseModule<vinc::RunMode::FrameworkLoop> {
public:
CounterPublisher() : BaseModule("sender") {
// 設定 Shell 指令使用的實例名稱。
}
vinc::Result<void> on_start(const std::vector<std::string>&) override {
// 啟動 hook:實例名稱核准後,由框架呼叫。
// 在這裡初始化模組;回傳 {} 代表初始化成功。
auto publisher = context.advertise<vinc::CounterSample>(
"tutorial/counter");
if (!publisher) {
return std::unexpected(publisher.error());
}
publisher_.emplace(std::move(*publisher));
std::cout << "ready sender" << std::endl;
return {};
}
vinc::Result<std::int32_t> module_interface(std::vector<std::string> args) override {
// 指令 hook:Shell 將指令送到這個實例時,由框架呼叫。
// 回傳 0 表示成功,回傳 1 表示指令執行失敗。
// 原生 Shell 會附上目標名稱;直接透過 Manager 呼叫時可以省略。
if (!args.empty() && args.front() == get_module_name()) {
args.erase(args.begin());
}
if (args.size() != 1 || args.front() != "send") {
std::cout << "Usage: sender send" << std::endl;
return 1;
}
auto message = vinc::make_message<vinc::CounterSample>();
message->data().sequence = next_sequence_;
auto published = publisher_->push(*message);
if (!published) {
std::cerr << vinc::error_to_string(published.error()) << std::endl;
return 1;
}
++next_sequence_;
return 0;
}
vinc::Result<void> on_stop() override {
// 停止 hook:正常關閉時由框架呼叫,在這裡清理模組資源。
publisher_.reset();
std::cout << "stopped sender" << std::endl;
return {};
}
private:
std::optional<vinc::message_bus::Publisher<vinc::CounterSample>> publisher_;
std::uint64_t next_sequence_ = 1;
};
// 登記 Shell 用來建立此模組的種類名稱。
REGISTER_MODULE(CounterPublisher, "counterPublisher")

modules/publisher.cpp · e165aed · 中文註解

先看這幾個步驟:

  1. on_start() 用 context.advertise() 建立 Publisher,並存到成員 publisher_,讓它在 Module 運行期間持續存在。
  2. sender send 進入 module_interface(),用 make_message() 建立訊息,填入 sequence。
  3. publisher_->push(*message) 發送訊息,成功後才增加下一筆序號。
  4. on_stop() 釋放 Publisher。

程式保留每個 Result 的錯誤檢查,讓註冊或發送失敗時可以回報錯誤。

兩種版本都先使用框架預設容量;接收太慢仍可能漏資料。

modules/subscriber.cpp
#include <vinc/vinc.hpp>
#include <vinc_messages/CounterSample.hpp>
#include <cstdint>
#include <iostream>
#include <memory>
#include <optional>
#include <string>
#include <utility>
#include <vector>
class CounterSubscriber final
: public vinc::BaseModule<vinc::RunMode::FrameworkLoop> {
public:
CounterSubscriber() : BaseModule("receiver") {
// 設定 Shell 指令使用的實例名稱。
}
vinc::Result<void> on_start(const std::vector<std::string>&) override {
// 啟動 hook:實例名稱核准後,由框架呼叫。
// 在這裡初始化模組;回傳 {} 代表初始化成功。
auto subscriber = context.subscribe<vinc::CounterSample>(
"tutorial/counter",
[this](std::unique_ptr<vinc::CounterSample> message) {
on_message(std::move(message));
});
if (!subscriber) {
return std::unexpected(subscriber.error());
}
subscriber_.emplace(std::move(*subscriber));
std::cout << "ready receiver" << std::endl;
return {};
}
vinc::Result<std::int32_t> module_interface(std::vector<std::string> args) override {
// 指令 hook:Shell 將指令送到這個實例時,由框架呼叫。
// 回傳 0 表示成功,回傳 1 表示指令執行失敗。
if (!args.empty() && args.front() == get_module_name()) {
args.erase(args.begin());
}
if (args.empty()) {
args.push_back("status");
}
if (args.size() == 1 && args.front() == "status") {
std::cout << "received=" << received_ << std::endl;
return 0;
}
if (args.size() == 1 && args.front() == "reset") {
received_ = 0;
std::cout << "counter reset" << std::endl;
return 0;
}
std::cout << "Usage: receiver [status|reset]" << std::endl;
return 1;
}
vinc::Result<void> on_stop() override {
// 停止 hook:正常關閉時由框架呼叫,在這裡清理模組資源。
subscriber_.reset();
std::cout << "stopped receiver" << std::endl;
return {};
}
private:
void on_message(std::unique_ptr<vinc::CounterSample> message) {
// 訂閱 callback:計數訊息送達時,由框架呼叫。
++received_;
// 立即送出輸出緩衝區的內容,讓互動範例及時顯示接收結果。
std::cout
<< "received sequence=" << message->data().sequence.get()
<< " publisher=" << message->publisher_name()
<< std::endl;
}
std::optional<vinc::message_bus::Subscriber<vinc::CounterSample>> subscriber_;
std::uint64_t received_ = 0;
};
// 登記 Shell 用來建立此模組的種類名稱。
REGISTER_MODULE(CounterSubscriber, "counterSubscriber")

modules/subscriber.cpp · e165aed · 中文註解

接收端分成兩個部分:

  • on_start() 用 context.subscribe() 訂閱 "tutorial/counter",並把訂閱存到成員 subscriber_。
  • 收到訊息時,lambda 只負責呼叫 on_message();計數與輸出都寫在這個具名函式裡。

[this] 讓 lambda 可以呼叫目前物件的成員函式。std::move(message) 把這筆訊息的所有權交給 on_message()。函式內的 publisher_name() 可讀出發布者名稱。

訂閱要存成成員,才能在 on_start() 返回後繼續接收;on_stop() 再釋放它。

發送端與接收端必須使用相同的 topic 名稱 "tutorial/counter"。

CMakeLists.txt
cmake_minimum_required(VERSION 3.20)
project(open_vinc_counter_example LANGUAGES C CXX)
if(MSVC)
add_compile_options("$<$<COMPILE_LANGUAGE:CXX>:/utf-8>")
endif()
set(VINC_NAME "counter-example" CACHE STRING "Central instance identity")
set(VINC_BUILD_APPS OFF CACHE BOOL "Build the framework's demonstration app")
set(BUILD_TESTING OFF CACHE BOOL "Build the framework's internal tests")
add_subdirectory(framework/open-vinc/src open-vinc)
add_message_dir("${CMAKE_CURRENT_SOURCE_DIR}/messages")
add_module(counter_publisher
MODULE_TYPE_NAME counterPublisher
SOURCES modules/publisher.cpp
)
add_module(counter_subscriber
MODULE_TYPE_NAME counterSubscriber
SOURCES modules/subscriber.cpp
)
add_subdirectory(parameters)
add_subdirectory(rpc)
add_subdirectory(logging)
add_subdirectory(custom-message)
vinc_add_app(Vinc INSTANCE_NAME "${VINC_NAME}" VINC_BUILD_CONFIG vinc.conf)
# 固定教學使用的執行檔路徑,Tcl 也會部署到相同位置。
set_target_properties(Vinc PROPERTIES
RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}"
RUNTIME_OUTPUT_DIRECTORY_DEBUG "${CMAKE_BINARY_DIR}"
RUNTIME_OUTPUT_DIRECTORY_RELEASE "${CMAKE_BINARY_DIR}"
)
include(tests/CMakeLists.txt)

CMakeLists.txt · e165aed · 中文註解

本篇在上一篇的基礎上加入訊息定義與第二個 Module,先掌握這四個指令:

  • add_subdirectory():加入框架。
  • add_message_dir():加入 messages/ 的訊息定義。
  • add_module():分別建立 Publisher 與 Subscriber。
  • vinc_add_app():依 vinc.conf 組裝這個 App。

set_target_properties() 讓執行檔放在 build/debug/。最後的測試 include() 可以先略過。

閱讀完成後,在 Vinc Shell 輸入:

exit

你會看見 stopped sender、stopped receiver;兩者的輸出順序可能不同。中央等待兩個程序退出後,會返回 PowerShell。

你已經完成兩個 Module 的啟動、訊息收發與正常關閉。接下來閱讀自訂訊息,練習定義自己的數值與字串欄位。