Wildcard Subscription
Subscribe to events using wildcard channel patterns
Overview
A wildcard subscription lets one subscriber match a whole family of channels with a single call, instead of wiring up a separate SubscribeToEvents for every sub-channel and touching code each time a new one appears. It's the natural fit for monitoring, logging, or fan-in aggregation across a channel hierarchy — for example, watching every regional order channel from one place.
KubeMQ matches wildcard tokens against the channel hierarchy server-side at delivery time. * matches exactly one dot-separated segment, and > matches one or more trailing segments, so client->SubscribeToEvents("cpp-events.wildcard.*", ...) catches any single-segment suffix. Every delivered EventReceive still carries its exact channel, so the callback can tell which concrete sub-channel it came from even though the subscription itself only named a pattern.
Gotchas: * matches exactly one segment — it won't reach two levels deep, so orders.* misses orders.us.east; use > for that. Wildcards are only valid on Events subscriptions, not on SendEvent/publishes or on events-store, queues, or commands/queries. And an overly broad pattern like > at the root will quietly pull in every channel under that prefix, including ones you didn't intend to monitor.
Prerequisites
- KubeMQ server running on
localhost:50000 - C++ SDK installed (vcpkg or CMake FetchContent)
- C++17 compiler (GCC 9+, Clang 9+, MSVC 2019+)
Code
// Example: events/wildcard_subscription
//
// Demonstrates subscribing to events using a wildcard pattern.
// Wildcard "cpp-events.wildcard.*" matches channels like
// "cpp-events.wildcard.a" and "cpp-events.wildcard.b".
//
// Channel: cpp-events.wildcard-subscription
// Client ID: cpp-events-wildcard-subscription-client
//
// Run with a KubeMQ server on localhost:50000
// (see https://docs.kubemq.io/deploy).
#include <kubemq/kubemq.h>
#include <chrono>
#include <iostream>
#include <thread>
int main() {
std::cout << "[1] Connecting to localhost:50000" << std::endl;
kubemq::ClientOptions options;
options.set_address("localhost", 50000);
options.set_client_id("cpp-events-wildcard-subscription-client");
auto client_result = kubemq::Client::Create(options);
if (!client_result.ok()) {
std::cerr << "[ERROR] Failed to create client: " << client_result.status().message()
<< std::endl;
return 1;
}
auto& client = *client_result;
// Subscribe with a wildcard pattern to match multiple channels.
std::cout << "[2] Subscribing to cpp-events.wildcard.*" << std::endl;
auto sub_result = client->SubscribeToEvents(
"cpp-events.wildcard.*", "",
[](const kubemq::EventReceive& event) {
std::cout << "[4] Wildcard received: channel=" << event.channel
<< " body=" << event.body << std::endl;
},
[](const kubemq::Status& err) {
std::cerr << "[ERROR] Subscription error: " << err.message() << std::endl;
});
if (!sub_result.ok()) {
std::cerr << "[ERROR] SubscribeToEvents: " << sub_result.status().message() << std::endl;
return 1;
}
auto& sub = *sub_result;
std::this_thread::sleep_for(std::chrono::seconds(1));
// Publish to two channels that match the wildcard pattern.
for (const auto& ch : {"cpp-events.wildcard.a", "cpp-events.wildcard.b"}) {
auto ev_result = kubemq::Event::Builder()
.SetChannel(ch)
.SetBody("wildcard-msg")
.SetMetadata("wildcard-demo")
.Build();
if (!ev_result.ok()) {
std::cerr << "[ERROR] Build event: " << ev_result.status().message() << std::endl;
return 1;
}
auto send_status = client->SendEvent(*ev_result);
if (!send_status.ok()) {
std::cerr << "[ERROR] SendEvent to " << ch << ": " << send_status.message()
<< std::endl;
return 1;
}
std::cout << "[3] Published to " << ch << std::endl;
}
// Wait for at least one event.
std::this_thread::sleep_for(std::chrono::seconds(2));
std::cout << "[5] Wildcard subscription demo complete" << std::endl;
// Cancel the subscription explicitly.
// Note: Subscription destructor would also handle cleanup (RAII)
sub->Cancel();
auto close_status = client->Close();
if (!close_status.ok()) {
std::cerr << "[ERROR] Close failed: " << close_status.message() << std::endl;
return 1;
}
std::cout << "[6] Client closed" << std::endl;
return 0;
}How It Works
- Subscribes using a wildcard pattern
cpp-events.wildcard.*to match multiple channels. - Publishes events to
cpp-events.wildcard.aandcpp-events.wildcard.b-- both match the pattern. - Wildcard subscriptions simplify consuming events from related channels.
- The
*wildcard matches any single segment in the channel name.
Related
Was this page helpful?