Overview

Poll mode is a pull-based way to consume queue messages: the consumer decides exactly when to ask for work and how much, instead of holding an open stream the broker pushes into. That control matters for batch jobs, cron-triggered workers, and any consumer that only runs intermittently and would rather ask "is there anything for me?" than keep a subscription alive.

A single call to PollQueue() sends a channel, max_items, and wait_timeout_seconds; the broker holds the request open as a long poll and returns once enough messages are available or the timeout elapses, so the call never spins on an empty queue. auto_ack = true on the PollRequest settles the whole batch on delivery, with no separate ack step.

Gotchas: auto-ack removes messages the instant they're delivered — a crash mid-processing loses them, so set auto_ack = false and settle manually when work can fail; the timeout bounds latency, not throughput, so a small max_items on a busy queue means many round trips; and PollQueue() wraps the same receiver machinery as streaming — use a persistent stream instead for continuous, low-latency consumption.

Prerequisites

KubeMQ server running on localhost:50000
C++ SDK installed (vcpkg or CMake FetchContent)
C++17 compiler (GCC 9+, Clang 9+, MSVC 2019+)

Code

main.cc

// Example: queues_stream/poll_mode
//
// Demonstrates PollQueue for simple single-shot queue polling.
// PollQueue is a high-level abstraction that handles the receiver lifecycle
// automatically with auto-ack.
//
// Channel: cpp-queues.poll-mode
// Client ID: cpp-queues-poll-mode-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-poll-mode-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.poll-mode";

    // Send 3 messages to poll.
    std::cout << "[2] Sending 3 messages to queue " << channel << std::endl;
    for (int i = 1; i <= 3; i++) {
        auto msg_result = kubemq::QueueMessage::Builder()
                              .SetChannel(channel)
                              .SetBody("poll-msg-" + std::to_string(i))
                              .Build();
        if (!msg_result.ok()) {
            std::cerr << "[ERROR] Build message " << i << ": " << msg_result.status().message()
                      << std::endl;
            return 1;
        }
        auto send_result = client->SendQueueMessage(*msg_result);
        if (!send_result.ok()) {
            std::cerr << "[ERROR] SendQueueMessage " << i << ": " << send_result.status().message()
                      << std::endl;
            return 1;
        }
    }
    std::cout << "[3] Sent 3 messages" << std::endl;

    // PollQueue: single-shot poll with auto-ack.
    std::cout << "[4] Polling queue with auto-ack" << std::endl;
    kubemq::PollRequest poll_req;
    poll_req.channel = channel;
    poll_req.max_items = 10;
    poll_req.wait_timeout_seconds = 3;
    poll_req.auto_ack = true;

    auto poll_result = client->PollQueue(poll_req);
    if (!poll_result.ok()) {
        std::cerr << "[ERROR] PollQueue: " << poll_result.status().message() << std::endl;
        return 1;
    }
    if (poll_result->is_error()) {
        std::cerr << "[ERROR] Poll response: " << poll_result->error() << std::endl;
        return 1;
    }

    std::cout << "[5] PollQueue: " << poll_result->messages().size() << " messages" << std::endl;
    for (const auto& dm : poll_result->messages()) {
        std::cout << "  body=" << dm.message().body() << 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 << "[6] Client closed" << std::endl;

    return 0;
}

How It Works

Uses PollQueue() as a convenience wrapper for one-shot polling.
Configures PollRequest with channel, max items, wait timeout, and auto-ack.
The poll blocks until messages arrive or the timeout expires.
Returns a PollResponse with messages and settlement methods.

Poll Mode

Overview

Prerequisites

Code

How It Works

On this page

Poll Mode

Overview

Prerequisites

Code

How It Works

Related

On this page