# Send & Receive (/sdks/cpp/tutorials/send-receive)



## Overview [#overview]

Queue send/receive is the foundational operation for guaranteed-delivery, point-to-point messaging: you reach for it whenever work needs to survive past the moment it's created and be handled by exactly one consumer, not broadcast to every subscriber. Unlike pub/sub, a queued message sits durably on the broker until something pulls it, so the producer and consumer never need to be online at the same time — a slow or offline worker adds latency, it doesn't drop the message.

This tutorial builds the smallest possible version of that round trip: `client->SendQueueMessage` enqueues a message built with `QueueMessage::Builder()`, and `client->PollQueue` pulls it back using a `PollRequest` with a bounded `wait_timeout_seconds`. The `auto_ack` field controls settlement — set `true` and the broker acknowledges each message automatically the instant it's delivered.

**Gotchas:** auto-ack means "delivered," not "processed" — if your handler crashes after receiving but before finishing the work, the message is already gone with no chance to retry. Polling an empty queue isn't an error; `PollQueue` just returns an empty result once the wait timeout elapses, so always check `is_error()` rather than treating zero messages as a failure. And `max_items` caps how many messages a single poll can return, so don't assume one call drains the whole queue.

## Prerequisites [#prerequisites]

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

## Code [#code]

```cpp title="main.cc"
// Example: queues/send_receive
//
// Demonstrates basic queue send and receive operations.
// A message is sent to a queue and then consumed (pulled) with auto-ack.
//
// Channel: cpp-queues.send-receive
// Client ID: cpp-queues-send-receive-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-send-receive-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.send-receive";

    // Build and send a single queue message.
    std::cout << "[2] Sending message to queue " << channel << std::endl;
    auto msg_result = kubemq::QueueMessage::Builder()
                          .SetChannel(channel)
                          .SetBody("hello queue")
                          .SetMetadata("greeting")
                          .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] Sent: id=" << send_result->message_id << std::endl;

    // Receive (consume) messages from the queue via PollQueue with auto-ack.
    std::cout << "[4] Polling queue " << channel << std::endl;
    kubemq::PollRequest poll_req;
    poll_req.channel = channel;
    poll_req.max_items = 10;
    poll_req.wait_timeout_seconds = 5;
    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 failed: " << poll_result->error() << std::endl;
        return 1;
    }
    std::cout << "[5] Received: " << poll_result->messages().size() << " messages" << std::endl;
    for (const auto& dm : poll_result->messages()) {
        std::cout << "  body=" << dm.message().body() << " metadata=" << dm.message().metadata()
                  << 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 [#how-it-works]

* Sends a message to a queue using `QueueMessage::Builder()` and `SendQueueMessage()`.
* Receives messages using `PollQueue()` with a configured `PollRequest` (channel, max items, wait timeout, auto-ack).
* Each received message includes body, metadata, and sequence information via `PollResponse::messages()`.
* With `auto_ack = true`, messages are acknowledged automatically on receipt.

## Related [#related]

* [Pattern overview](/learn/queues/getting-started)
* [C++ SDK Reference](/sdks/cpp/reference/queues)
* [Batch Send](/sdks/cpp/how-to/queues/batch-send)
* [Ack All](/sdks/cpp/how-to/queues/ack-all)