Skip to content

Your first RPC: ask another module

Documented releasev0.2.0/Stable main branch

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.

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:

Terminal window
cmake --build build/debug
.\build\debug\Vinc.exe

If 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:

rpcSubscriber

Wait for ready receiver and Started receiver, then start the sender:

rpcPublisher

Wait 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.

sender count

Wait for the sender to print:

RPC received=0

The 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.

sender send

First wait for the receiver to print:

received sequence=1 publisher=sender

Then query the count:

sender count

This time, you will see:

RPC received=1

Enter sender send again. Wait for received sequence=2 publisher=sender, then enter sender count to get:

RPC received=2

Wait for the receive output before each RPC query to confirm the message has been counted.

RPC uses two message types. The caller and receiver must use matching definitions.

GetCountRequest.msg asks for the count and needs no data fields:

messages/GetCountRequest.msg
# Asking for the current count needs no data fields.

messages/GetCountRequest.msg · e165aed

GetCountResponse.msg carries the received count in the reply:

messages/GetCountResponse.msg
uint64_t received;

messages/GetCountResponse.msg · e165aed

The build generates vinc::GetCountRequest and vinc::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():

rpc/subscriber.cpp
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());
}

rpc/subscriber.cpp · e165aed

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.

When a request arrives, get_count() writes the current received count into the response:

rpc/subscriber.cpp
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();
}

rpc/subscriber.cpp · e165aed

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:

rpc/publisher.cpp
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;
}

rpc/publisher.cpp · e165aed

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.

The reply handler checks for errors before printing the received count:

rpc/publisher.cpp
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;
}

rpc/publisher.cpp · e165aed

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.

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.

exit

Wait 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.