Skip to content

Your first cross-process message

Documented releasev0.2.0/Stable main branch

Continue from Your first running module by exchanging a message between two modules: sender publishes a counter and receiver prints what it receives.

Use the open-vinc-examples checkout from the previous lesson. You do not need to download it again. Run all commands below from the repository root, where you can see framework/, modules/ and messages/.

For Python, complete Prepare the Python examples first. For C++ tools, see the build guide.

Use the repository root’s CMakeLists.txt this time to build the two counter modules:

Terminal window
cmake -S . -B build/debug -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build/debug

Once the build finishes, the next step runs build/debug/Vinc.exe.

Open the central application’s Vinc Shell from PowerShell:

Terminal window
.\build\debug\Vinc.exe

The central application has started its built-in Web UI and Recorder. The sender and receiver used in this lesson have not been created yet.

Enter the following in Vinc Shell, not PowerShell. Start the Subscriber first:

counterSubscriber

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

counterPublisher

Wait for ready sender and Started sender. Enter a ModuleType to create an instance, then use the instance name for subsequent operations:

Role ModuleType Instance name
Receive messages counterSubscriber receiver
Send messages counterPublisher sender

Enter in Vinc Shell:

sender send

Wait for the receiver to print this line. Actual output also includes a source prefix:

received sequence=1 publisher=sender

This means receiver received sequence 1, published by sender.

Then query the received count:

receiver status

The output includes:

received=1

Wait for the receive output before querying. To send another message, enter sender send again and wait for the receiver to print the next sequence before querying.

Now read the code to see how the message gets from sender to receiver.

messages/CounterSample.msg defines the data to send:

messages/CounterSample.msg
uint64_t sequence;

messages/CounterSample.msg · e165aed

sequence is the counter value. Both languages use the same definition:

The build generates vinc::CounterSample and <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") {
// Set the instance name used by Shell commands.
}
vinc::Result<void> on_start(const std::vector<std::string>&) override {
// Startup hook: the framework calls this after the instance name is approved.
// Set up this module here; returning {} means initialization succeeded.
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 {
// Command hook: called when Shell addresses this instance.
// Return 0 for success or 1 to report a command error.
// Native Shell includes the target. Direct Manager callers may omit it.
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 {
// Shutdown hook: called during normal shutdown to clean up this module.
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;
};
// Register the type name Shell uses to create this module.
REGISTER_MODULE(CounterPublisher, "counterPublisher")

modules/publisher.cpp · e165aed

Follow these steps:

  1. on_start() creates a Publisher with context.advertise() and stores it in member publisher_, keeping it alive while the module runs.
  2. sender send enters module_interface(), which creates a message with make_message() and sets sequence.
  3. publisher_->push(*message) sends the message. The next sequence increases only after success.
  4. on_stop() releases the Publisher.

The code checks each Result so registration and send failures can be reported.

Both versions use the framework’s default capacity for now; a slow reader can still miss data.

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") {
// Set the instance name used by Shell commands.
}
vinc::Result<void> on_start(const std::vector<std::string>&) override {
// Startup hook: the framework calls this after the instance name is approved.
// Set up this module here; returning {} means initialization succeeded.
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 {
// Command hook: called when Shell addresses this instance.
// Return 0 for success or 1 to report a command error.
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 {
// Shutdown hook: called during normal shutdown to clean up this module.
subscriber_.reset();
std::cout << "stopped receiver" << std::endl;
return {};
}
private:
void on_message(std::unique_ptr<vinc::CounterSample> message) {
// Subscription callback: called when a counter message is delivered.
++received_;
// Flush this small interactive example so captured output is visible promptly.
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;
};
// Register the type name Shell uses to create this module.
REGISTER_MODULE(CounterSubscriber, "counterSubscriber")

modules/subscriber.cpp · e165aed

The receiver has two parts:

  • on_start() subscribes to "tutorial/counter" with context.subscribe() and stores the subscription in member subscriber_.
  • When a message arrives, the lambda only calls on_message(). That named function contains the counting and output logic.

Capturing [this] lets the lambda call a member function on this object. std::move(message) transfers ownership of the message to on_message(). Inside that function, publisher_name() reads the publisher’s name.

Storing the subscription as a member keeps it receiving after on_start() returns. on_stop() releases it.

The sender and receiver must use the same topic name, "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)
# Keep the tutorial's executable path stable. Tcl deployment follows this target.
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

This lesson adds a message definition and a second module to the previous lesson’s structure. Focus on these four commands:

  • add_subdirectory(): add the framework.
  • add_message_dir(): add the message definitions in messages/.
  • add_module(): build the Publisher and Subscriber.
  • vinc_add_app(): compose this App using vinc.conf.

set_target_properties() places the executable in build/debug/. You can skip the final test include() for now.

When you have finished reading, enter in Vinc Shell:

exit

Look for stopped sender and stopped receiver; they may appear in either order. The central application waits for both processes to exit, then returns to PowerShell.

You have now started two modules, exchanged a message and shut down cleanly. Continue with Define your own message to define your own numeric and string fields.