grpc::ServerBuilder Class Reference

A builder class for the creation and startup of grpc::Server instances. More...

#include <server_builder.h>

Data Structures
class	experimental_type
	NOTE: class experimental_type is not part of the public API of this class. More...
struct	NamedService
struct	Port
	Experimental, to be deprecated. More...

Public Types
enum	SyncServerOption { NUM_CQS, MIN_POLLERS, MAX_POLLERS, CQ_TIMEOUT_MSEC }
	Options for synchronous servers. More...

Public Member Functions
	ServerBuilder ()
virtual	~ServerBuilder ()
virtual std::unique_ptr< grpc::Server >	BuildAndStart ()
	Return a running server which is ready for processing calls. More...
ServerBuilder &	RegisterService (grpc::Service *service)
	Register a service. More...
ServerBuilder &	AddListeningPort (const std::string &addr_uri, std::shared_ptr< grpc::ServerCredentials > creds, int *selected_port=nullptr)
	Enlists an endpoint addr (port with an optional IP address) to bind the grpc::Server object to be created to. More...
std::unique_ptr< grpc::ServerCompletionQueue >	AddCompletionQueue (bool is_frequently_polled=true)
	Add a completion queue for handling asynchronous services. More...
ServerBuilder &	RegisterService (const std::string &host, grpc::Service *service)
	Register a service. More...
ServerBuilder &	RegisterAsyncGenericService (grpc::AsyncGenericService *service)
	Register a generic service. More...
ServerBuilder &	SetMaxReceiveMessageSize (int max_receive_message_size)
	Set max receive message size in bytes. More...
ServerBuilder &	SetMaxSendMessageSize (int max_send_message_size)
	Set max send message size in bytes. More...
ServerBuilder &	SetMaxMessageSize (int max_message_size)
ServerBuilder &	SetCompressionAlgorithmSupportStatus (grpc_compression_algorithm algorithm, bool enabled)
	Set the support status for compression algorithms. More...
ServerBuilder &	SetDefaultCompressionLevel (grpc_compression_level level)
	The default compression level to use for all channel calls in the absence of a call-specific level. More...
ServerBuilder &	SetDefaultCompressionAlgorithm (grpc_compression_algorithm algorithm)
	The default compression algorithm to use for all channel calls in the absence of a call-specific level. More...
ServerBuilder &	SetResourceQuota (const grpc::ResourceQuota &resource_quota)
	Set the attached buffer pool for this server. More...
ServerBuilder &	SetEventEngine (std::shared_ptr< grpc_event_engine::experimental::EventEngine > event_engine)
ServerBuilder &	SetOption (std::unique_ptr< grpc::ServerBuilderOption > option)
ServerBuilder &	SetSyncServerOption (SyncServerOption option, int value)
	Only useful if this is a Synchronous server. More...
template<class T >
ServerBuilder &	AddChannelArgument (const std::string &arg, const T &value)
	Add a channel argument (an escape hatch to tuning core library parameters directly) More...
ServerBuilder &	EnableWorkaround (grpc_workaround_list id)
	Enable a server workaround. More...
ServerBuilder &	SetContextAllocator (std::unique_ptr< grpc::ContextAllocator > context_allocator)
	Set the allocator for creating and releasing callback server context. More...
ServerBuilder &	RegisterCallbackGenericService (grpc::CallbackGenericService *service)
	Register a generic service that uses the callback API. More...
experimental_type	experimental ()
	NOTE: The function experimental() is not stable public API. More...

Static Public Member Functions
static void	InternalAddPluginFactory (std::unique_ptr< grpc::ServerBuilderPlugin >(*CreatePlugin)())
	For internal use only: Register a ServerBuilderPlugin factory function. More...

Protected Types
typedef std::unique_ptr< std::string >	HostString
	Experimental, to be deprecated. More...

Protected Member Functions
std::vector< Port >	ports ()
	Experimental, to be deprecated. More...
std::vector< NamedService * >	services ()
	Experimental, to be deprecated. More...
std::vector< grpc::ServerBuilderOption * >	options ()
	Experimental, to be deprecated. More...
void	set_fetcher (grpc_server_config_fetcher *server_config_fetcher)
	Experimental API, subject to change. More...
virtual ChannelArguments	BuildChannelArgs ()
	Experimental API, subject to change. More...

Friends
class	grpc::testing::ServerBuilderPluginTest

Detailed Description

A builder class for the creation and startup of grpc::Server instances.

Member Typedef Documentation

HostString

typedef std::unique_ptr<std::string> grpc::ServerBuilder::HostString

protected

Experimental, to be deprecated.

Member Enumeration Documentation

SyncServerOption

enum grpc::ServerBuilder::SyncServerOption

Options for synchronous servers.

Enumerator
NUM_CQS	Number of completion queues.
MIN_POLLERS	Minimum number of polling threads.
MAX_POLLERS	Maximum number of polling threads.
CQ_TIMEOUT_MSEC	Completion queue timeout in milliseconds.

Constructor & Destructor Documentation

ServerBuilder()

grpc::ServerBuilder::ServerBuilder

(

)

~ServerBuilder()

virtual grpc::ServerBuilder::~ServerBuilder ( )

virtual

Member Function Documentation

AddChannelArgument()

template<class T >

ServerBuilder& grpc::ServerBuilder::AddChannelArgument ( const std::string &  arg, const T &  value  )

inline

Add a channel argument (an escape hatch to tuning core library parameters directly)

AddCompletionQueue()

std::unique_ptr<grpc::ServerCompletionQueue> grpc::ServerBuilder::AddCompletionQueue

(

bool

is_frequently_polled = true

)

Add a completion queue for handling asynchronous services.

Best performance is typically obtained by using one thread per polling completion queue.

Caller is required to shutdown the server prior to shutting down the returned completion queue. Caller is also required to drain the completion queue after shutting it down. A typical usage scenario:

// While building the server: ServerBuilder builder; ... cq_ = builder.AddCompletionQueue(); server_ = builder.BuildAndStart();

// While shutting down the server; server_->Shutdown(); cq_->Shutdown(); // Always after the associated server's Shutdown()! // Drain the cq_ that was created void* ignored_tag; bool ignored_ok; while (cq_->Next(&ignored_tag, &ignored_ok)) { }

Parameters

is_frequently_polled

This is an optional parameter to inform gRPC library about whether this completion queue would be frequently polled (i.e. by calling Next() or AsyncNext()). The default value is 'true' and is the recommended setting. Setting this to 'false' (i.e. not polling the completion queue frequently) will have a significantly negative performance impact and hence should not be used in production use cases.

AddListeningPort()

ServerBuilder& grpc::ServerBuilder::AddListeningPort	(	const std::string &	addr_uri,
		std::shared_ptr< grpc::ServerCredentials >	creds,
		int *	selected_port = nullptr
	)

Enlists an endpoint addr (port with an optional IP address) to bind the grpc::Server object to be created to.

It can be invoked multiple times.

Parameters

	addr_uri	The address to try to bind to the server in URI form. If the scheme name is omitted, "dns:///" is assumed. To bind to any address, please use IPv6 any, i.e., [::]:<port>, which also accepts IPv4 connections. Valid values include dns:///localhost:1234, 192.168.1.1:31416, dns:///[::1]:27182, etc.
	creds	The credentials associated with the server.
[out]	selected_port	If not nullptr, gets populated with the port number bound to the grpc::Server for the corresponding endpoint after it is successfully bound by BuildAndStart(), 0 otherwise. AddListeningPort does not modify this pointer.

BuildAndStart()

virtual std::unique_ptr<grpc::Server> grpc::ServerBuilder::BuildAndStart ( )

virtual

Return a running server which is ready for processing calls.

Before calling, one typically needs to ensure that:

1. a service is registered - so that the server knows what to serve (via RegisterService, or RegisterAsyncGenericService)
2. a listening port has been added - so the server knows where to receive traffic (via AddListeningPort)
3. [for async api only] completion queues have been added via AddCompletionQueue

Will return a nullptr on errors.

BuildChannelArgs()

virtual ChannelArguments grpc::ServerBuilder::BuildChannelArgs ( )

protectedvirtual

Experimental API, subject to change.

EnableWorkaround()

ServerBuilder& grpc::ServerBuilder::EnableWorkaround

(

grpc_workaround_list

id

)

Enable a server workaround.

Do not use unless you know what the workaround does. For explanation and detailed descriptions of workarounds, see doc/workarounds.md.

experimental()

experimental_type grpc::ServerBuilder::experimental ( )

inline

NOTE: The function experimental() is not stable public API.

It is a view to the experimental components of this class. It may be changed or removed at any time.

InternalAddPluginFactory()

static void grpc::ServerBuilder::InternalAddPluginFactory ( std::unique_ptr< grpc::ServerBuilderPlugin >(*)()  CreatePlugin )

static

For internal use only: Register a ServerBuilderPlugin factory function.

options()

std::vector<grpc::ServerBuilderOption*> grpc::ServerBuilder::options ( )

inlineprotected

Experimental, to be deprecated.

ports()

std::vector<Port> grpc::ServerBuilder::ports ( )

inlineprotected

Experimental, to be deprecated.

RegisterAsyncGenericService()

ServerBuilder& grpc::ServerBuilder::RegisterAsyncGenericService

(

grpc::AsyncGenericService *

service

)

Register a generic service.

Matches requests with any :authority This is mostly useful for writing generic gRPC Proxies where the exact serialization format is unknown

RegisterCallbackGenericService()

ServerBuilder& grpc::ServerBuilder::RegisterCallbackGenericService

(

grpc::CallbackGenericService *

service

)

Register a generic service that uses the callback API.

Matches requests with any :authority This is mostly useful for writing generic gRPC Proxies where the exact serialization format is unknown

RegisterService() [1/2]

ServerBuilder& grpc::ServerBuilder::RegisterService	(	const std::string &	host,
		grpc::Service *	service
	)

Register a service.

This call does not take ownership of the service. The service must exist for the lifetime of the Server instance returned by BuildAndStart(). Only matches requests with :authority host

RegisterService() [2/2]

ServerBuilder& grpc::ServerBuilder::RegisterService

(

grpc::Service *

service

)

Register a service.

This call does not take ownership of the service. The service must exist for the lifetime of the Server instance returned by BuildAndStart(). Matches requests with any :authority

services()

std::vector<NamedService*> grpc::ServerBuilder::services ( )

inlineprotected

Experimental, to be deprecated.

set_fetcher()

void grpc::ServerBuilder::set_fetcher ( grpc_server_config_fetcher *  server_config_fetcher )

inlineprotected

Experimental API, subject to change.

SetCompressionAlgorithmSupportStatus()

ServerBuilder& grpc::ServerBuilder::SetCompressionAlgorithmSupportStatus	(	grpc_compression_algorithm	algorithm,
		bool	enabled
	)

Set the support status for compression algorithms.

All algorithms are enabled by default.

Incoming calls compressed with an unsupported algorithm will fail with GRPC_STATUS_UNIMPLEMENTED.

SetContextAllocator()

ServerBuilder& grpc::ServerBuilder::SetContextAllocator

(

std::unique_ptr< grpc::ContextAllocator >

context_allocator

)

Set the allocator for creating and releasing callback server context.

Takes the owndership of the allocator.

SetDefaultCompressionAlgorithm()

ServerBuilder& grpc::ServerBuilder::SetDefaultCompressionAlgorithm

(

grpc_compression_algorithm

algorithm

)

The default compression algorithm to use for all channel calls in the absence of a call-specific level.

Note that it overrides any compression level set by SetDefaultCompressionLevel.

SetDefaultCompressionLevel()

ServerBuilder& grpc::ServerBuilder::SetDefaultCompressionLevel

(

grpc_compression_level

level

)

The default compression level to use for all channel calls in the absence of a call-specific level.

SetEventEngine()

ServerBuilder& grpc::ServerBuilder::SetEventEngine

(

std::shared_ptr< grpc_event_engine::experimental::EventEngine >

event_engine

)

SetMaxMessageSize()

ServerBuilder& grpc::ServerBuilder::SetMaxMessageSize ( int  max_message_size )

inline

Deprecated:

For backward compatibility.

SetMaxReceiveMessageSize()

ServerBuilder& grpc::ServerBuilder::SetMaxReceiveMessageSize ( int  max_receive_message_size )

inline

Set max receive message size in bytes.

The default is GRPC_DEFAULT_MAX_RECV_MESSAGE_LENGTH.

SetMaxSendMessageSize()

ServerBuilder& grpc::ServerBuilder::SetMaxSendMessageSize ( int  max_send_message_size )

inline

Set max send message size in bytes.

The default is GRPC_DEFAULT_MAX_SEND_MESSAGE_LENGTH.

SetOption()

ServerBuilder& grpc::ServerBuilder::SetOption

(

std::unique_ptr< grpc::ServerBuilderOption >

option

)

SetResourceQuota()

ServerBuilder& grpc::ServerBuilder::SetResourceQuota

(

const grpc::ResourceQuota &

resource_quota

)

Set the attached buffer pool for this server.

SetSyncServerOption()

ServerBuilder& grpc::ServerBuilder::SetSyncServerOption	(	SyncServerOption	option,
		int	value
	)

Only useful if this is a Synchronous server.

Friends And Related Function Documentation

grpc::testing::ServerBuilderPluginTest

friend class grpc::testing::ServerBuilderPluginTest

friend

Field Documentation

algorithm

grpc_compression_algorithm grpc::ServerBuilder::algorithm

is_set

bool grpc::ServerBuilder::is_set

level

grpc_compression_level grpc::ServerBuilder::level

---

The documentation for this class was generated from the following file:

• include/grpcpp/server_builder.h