第一個 RPC:讓模組互相詢問
這篇接續設定與儲存模組參數,讓 sender 詢問 receiver:「目前收到幾筆訊息?」再取得回覆。這就是一次 RPC(遠端程序呼叫)。
Message Bus 負責發布訊息給訂閱者,RPC 則向指定模組的服務提出請求並取得結果。兩者可以一起使用:本篇用 Bus 傳送計數訊息,用 RPC 查詢接收數量。
1. 建置並啟動 RPC 範例
Section titled “1. 建置並啟動 RPC 範例”若前一次的 Vinc Shell 還開著,先輸入 exit。在 open-vinc-examples 根目錄重新建置,再從 PowerShell 開啟 Shell:
cmake --build build/debug.\build\debug\Vinc.execmake --build build/python.\build\python\Vinc.exe --python .\.venv\Scripts\python.exe若還沒有建置目錄,先完成跨程序訊息或 Python 環境準備。這次增加了訊息定義,Python 也需要重新建置 SDK。
看到 VINC ready 後,在 Vinc Shell 先啟動接收端:
rpcSubscriber等到 ready receiver 和 Started receiver,再啟動發送端:
rpcPublisher等到 ready sender 和 Started sender 再繼續。這次使用 RPC 版的兩個 Module,實例名稱仍為 sender 和 receiver,每次發送的序號增加 1。
2. 先詢問目前的接收數量
Section titled “2. 先詢問目前的接收數量”sender count等待發送端印出:
RPC received=0這個指令交給 sender 處理,由它呼叫 receiver 的 get_count 服務。接收端還沒收到計數訊息,所以回覆 0。
RPC 是非同步的。Shell 指令返回後,結果可能稍後才出現;請等到 RPC received=... 再繼續。
3. 發送訊息,再用 RPC 查詢
Section titled “3. 發送訊息,再用 RPC 查詢”sender send先等接收端印出:
received sequence=1 publisher=sender再詢問數量:
sender count這次會看到:
RPC received=1再送一筆 sender send,等到 received sequence=2 publisher=sender,再輸入 sender count,就會得到:
RPC received=2每次都先等到接收輸出,再用 RPC 查詢,才能確認那筆訊息已經被計入。
4. 定義請求與回覆
Section titled “4. 定義請求與回覆”RPC 使用兩個訊息型別,發送端與接收端必須使用相同的定義。
GetCountRequest.msg 只表示「查詢數量」,不需要額外資料欄位:
# 查詢目前的接收數量,不需要任何資料欄位。messages/GetCountRequest.msg · e165aed · 中文註解
GetCountResponse.msg 放回覆的接收數量:
uint64_t received;messages/GetCountResponse.msg · e165aed
建置後產生 vinc::GetCountRequest 和 vinc::GetCountResponse。
建置後透過 vinc.messages.GetCountRequest 和 vinc.messages.GetCountResponse 使用。
5. 接收端:提供 get_count 服務
Section titled “5. 接收端:提供 get_count 服務”在接收端的 on_start() 加入服務登記:
auto registered = context.register_rpc<vinc::GetCountRequest, vinc::GetCountResponse>( "get_count", {}, [this](const vinc::GetCountRequest& request, vinc::GetCountResponse& response) { return get_count(request, response); }); if (!registered) { return std::unexpected(registered.error()); }register_rpc<Request, Response>() 指定請求與回覆型別。服務名稱是 get_count,{} 使用預設選項;lambda 只轉交給具名的 get_count()。登記失敗時回報啟動失敗。
self.context.register_rpc( vinc.messages.GetCountRequest, vinc.messages.GetCountResponse, "get_count", self.get_count )python/modules/rpcSubscriber/rpcSubscriber.py · e165aed
register_rpc() 指定請求型別、回覆型別、服務名稱與處理函式。這裡直接傳入具名的 self.get_count。
收到請求後,get_count() 把目前的接收數量寫進回覆:
vinc::rpc::RpcStatus get_count(const vinc::GetCountRequest&, vinc::GetCountResponse& response) { // RPC 處理函式:其他模組請求此接收端的計數時呼叫。 // 填入 response 並回傳成功,再由框架送出回覆。 response.data().received = received_; return vinc::rpc::RpcStatus::success();}rpc/subscriber.cpp · e165aed · 中文註解
def get_count(self, request, response): # RPC 處理函式:其他模組請求此接收端的計數時呼叫。 # 填入 response 並回傳成功,再由框架送出回覆。 response.data().received = self.received return vinc.rpc.RpcStatus.success()python/modules/rpcSubscriber/rpcSubscriber.py · e165aed · 中文註解
RpcStatus.success() 表示服務成功完成這次請求。數量來自接收端原本的計數成員,查詢不會清除它。
6. 發送端:提出請求並處理回覆
Section titled “6. 發送端:提出請求並處理回覆”發送端的 module_interface() 收到 count 時,呼叫具名函式 request_count():
std::int32_t request_count() { // 送出非同步 RPC 請求,稍後由 on_count_reply 處理結果。 auto request = vinc::make_message<vinc::GetCountRequest>(); auto submitted = context.call_rpc<vinc::GetCountRequest, vinc::GetCountResponse>( "receiver", "get_count", *request, {}, [this](vinc::Result<vinc::rpc::RpcReply<vinc::GetCountResponse>> reply) { on_count_reply(std::move(reply)); }); if (!submitted) { std::cerr << "RPC failed: " << vinc::error_to_string(submitted.error()) << std::endl; return 1; }
return 0;}rpc/publisher.cpp · e165aed · 中文註解
call_rpc() 的目標是實例名稱 receiver,服務名稱是 get_count。lambda 只把結果轉交給 on_count_reply()。
這裡回傳 0 表示請求已被本地接受排送;是否取得回覆,要看後續 callback。
def request_count(self): # 送出非同步 RPC 請求,稍後由 on_count_reply 處理結果。 request = vinc.make_message(vinc.messages.GetCountRequest) try: self.context.call_rpc( vinc.messages.GetCountRequest, vinc.messages.GetCountResponse, "receiver", "get_count", request, self.on_count_reply ) except vinc.VincError as error: print(f"RPC failed: {error}") return 1
return 0python/modules/rpcPublisher/rpcPublisher.py · e165aed · 中文註解
call_rpc() 的目標是實例名稱 receiver,服務名稱是 get_count,完成時呼叫 self.on_count_reply。
呼叫當下的失敗以 VincError 回報;請求成功被本地接受後,結果會由 callback 交付。
處理回覆的函式先檢查錯誤,再印出接收數量:
void on_count_reply(vinc::Result<vinc::rpc::RpcReply<vinc::GetCountResponse>> reply) { // RPC 完成 callback:稍後在請求結束時呼叫。 // 使用 response 前,先檢查框架錯誤與服務回傳狀態。 if (!reply) { std::cerr << "RPC failed: " << vinc::error_to_string(reply.error()) << std::endl; return; }
if (reply->status.code != 0) { std::cerr << "RPC rejected: " << reply->status.reason << std::endl; return; }
std::cout << "RPC received=" << reply->response->data().received.get() << std::endl;}rpc/publisher.cpp · e165aed · 中文註解
reply 失敗表示 RPC 的框架錯誤;status.code 非 0 表示服務回報應用錯誤。成功時從 response 讀取 received。
def on_count_reply(self, reply, error): # RPC 完成 callback:稍後在請求結束時呼叫。 # 使用 response 前,先檢查框架錯誤與服務回傳狀態。 if error is not None: print(f"RPC failed: {error}") return
status, response = reply if status.code != 0: print(f"RPC rejected: {status.reason}") return
print(f"RPC received={response.data().received}")python/modules/rpcPublisher/rpcPublisher.py · e165aed · 中文註解
框架錯誤放在 error。成功取得回覆時,reply 是 (status, response);先檢查服務狀態,再讀取 response.data().received。
兩個 Module 都使用 FrameworkLoop,框架會派送服務請求和完成 callback。不要在 module_interface() 裡用迴圈卡住、等待回覆。
7. 正常關閉
Section titled “7. 正常關閉”exit等到 stopped sender、stopped receiver 並回到 PowerShell。你已經完成從 Shell 發起動作、由 Module 發送 RPC、再處理回覆的流程。
接著閱讀使用啟動腳本,把這兩個 Module 的啟動指令寫進同一份 Tcl 腳本。