ping

ping measures transport-level websocket latency for the current blaze::session. Unlike API operations such as initialize or authorize, it does not return blaze::status and does not depend on application initialization state.

Function variants

std::chrono::milliseconds ping();
std::chrono::milliseconds ping(std::error_code& ec) noexcept;
void async_ping(std::function<void(std::error_code, std::chrono::milliseconds)> callback);
blaze::coro::awaitable_result<std::chrono::milliseconds> co_ping();

No API status here

ping measures websocket ping/pong round-trip time. Failures are reported through std::error_code or std::system_error, not through blaze::status.

Result

std::chrono::milliseconds

Type	Meaning
`std::chrono::milliseconds`	Elapsed time between sending websocket ping and receiving pong.

Behavior notes

Call ping after a successful connect.
ping does not require initialize.
The returned value measures websocket transport round-trip time, not Blazeauth packet handler execution time.
ping participates in the same session send-rate limiting as other outgoing operations.
Sync overloads use the session timeout configured in the constructor or via with_timeout(...).

Example

Compilation note

Synchronous and Asynchronous examples compile in the same form from C++14 to C++26.

#include "blazeauth/api/api.hpp"

#include <chrono>
#include <iostream>
#include <string>
#include <system_error>

void print_error_code(const std::string& context, const std::error_code& ec) {
  std::cout << context << ": " << ec.message() << " ("
            << ec.value() << " : " << ec.category().name() << ")\n";
}

int main() {
  blaze::session session;

  try {
    const blaze::api_server server = session.connect();
    std::cout << "Connected to server location: " << server.location << '\n';

    const std::chrono::milliseconds rtt = session.ping();
    std::cout << "Ping RTT: " << rtt.count() << " ms\n";

    session.shutdown();
  } catch (const std::system_error& e) {
    print_error_code("Ping failed", e.code());
    return 1;
  }

  return 0;
}

#include "blazeauth/api/api.hpp"

#include <chrono>
#include <future>
#include <iostream>
#include <string>
#include <system_error>

void print_error_code(const std::string& context, const std::error_code& ec) {
  std::cout << context << ": " << ec.message() << " ("
            << ec.value() << " : " << ec.category().name() << ")\n";
}

int main() {
  blaze::session session;

  std::promise<int> completion;
  std::future<int> result = completion.get_future();

  session.async_connect([&session, &completion](std::error_code connect_ec, blaze::api_server server) {
    if (connect_ec) {
      print_error_code("Connect failed", connect_ec);
      completion.set_value(1);
      return;
    }

    std::cout << "Connected to server location: " << server.location << '\n';

    session.async_ping([&session, &completion](std::error_code ping_ec, std::chrono::milliseconds rtt) {
      if (ping_ec) {
        print_error_code("Ping failed", ping_ec);
        session.async_shutdown([&completion](std::error_code) { completion.set_value(1); });
        return;
      }

      std::cout << "Ping RTT: " << rtt.count() << " ms\n";

      session.async_shutdown([&completion](std::error_code shutdown_ec) {
        if (shutdown_ec) {
          print_error_code("Shutdown failed", shutdown_ec);
          completion.set_value(1);
          return;
        }

        completion.set_value(0);
      });
    });
  });

  return result.get();
}

Project must be built with C++20 support and with coroutine support available both in the language mode and in the standard library implementation for this example to compile correctly.

#include "blazeauth/api/api.hpp"

#include <chrono>
#include <future>
#include <iostream>
#include <string>
#include <system_error>

void print_error_code(const std::string& context, const std::error_code& ec) {
  std::cout << context << ": " << ec.message() << " ("
            << ec.value() << " : " << ec.category().name() << ")\n";
}

#if BLAZEAUTH_HAS_COROUTINES

blaze::coro::task<std::error_code> run_example(blaze::session& session) {
  const auto [connect_ec, server] = co_await session.co_connect();
  if (connect_ec) {
    co_return connect_ec;
  }

  std::cout << "Connected to server location: " << server.location << '\n';

  const auto [ping_ec, rtt] = co_await session.co_ping();
  if (ping_ec) {
    co_return ping_ec;
  }

  std::cout << "Ping RTT: " << rtt.count() << " ms\n";

  const auto [shutdown_ec] = co_await session.co_shutdown();
  co_return shutdown_ec;
}

int main() {
  blaze::session session;

  std::promise<std::error_code> completion;
  std::future<std::error_code> result = completion.get_future();

  blaze::coro::co_spawn([&session, &completion]() -> blaze::coro::task<void> {
    const std::error_code ec = co_await run_example(session);
    completion.set_value(ec);
    co_return;
  }());

  const std::error_code ec = result.get();
  if (ec) {
    print_error_code("Ping failed", ec);
    return 1;
  }

  return 0;
}

#else

int main() {
  std::cout << "This example requires coroutine support in the Blazeauth library build.\n";
  return 0;
}

#endif

Error handling

You can match generic failures against blaze::errc, for example: if (ec == blaze::errc::connection_lost).

Error condition	When it can happen
`not_connected`	`ping` was called while the session was not connected.
`rate_limit_reached`	Session send rate limit was reached before ping could be started.
`timed_out`	A sync overload exceeded the configured session timeout while waiting for pong.
`operation_would_block`	A sync overload was called from the library I/O thread.
`connection_closed`	Server closed the websocket before ping completed.
`connection_lost`	Network connection was lost while waiting for pong.
`protocol_error`	Transport or websocket protocol handling failed during the ping flow.