Delayed Messages
Send KubeMQ Queue messages with delayed delivery using the C++ SDK so consumers receive them after a set interval.
Overview
A delivery delay holds a queue message out of consumers' reach for a fixed window after it's sent — the message is accepted and persisted immediately, but invisible to pollers until the delay expires. It's the building block for scheduled work — a reminder to fire in an hour, a retry with back-off, a task queued for off-peak processing — without standing up a separate scheduler or cron service.
Set it with SetDelaySeconds() on the QueueMessage::Builder before sending; the broker does the waiting. The send result's delayed_to field returns the Unix timestamp when the message becomes visible, so you can log or monitor exactly when delivery will happen. Until then, any poll against that channel simply returns nothing for that message — it isn't hidden in a separate place, it's the same queue, just not yet eligible for delivery.
Gotchas: the delay is set once at send time and can't be extended or shortened afterward — if you need a different wait, send a new message. A long delay still counts as an in-flight, persisted message, so it survives a broker restart, but it also occupies queue storage for the whole waiting period. Don't confuse this with a visibility timeout after delivery — that's a separate mechanism for redelivery on failed acknowledgment, not initial availability.
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: queues/delayed_messages
//
// Demonstrates sending a delayed queue message. The message becomes
// available for consumption only after the specified delay period.
//
// Channel: cpp-queues.delayed-messages
// Client ID: cpp-queues-delayed-messages-client
//
// Run with a KubeMQ server on localhost:50000
// (see https://docs.kubemq.io/deploy).
#include <kubemq/kubemq.h>
#include <iostream>
int main() {
std::cout << "[1] Connecting to localhost:50000" << std::endl;
kubemq::ClientOptions options;
options.set_address("localhost", 50000);
options.set_client_id("cpp-queues-delayed-messages-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;
std::string channel = "cpp-queues.delayed-messages";
// Send a message with a 3-second delay.
std::cout << "[2] Sending delayed message (3s) to queue " << channel << std::endl;
auto msg_result = kubemq::QueueMessage::Builder()
.SetChannel(channel)
.SetBody("delayed message")
.SetDelaySeconds(3)
.Build();
if (!msg_result.ok()) {
std::cerr << "[ERROR] Build message: " << msg_result.status().message() << std::endl;
return 1;
}
auto send_result = client->SendQueueMessage(*msg_result);
if (!send_result.ok()) {
std::cerr << "[ERROR] SendQueueMessage: " << send_result.status().message() << std::endl;
return 1;
}
if (send_result->is_error) {
std::cerr << "[ERROR] Send failed: " << send_result->error << std::endl;
return 1;
}
std::cout << "[3] Delayed message sent: id=" << send_result->message_id
<< " delayed_to=" << send_result->delayed_to << std::endl;
std::cout << "[4] Message will be available after 3 seconds" << std::endl;
// Close the client explicitly.
// Note: The Client destructor also calls Close(), but explicit
// cleanup is shown here for clarity and to match Go's defer pattern.
auto close_status = client->Close();
if (!close_status.ok()) {
std::cerr << "[ERROR] Close failed: " << close_status.message() << std::endl;
return 1;
}
std::cout << "[5] Client closed" << std::endl;
return 0;
}How It Works
- Sets a delay on queue messages using
SetDelaySeconds()in the builder. - Delayed messages are not available for consumption until the delay expires.
- The delay is specified in seconds from the time of sending.
- Useful for scheduled tasks, retry backoff, and time-based workflows.
Related
Was this page helpful?