Your first RPC: ask another module
Continue from Configure and save module parameters by having sender ask receiver, “How many messages have you received?” and receive a reply. This is an RPC, or remote procedure call.
Message Bus publishes messages to subscribers. RPC sends a request to a service on a specific module and returns a result. This lesson uses both: Bus delivers counter messages, and RPC queries the received count.
1. Build and start the RPC example
Section titled “1. Build and start the RPC example”If the previous Vinc Shell is still open, enter exit first. Rebuild from the open-vinc-examples repository root, then open the Shell from PowerShell:
cmake --build build/debug.\build\debug\Vinc.execmake --build build/python.\build\python\Vinc.exe --python .\.venv\Scripts\python.exeIf you have not prepared a build directory, follow Your first cross-process message or Prepare the Python examples first. This lesson adds message definitions, so Python also needs the SDK rebuild.
Once you see VINC ready, start the receiver in Vinc Shell:
rpcSubscriberWait for ready receiver and Started receiver, then start the sender:
rpcPublisherWait for ready sender and Started sender before continuing. These are the RPC versions of the two modules. Their instance names remain sender and receiver, and each send increases the sequence by 1.
2. Ask for the current count
Section titled “2. Ask for the current count”sender countWait for the sender to print:
RPC received=0The Shell command goes to sender, which calls the get_count service on receiver. The receiver has not received any counter messages yet, so it replies with 0.
RPC is asynchronous. The result can arrive after the Shell command returns. Wait for RPC received=... before continuing.
3. Send a message, then query with RPC
Section titled “3. Send a message, then query with RPC”sender sendFirst wait for the receiver to print:
received sequence=1 publisher=senderThen query the count:
sender countThis time, you will see:
RPC received=1Enter sender send again. Wait for received sequence=2 publisher=sender, then enter sender count to get:
RPC received=2Wait for the receive output before each RPC query to confirm the message has been counted.
4. Define the request and response
Section titled “4. Define the request and response”RPC uses two message types. The caller and receiver must use matching definitions.
GetCountRequest.msg asks for the count and needs no data fields:
# Asking for the current count needs no data fields.messages/GetCountRequest.msg · e165aed
GetCountResponse.msg carries the received count in the reply:
uint64_t received;messages/GetCountResponse.msg · e165aed
The build generates vinc::GetCountRequest and vinc::GetCountResponse.
After the build, use vinc.messages.GetCountRequest and vinc.messages.GetCountResponse.
5. Receiver: provide the get_count service
Section titled “5. Receiver: provide the get_count service”Register the service in the receiver’s 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>() specifies the request and response types. The service name is get_count, and {} uses default options. The lambda only forwards to the named get_count() function. Registration failure is reported as a startup failure.
self.context.register_rpc( vinc.messages.GetCountRequest, vinc.messages.GetCountResponse, "get_count", self.get_count )python/modules/rpcSubscriber/rpcSubscriber.py · e165aed
register_rpc() specifies the request type, response type, service name, and handler. Pass the named self.get_count function directly.
When a request arrives, get_count() writes the current received count into the response:
vinc::rpc::RpcStatus get_count(const vinc::GetCountRequest&, vinc::GetCountResponse& response) { // RPC handler: called when another module requests this receiver's count. // Fill response and return success; the framework sends the reply. response.data().received = received_; return vinc::rpc::RpcStatus::success();}def get_count(self, request, response): # RPC handler: called when another module requests this receiver's count. # Fill response and return success; the framework sends the reply. response.data().received = self.received return vinc.rpc.RpcStatus.success()RpcStatus.success() reports that the service completed this request successfully. The count comes from the receiver’s existing counter; querying does not clear it.
6. Sender: make the request and handle the reply
Section titled “6. Sender: make the request and handle the reply”When the sender’s module_interface() receives count, it calls the named request_count() function:
std::int32_t request_count() { // Submit an asynchronous RPC; on_count_reply handles the result later. 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;}The target of call_rpc() is instance receiver, and the service is get_count. The lambda only forwards the result to on_count_reply().
Returning 0 here means the request was accepted locally for dispatch. The later callback reports the result.
def request_count(self): # Submit an asynchronous RPC; on_count_reply handles the result later. 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
The target of call_rpc() is instance receiver, the service is get_count, and completion calls self.on_count_reply.
An immediate call failure raises VincError. Once the request is accepted locally, the callback delivers its result.
The reply handler checks for errors before printing the received count:
void on_count_reply(vinc::Result<vinc::rpc::RpcReply<vinc::GetCountResponse>> reply) { // RPC completion callback: called later when the request finishes. // Check framework errors and the service status before using the 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;}A failed reply is a framework RPC error. A nonzero status.code is an application error reported by the service. On success, read received from response.
def on_count_reply(self, reply, error): # RPC completion callback: called later when the request finishes. # Check framework errors and the service status before using the 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
Framework errors arrive in error. When a reply arrives successfully, reply is (status, response). Check the service status, then read response.data().received.
Both modules use FrameworkLoop, so the framework dispatches service requests and completion callbacks. Do not block module_interface() in a loop waiting for the reply.
7. Shut down cleanly
Section titled “7. Shut down cleanly”exitWait for stopped sender, stopped receiver, and a return to PowerShell. You have now triggered an action from Shell, sent an RPC from a Module, and handled its reply.
Continue with Start modules with a script to put these two module startup commands in one Tcl file.