Overview

A ping is a lightweight liveness check — you call it to confirm the broker is actually reachable before sending real traffic, without standing up a publisher, subscriber, or queue client just to find out. It's the tool of choice for startup readiness checks, container liveness/readiness probes, and connection-health dashboards that need a fast, cheap go/no-go signal.

client->Ping() issues a minimal RPC to the server and returns a StatusOr<ServerInfo> (host, version, uptime) confirming the broker answered. It works over the same connection regardless of which messaging pattern you use elsewhere on that client — events, queues, commands, or queries — and doesn't touch any channel.

Gotchas: a failed Ping() doesn't close the client — the SDK's reconnect logic keeps retrying in the background, so check the returned StatusOr yourself rather than assume the client tears itself down. A successful ping only confirms the broker process answered, not that a specific channel or queue exists or has capacity. And since the gRPC channel is often established lazily, the first call you make is what actually triggers the connection.

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: connection/ping
//
// Demonstrates how to ping a KubeMQ server to verify connectivity and
// retrieve server information (host, version, uptime).
//
// Channel: cpp-connection.ping
// Client ID: cpp-connection-ping-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-connection-ping-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::cout << "[2] Client connected" << std::endl;

    // Ping the server to verify connectivity and retrieve server info.
    auto ping_result = client->Ping();
    if (!ping_result.ok()) {
        std::cerr << "[ERROR] Ping failed: " << ping_result.status().message() << std::endl;
        return 1;
    }
    std::cout << "[3] Ping OK: 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 << "[4] Client closed" << std::endl;

    return 0;
}

How It Works

Connects to the broker with basic options.
Calls Ping() which returns a StatusOr<ServerInfo> containing host, version, and uptime.
Use Ping as a health check to verify the server is reachable before starting business logic.

Ping

Overview

Prerequisites

Code

How It Works

Related

On this page