Skip to content

Latest commit

 

History

History
349 lines (253 loc) · 10.3 KB

api.md

File metadata and controls

349 lines (253 loc) · 10.3 KB

API Documentation

Warning

*::detail namespaces are considered internal and may change without any warning.

Important

(asio) indicates it's only available when using Asio (i.e. compiled with GRPCXX_USE_ASIO). (libuv) indicates it's only available when using libuv, which is the default.

grpcxx::rpc

Defined in header <grpcxx/rpc.h>.

template <
  fixed_string M,
  typename T,
  typename U
> struct rpc;

grpcxx::rpc template class holds the definition for an RPC method within a gRPC service.

Template parameters
M Method name
T Request message type
U Response message type

T and U are typically Protobuf generated types but they don't have to be. As long as T can be constructed from a const char * and U can be converted to a std::string any type would work.

Example

service Greeter {
  rpc Hello(GreeterHelloRequest) returns (GreeterHelloResponse) {}
}
using rpcHello = grpcxx::rpc<"Hello", GreeterHelloRequest, GreeterHelloResponse>;

grpcxx::service

Defined in header <grpcxx/service.h>.

template <
  fixed_string N,
  concepts::rpc_type... R
> class service;

grpcxx::service template class holds the definition for a gRPC service.

Template parameters
N Service name
R... RPC methods within the service

R.. could be types defined using grpcxx::rpc template class or any other type that conforms to grpcxx::concepts::rpc_type.

Example

service Greeter {
  rpc Hello(GreeterHelloRequest) returns (GreeterHelloResponse) {}
}
using rpcHello = grpcxx::rpc<"Hello", GreeterHelloRequest, GreeterHelloResponse>;

using Service = grpcxx::service<"Greeter", rpcHello>;

grpcxx::server

Defined in header <grpcxx/server.h>.

class server;

A gRPC server capable of serving multiple clients.

Member functions

(constructor)
server() (1) (asio)
server(std::size_t n = std::thread::hardware_concurrency()) noexcept; (2) (libuv)

Constructs a new server instance.

  1. Constructs a server using the default constructor.
  2. Constructs a server with n worker threads (in addition to the I/O thread). If n is 0, all requests will be processed in the I/O thread.

Tip

Number of worker threads can impact throughput and should be tuned for your use-case (i.e. more workers will not always increase throughput).

add
template <typename S> void add(S &s); (1)

Add a gRPC service implementation to the server.

  1. Add a gRPC service implemented by s. s must stay in scope while the server in running. If two services are added with the same name, the second will be ignored.

listen
ASIO_NS::awaitable<void> listen(std::string_view ip, int port); (1) (asio)
uv_loop_t *listen(std::string_view ip, int port); (2) (libuv)
uv_loop_t *listen(uv_os_sock_t &&sock); (3) (libuv)

Listen and prepare to serve incoming gRPC requests.

  1. Await on a coroutine executor and listen on ip and port for incoming gRPC connections. The returned awaitable must be passed on to an io_context executor to serve requests.
  2. Listen on ip and port for incoming gRPC connections and returns a pointer to the event loop. The returned event loop can be used to run the loop externally or add external events to the loop. The loop will be stopped when the server instance is destroyed. No request will be served until the loop is run, either externally or by calling run(std::stop_token token = {}).
  3. Listen on an existing socket handler sock for incoming gRPC connections and returns a pointer to the event loop. The socket handler must be already bound to a network address and will be closed when the server stops. The event loop behaviour is same as (2).

run
void run(const std::string_view &ip, int port); (1) (asio)
void run(std::string_view ip, int port, std::stop_token token = {}); (2) (libuv)
void run(uv_os_sock_t &&sock, std::stop_token token = {}); (3) (libuv)
void run(std::stop_token token = {}); (4) (libuv)

Listen and serve incoming gRPC requests.

  1. Start listening on ip and port for incoming gRPC connections and serve requests.
  2. Same as (1), but accepting an optional stop token to asynchronously signal the server to exit.
  3. Start listening on the socket handler sock for incoming gRPC connections and serve requests. The socket handler must be already bound to a network address and will be closed when the server stops. This is useful when the socket needs to have some additional properties set (such as keep-alive) and/or reused outside the run context (e.g. when using systemd socket activation protocol).
  4. Run the server until a stop is requested or there aren't any active handlers in the event loop. This can be called after calling listen(...).

Important

If used with Asio, this will create and run an io_context executor on the main thread.

Example (asio)

ServiceImpl impl;
Service     service(impl);

grpcxx::server server;
server.add(service);

asio::io_context ctx;
asio::co_spawn(ctx, server.listen("127.0.0.1", 50051), asio::detached);

std::list<std::thread> threads;
for (auto i = 0; i < 2; i++) {
  threads.emplace_back([&ctx] { ctx.run(); });
}

for (auto &t : threads) {
  t.join();
}

Example (libuv)

ServiceImpl impl;
Service     service(impl);

grpcxx::server server(2);
server.add(service);

server.run("127.0.0.1", 50051);

grpcxx::context

Defined in header <grpcxx/context.h>.

class context;

grpcxx::context class carry additional contextual data relevant for gRPC requests.

Member types

Type Definition
meta_t std::unordered_map<std::string_view, std::string_view>;

Member functions

meta
meta_t::mapped_type meta(meta_t::key_type key) const noexcept; (1)

Retrieve gRPC custom metadata.

  1. Retrieve gRPC custom metadata value for key key. If there's no value found for the specified key, an empty value is returned.

Tip

Custom Metadata are essentially HTTP/2 headers that doesn't start with : or grpc-.

grpcxx::status

Defined in header <grpcxx/status.h>.

class status;

grpcxx::status class represents a gRPC response status.

Member types

Type Definition
code_t enum struct code_t : int8_t 
enum struct code_t : int8_t {
  ok                  = 0,
  cancelled           = 1,
  unknown             = 2,
  invalid_argument    = 3,
  deadline_exceeded   = 4,
  not_found           = 5,
  already_exists      = 6,
  permission_denied   = 7,
  resource_exhausted  = 8,
  failed_precondition = 9,
  aborted             = 10,
  out_of_range        = 11,
  unimplemented       = 12,
  internal            = 13,
  unavailable         = 14,
  data_loss           = 15,
  unauthenticated     = 16,
};

Member functions

(constructor)
status(code_t code = code_t::ok) (1)
status(code_t code, std::string &&details) (2)
  1. Construct a status with an optional status code code.
  2. Construct a status with code code and a base64 encoded details. Although it's not in official gRPC documentation (yet), details should be base64 encoded serialised value of a google.rpc.Status message.

operator std::string_view
operator std::string_view() const (1)

Returns a std::string_view representation of the status.

code
code_t code() const noexcept (1)

Returns the status code.

str
std::string_view str() const (1)

Returns a std::string_view representation of the status.

Example

grpcxx::status s1; // ok
grpcxx::status s2(grpcxx::status::code_t::internal); // internal