Connect

Overview

Every KubeMQ application starts the same way: open a connection to the broker and prove it actually works before building anything on top of it. This tutorial is that first lesson — create a client, give it a stable identity, and confirm connectivity with a health check, so the pattern is muscle memory before you move on to real messaging.

ClientOptions is populated with an address and a client_id — the ID tags this connection in broker logs, subscriptions, and management views, so pick something stable rather than a random string. Client::Create() returns a StatusOr<unique_ptr<Client>>, so checking ok() catches construction failures immediately instead of dereferencing a null client. client->Ping() verifies the round trip cheaply: it returns live server info (host, version, uptime) instead of just a success status, proving the client is talking to a real broker rather than silently misconfigured. client->Close() releases the connection explicitly, though the destructor handles it too via RAII.

Gotchas: a successful Create() doesn't always mean the broker is reachable — connection can happen lazily, so Ping() is the only reliable proof; reusing the same client ID across running instances causes routing confusion on the broker; and relying on the destructor instead of an explicit Close() in long-lived processes can delay releasing the connection longer than expected.

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: connection/connect
//
// Demonstrates how to create a basic KubeMQ client connection.
// The client connects to a KubeMQ server on localhost:50000 and verifies
// connectivity with a Ping.
//
// Channel: cpp-connection.connect
// Client ID: cpp-connection-connect-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;

    // Create a KubeMQ client with basic configuration.
    kubemq::ClientOptions options;
    options.set_address("localhost", 50000);
    options.set_client_id("cpp-connection-connect-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;

    // Verify the connection by pinging the server.
    auto ping_result = client->Ping();
    if (!ping_result.ok()) {
        std::cerr << "[ERROR] Ping failed: " << ping_result.status().message() << std::endl;
        return 1;
    }
    std::cout << "[2] Connected successfully: host=" << ping_result->host
              << " version=" << ping_result->version
              << " uptime=" << ping_result->server_up_time_seconds << "s" << std::endl;

    // Close the client explicitly.
    // Note: Client destructor would also handle cleanup (RAII)
    auto close_status = client->Close();
    if (!close_status.ok()) {
        std::cerr << "[ERROR] Close failed: " << close_status.message() << std::endl;
        return 1;
    }
    std::cout << "[3] Client closed" << std::endl;

    return 0;
}

How It Works

• Creates a ClientOptions instance and sets the broker address and client ID.
• Calls Client::Create() which returns a StatusOr<unique_ptr<Client>> -- check ok() before use.
• Verifies the connection with Ping(), which returns server information.
• Closes the client explicitly with Close(). The destructor also handles cleanup (RAII).

Related

• C++ SDK Reference
• Close
• Ping