#include <grpc/support/port_platform.h>
#include <grpc/status.h>
#include <grpc/byte_buffer.h>
#include <grpc/impl/codegen/connectivity_state.h>
#include <grpc/impl/codegen/grpc_types.h>
#include <grpc/impl/codegen/propagation_bits.h>
#include <grpc/slice.h>
#include <grpc/support/time.h>
#include <stddef.h>

Macros
#define	GRPC_MAX_COMPLETION_QUEUE_PLUCKERS 6
	Maximum number of outstanding grpc_completion_queue_pluck executions per completion queue. More...

Enumerations
enum	grpc_server_register_method_payload_handling { GRPC_SRM_PAYLOAD_NONE, GRPC_SRM_PAYLOAD_READ_INITIAL_BYTE_BUFFER }
	How to handle payloads for a registered method. More...

Functions
GRPCAPI void	grpc_metadata_array_init (grpc_metadata_array *array)

GRPCAPI void	grpc_metadata_array_destroy (grpc_metadata_array *array)

GRPCAPI void	grpc_call_details_init (grpc_call_details *details)

GRPCAPI void	grpc_call_details_destroy (grpc_call_details *details)

GRPCAPI void	grpc_register_plugin (void(init)(void), void(destroy)(void))
	Registers a plugin to be initialized and destroyed with the library. More...

GRPCAPI void	grpc_init (void)
	Initialize the grpc library. More...

GRPCAPI void	grpc_shutdown (void)
	Shut down the grpc library. More...

GRPCAPI int	grpc_is_initialized (void)
	EXPERIMENTAL. More...

GRPCAPI void	grpc_shutdown_blocking (void)
	EXPERIMENTAL. More...

const GRPCAPI char *	grpc_version_string (void)
	Return a string representing the current version of grpc. More...

const GRPCAPI char *	grpc_g_stands_for (void)
	Return a string specifying what the 'g' in gRPC stands for. More...

const GRPCAPI grpc_completion_queue_factory *	grpc_completion_queue_factory_lookup (const grpc_completion_queue_attributes *attributes)
	Returns the completion queue factory based on the attributes. More...

GRPCAPI grpc_completion_queue *	grpc_completion_queue_create_for_next (void *reserved)
	Helper function to create a completion queue with grpc_cq_completion_type of GRPC_CQ_NEXT and grpc_cq_polling_type of GRPC_CQ_DEFAULT_POLLING. More...

GRPCAPI grpc_completion_queue *	grpc_completion_queue_create_for_pluck (void *reserved)
	Helper function to create a completion queue with grpc_cq_completion_type of GRPC_CQ_PLUCK and grpc_cq_polling_type of GRPC_CQ_DEFAULT_POLLING. More...

GRPCAPI grpc_completion_queue *	grpc_completion_queue_create_for_callback (grpc_experimental_completion_queue_functor shutdown_callback, void reserved)
	Helper function to create a completion queue with grpc_cq_completion_type of GRPC_CQ_CALLBACK and grpc_cq_polling_type of GRPC_CQ_DEFAULT_POLLING. More...

GRPCAPI grpc_completion_queue *	grpc_completion_queue_create (const grpc_completion_queue_factory factory, const grpc_completion_queue_attributes attributes, void *reserved)
	Create a completion queue. More...

GRPCAPI grpc_event	grpc_completion_queue_next (grpc_completion_queue cq, gpr_timespec deadline, void reserved)
	Blocks until an event is available, the completion queue is being shut down, or deadline is reached. More...

GRPCAPI grpc_event	grpc_completion_queue_pluck (grpc_completion_queue cq, void tag, gpr_timespec deadline, void *reserved)
	Blocks until an event with tag 'tag' is available, the completion queue is being shutdown or deadline is reached. More...

GRPCAPI void	grpc_completion_queue_shutdown (grpc_completion_queue *cq)
	Begin destruction of a completion queue. More...

GRPCAPI void	grpc_completion_queue_destroy (grpc_completion_queue *cq)
	Destroy a completion queue. More...

GRPCAPI void	grpc_completion_queue_thread_local_cache_init (grpc_completion_queue *cq)
	Initializes a thread local cache for cq. More...

GRPCAPI int	grpc_completion_queue_thread_local_cache_flush (grpc_completion_queue cq, void tag, int ok)
	Flushes the thread local cache for cq. More...

GRPCAPI grpc_connectivity_state	grpc_channel_check_connectivity_state (grpc_channel *channel, int try_to_connect)
	Check the connectivity state of a channel. More...

GRPCAPI int	grpc_channel_num_external_connectivity_watchers (grpc_channel *channel)
	Number of active "external connectivity state watchers" attached to a channel. More...

GRPCAPI void	grpc_channel_watch_connectivity_state (grpc_channel channel, grpc_connectivity_state last_observed_state, gpr_timespec deadline, grpc_completion_queue cq, void *tag)
	Watch for a change in connectivity state. More...

GRPCAPI int	grpc_channel_support_connectivity_watcher (grpc_channel *channel)
	Check whether a grpc channel supports connectivity watcher. More...

GRPCAPI grpc_call *	grpc_channel_create_call (grpc_channel channel, grpc_call parent_call, uint32_t propagation_mask, grpc_completion_queue completion_queue, grpc_slice method, const grpc_slice host, gpr_timespec deadline, void *reserved)
	Create a call given a grpc_channel, in order to call 'method'. More...

GRPCAPI void	grpc_channel_ping (grpc_channel channel, grpc_completion_queue cq, void tag, void reserved)
	Ping the channels peer (load balanced channels will select one sub-channel to ping); if the channel is not connected, posts a failed. More...

GRPCAPI void *	grpc_channel_register_call (grpc_channel channel, const char method, const char host, void reserved)
	Pre-register a method/host pair on a channel. More...

GRPCAPI grpc_call *	grpc_channel_create_registered_call (grpc_channel channel, grpc_call parent_call, uint32_t propagation_mask, grpc_completion_queue completion_queue, void registered_call_handle, gpr_timespec deadline, void *reserved)
	Create a call given a handle returned from grpc_channel_register_call. More...

GRPCAPI void *	grpc_call_arena_alloc (grpc_call *call, size_t size)
	Allocate memory in the grpc_call arena: this memory is automatically discarded at call completion. More...

GRPCAPI grpc_call_error	grpc_call_start_batch (grpc_call call, const grpc_op ops, size_t nops, void tag, void reserved)
	Start a batch of operations defined in the array ops; when complete, post a completion of type 'tag' to the completion queue bound to the call. More...

GRPCAPI char *	grpc_call_get_peer (grpc_call *call)
	Returns a newly allocated string representing the endpoint to which this call is communicating with. More...

GRPCAPI void	grpc_census_call_set_context (grpc_call call, struct census_context context)
	Set census context for a call; Must be called before first call to grpc_call_start_batch(). More...

GRPCAPI struct census_context *	grpc_census_call_get_context (grpc_call *call)
	Retrieve the calls current census context. More...

GRPCAPI char *	grpc_channel_get_target (grpc_channel *channel)
	Return a newly allocated string representing the target a channel was created for. More...

GRPCAPI void	grpc_channel_get_info (grpc_channel channel, const grpc_channel_info channel_info)
	Request info about the channel. More...

GRPCAPI void	grpc_channel_reset_connect_backoff (grpc_channel *channel)
	EXPERIMENTAL. More...

GRPCAPI grpc_channel *	grpc_insecure_channel_create (const char target, const grpc_channel_args args, void *reserved)
	Create a client channel to 'target'. More...

GRPCAPI grpc_channel *	grpc_lame_client_channel_create (const char target, grpc_status_code error_code, const char error_message)
	Create a lame client: this client fails every operation attempted on it. More...

GRPCAPI void	grpc_channel_destroy (grpc_channel *channel)
	Close and destroy a grpc channel. More...

GRPCAPI grpc_call_error	grpc_call_cancel (grpc_call call, void reserved)
	Error handling for grpc_call Most grpc_call functions return a grpc_error. More...

GRPCAPI grpc_call_error	grpc_call_cancel_with_status (grpc_call call, grpc_status_code status, const char description, void *reserved)
	Cancel an RPC. More...

GRPCAPI void	grpc_call_ref (grpc_call *call)
	Ref a call. More...

GRPCAPI void	grpc_call_unref (grpc_call *call)
	Unref a call. More...

GRPCAPI grpc_call_error	grpc_server_request_call (grpc_server server, grpc_call call, grpc_call_details details, grpc_metadata_array request_metadata, grpc_completion_queue cq_bound_to_call, grpc_completion_queue cq_for_notification, void tag_new)
	Request notification of a new call. More...

GRPCAPI void *	grpc_server_register_method (grpc_server server, const char method, const char *host, grpc_server_register_method_payload_handling payload_handling, uint32_t flags)
	Registers a method in the server. More...

GRPCAPI grpc_call_error	grpc_server_request_registered_call (grpc_server server, void registered_method, grpc_call *call, gpr_timespec deadline, grpc_metadata_array request_metadata, grpc_byte_buffer optional_payload, grpc_completion_queue cq_bound_to_call, grpc_completion_queue cq_for_notification, void tag_new)
	Request notification of a new pre-registered call. More...

GRPCAPI grpc_server *	grpc_server_create (const grpc_channel_args args, void reserved)
	Create a server. More...

GRPCAPI void	grpc_server_register_completion_queue (grpc_server server, grpc_completion_queue cq, void *reserved)
	Register a completion queue with the server. More...

GRPCAPI int	grpc_server_add_insecure_http2_port (grpc_server server, const char addr)
	Add a HTTP2 over plaintext over tcp listener. More...

GRPCAPI void	grpc_server_start (grpc_server *server)
	Start a server - tells all listeners to start listening. More...

GRPCAPI void	grpc_server_shutdown_and_notify (grpc_server server, grpc_completion_queue cq, void *tag)
	Begin shutting down a server. More...

GRPCAPI void	grpc_server_cancel_all_calls (grpc_server *server)
	Cancel all in-progress calls. More...

GRPCAPI void	grpc_server_destroy (grpc_server *server)
	Destroy a server. More...

GRPCAPI int	grpc_tracer_set_enabled (const char *name, int enabled)
	Enable or disable a tracer. More...

GRPCAPI int	grpc_header_key_is_legal (grpc_slice slice)
	Check whether a metadata key is legal (will be accepted by core) More...

GRPCAPI int	grpc_header_nonbin_value_is_legal (grpc_slice slice)
	Check whether a non-binary metadata value is legal (will be accepted by core) More...

GRPCAPI int	grpc_is_binary_header (grpc_slice slice)
	Check whether a metadata key corresponds to a binary value. More...

const GRPCAPI char *	grpc_call_error_to_string (grpc_call_error error)
	Convert grpc_call_error values to a string. More...

GRPCAPI grpc_resource_quota *	grpc_resource_quota_create (const char *trace_name)
	Create a buffer pool. More...

GRPCAPI void	grpc_resource_quota_ref (grpc_resource_quota *resource_quota)
	Add a reference to a buffer pool. More...

GRPCAPI void	grpc_resource_quota_unref (grpc_resource_quota *resource_quota)
	Drop a reference to a buffer pool. More...

GRPCAPI void	grpc_resource_quota_resize (grpc_resource_quota *resource_quota, size_t new_size)
	Update the size of a buffer pool. More...

GRPCAPI void	grpc_resource_quota_set_max_threads (grpc_resource_quota *resource_quota, int new_max_threads)
	Update the size of the maximum number of threads allowed. More...

const GRPCAPI grpc_arg_pointer_vtable *	grpc_resource_quota_arg_vtable (void)
	Fetch a vtable for a grpc_channel_arg that points to a grpc_resource_quota. More...

GRPCAPI char *	grpc_channelz_get_top_channels (intptr_t start_channel_id)
	Channelz is under active development. More...

GRPCAPI char *	grpc_channelz_get_servers (intptr_t start_server_id)

GRPCAPI char *	grpc_channelz_get_server (intptr_t server_id)

GRPCAPI char *	grpc_channelz_get_server_sockets (intptr_t server_id, intptr_t start_socket_id, intptr_t max_results)

GRPCAPI char *	grpc_channelz_get_channel (intptr_t channel_id)

GRPCAPI char *	grpc_channelz_get_subchannel (intptr_t subchannel_id)

GRPCAPI char *	grpc_channelz_get_socket (intptr_t socket_id)

Macro Definition Documentation

◆ GRPC_MAX_COMPLETION_QUEUE_PLUCKERS

#define GRPC_MAX_COMPLETION_QUEUE_PLUCKERS 6

Maximum number of outstanding grpc_completion_queue_pluck executions per completion queue.

Enumeration Type Documentation

◆ grpc_server_register_method_payload_handling

enum grpc_server_register_method_payload_handling

How to handle payloads for a registered method.

Enumerator
GRPC_SRM_PAYLOAD_NONE	Don't try to read the payload.
GRPC_SRM_PAYLOAD_READ_INITIAL_BYTE_BUFFER	Read the initial payload as a byte buffer.

Function Documentation

◆ grpc_call_arena_alloc()

GRPCAPI void* grpc_call_arena_alloc	(	grpc_call *	call,
		size_t	size
	)

Allocate memory in the grpc_call arena: this memory is automatically discarded at call completion.

◆ grpc_call_cancel()

GRPCAPI grpc_call_error grpc_call_cancel	(	grpc_call *	call,
		void *	reserved
	)

Error handling for grpc_call Most grpc_call functions return a grpc_error.

If the error is not GRPC_OK then the operation failed due to some unsatisfied precondition. If a grpc_call fails, it's guaranteed that no change to the call state has been made. Cancel an RPC. Can be called multiple times, from any thread. THREAD-SAFETY grpc_call_cancel and grpc_call_cancel_with_status are thread-safe, and can be called at any point before grpc_call_unref is called.

◆ grpc_call_cancel_with_status()

GRPCAPI grpc_call_error grpc_call_cancel_with_status	(	grpc_call *	call,
		grpc_status_code	status,
		const char *	description,
		void *	reserved
	)

Cancel an RPC.

Can be called multiple times, from any thread. If a status has not been received for the call, set it to the status code and description passed in. Importantly, this function does not send status nor description to the remote endpoint. Note that description doesn't need be a static string. It doesn't need to be alive after the call to grpc_call_cancel_with_status completes.

◆ grpc_call_details_destroy()

GRPCAPI void grpc_call_details_destroy ( grpc_call_details * details )

◆ grpc_call_details_init()

GRPCAPI void grpc_call_details_init ( grpc_call_details * details )

◆ grpc_call_error_to_string()

const GRPCAPI char* grpc_call_error_to_string ( grpc_call_error error )

Convert grpc_call_error values to a string.

◆ grpc_call_get_peer()

GRPCAPI char* grpc_call_get_peer ( grpc_call * call )

Returns a newly allocated string representing the endpoint to which this call is communicating with.

The string is in the uri format accepted by grpc_channel_create. The returned string should be disposed of with gpr_free().

WARNING: this value is never authenticated or subject to any security related code. It must not be used for any authentication related functionality. Instead, use grpc_auth_context.

◆ grpc_call_ref()

GRPCAPI void grpc_call_ref ( grpc_call * call )

Ref a call.

THREAD SAFETY: grpc_call_ref is thread-compatible

◆ grpc_call_start_batch()

GRPCAPI grpc_call_error grpc_call_start_batch	(	grpc_call *	call,
		const grpc_op *	ops,
		size_t	nops,
		void *	tag,
		void *	reserved
	)

Start a batch of operations defined in the array ops; when complete, post a completion of type 'tag' to the completion queue bound to the call.

The order of ops specified in the batch has no significance. Only one operation of each type can be active at once in any given batch. If a call to grpc_call_start_batch returns GRPC_CALL_OK you must call grpc_completion_queue_next or grpc_completion_queue_pluck on the completion queue associated with 'call' for work to be performed. If a call to grpc_call_start_batch returns any value other than GRPC_CALL_OK it is guaranteed that no state associated with 'call' is changed and it is not appropriate to call grpc_completion_queue_next or grpc_completion_queue_pluck consequent to the failed grpc_call_start_batch call. If a call to grpc_call_start_batch with an empty batch returns GRPC_CALL_OK, the tag is put in the completion queue immediately. THREAD SAFETY: access to grpc_call_start_batch in multi-threaded environment needs to be synchronized. As an optimization, you may synchronize batches containing just send operations independently from batches containing just receive operations. Access to grpc_call_start_batch with an empty batch is thread-compatible.

◆ grpc_call_unref()

GRPCAPI void grpc_call_unref ( grpc_call * call )

Unref a call.

THREAD SAFETY: grpc_call_unref is thread-compatible

◆ grpc_census_call_get_context()

GRPCAPI struct census_context* grpc_census_call_get_context ( grpc_call * call )

Retrieve the calls current census context.

◆ grpc_census_call_set_context()

GRPCAPI void grpc_census_call_set_context	(	grpc_call *	call,
		struct census_context *	context
	)

Set census context for a call; Must be called before first call to grpc_call_start_batch().

◆ grpc_channel_check_connectivity_state()

GRPCAPI grpc_connectivity_state grpc_channel_check_connectivity_state	(	grpc_channel *	channel,
		int	try_to_connect
	)

Check the connectivity state of a channel.

◆ grpc_channel_create_call()

GRPCAPI grpc_call* grpc_channel_create_call	(	grpc_channel *	channel,
		grpc_call *	parent_call,
		uint32_t	propagation_mask,
		grpc_completion_queue *	completion_queue,
		grpc_slice	method,
		const grpc_slice *	host,
		gpr_timespec	deadline,
		void *	reserved
	)

Create a call given a grpc_channel, in order to call 'method'.

All completions are sent to 'completion_queue'. 'method' and 'host' need only live through the invocation of this function. If parent_call is non-NULL, it must be a server-side call. It will be used to propagate properties from the server call to this new client call, depending on the value of propagation_mask (see propagation_bits.h for possible values).

◆ grpc_channel_create_registered_call()

GRPCAPI grpc_call* grpc_channel_create_registered_call	(	grpc_channel *	channel,
		grpc_call *	parent_call,
		uint32_t	propagation_mask,
		grpc_completion_queue *	completion_queue,
		void *	registered_call_handle,
		gpr_timespec	deadline,
		void *	reserved
	)

Create a call given a handle returned from grpc_channel_register_call.

See also: grpc_channel_create_call.

◆ grpc_channel_destroy()

GRPCAPI void grpc_channel_destroy ( grpc_channel * channel )

Close and destroy a grpc channel.

◆ grpc_channel_get_info()

GRPCAPI void grpc_channel_get_info	(	grpc_channel *	channel,
		const grpc_channel_info *	channel_info
	)

Request info about the channel.

channel_info indicates what information is being requested and how that information will be returned. channel_info is owned by the caller.

◆ grpc_channel_get_target()

GRPCAPI char* grpc_channel_get_target ( grpc_channel * channel )

Return a newly allocated string representing the target a channel was created for.

◆ grpc_channel_num_external_connectivity_watchers()

GRPCAPI int grpc_channel_num_external_connectivity_watchers ( grpc_channel * channel )

Number of active "external connectivity state watchers" attached to a channel.

Useful for testing.

◆ grpc_channel_ping()

GRPCAPI void grpc_channel_ping	(	grpc_channel *	channel,
		grpc_completion_queue *	cq,
		void *	tag,
		void *	reserved
	)

Ping the channels peer (load balanced channels will select one sub-channel to ping); if the channel is not connected, posts a failed.

◆ grpc_channel_register_call()

GRPCAPI void* grpc_channel_register_call	(	grpc_channel *	channel,
		const char *	method,
		const char *	host,
		void *	reserved
	)

Pre-register a method/host pair on a channel.

method and host are not owned and must remain alive while the channel is alive.

◆ grpc_channel_reset_connect_backoff()

GRPCAPI void grpc_channel_reset_connect_backoff ( grpc_channel * channel )

EXPERIMENTAL.

Resets the channel's connect backoff. TODO(roth): When we see whether this proves useful, either promote to non-experimental or remove it.

◆ grpc_channel_support_connectivity_watcher()

GRPCAPI int grpc_channel_support_connectivity_watcher ( grpc_channel * channel )

Check whether a grpc channel supports connectivity watcher.

◆ grpc_channel_watch_connectivity_state()

GRPCAPI void grpc_channel_watch_connectivity_state	(	grpc_channel *	channel,
		grpc_connectivity_state	last_observed_state,
		gpr_timespec	deadline,
		grpc_completion_queue *	cq,
		void *	tag
	)

Watch for a change in connectivity state.

Once the channel connectivity state is different from last_observed_state, tag will be enqueued on cq with success=1. If deadline expires BEFORE the state is changed, tag will be enqueued on cq with success=0.

◆ grpc_channelz_get_channel()

GRPCAPI char* grpc_channelz_get_channel ( intptr_t channel_id )

◆ grpc_channelz_get_server()

GRPCAPI char* grpc_channelz_get_server ( intptr_t server_id )

◆ grpc_channelz_get_server_sockets()

GRPCAPI char* grpc_channelz_get_server_sockets	(	intptr_t	server_id,
		intptr_t	start_socket_id,
		intptr_t	max_results
	)

◆ grpc_channelz_get_servers()

GRPCAPI char* grpc_channelz_get_servers ( intptr_t start_server_id )

◆ grpc_channelz_get_socket()

GRPCAPI char* grpc_channelz_get_socket ( intptr_t socket_id )

◆ grpc_channelz_get_subchannel()

GRPCAPI char* grpc_channelz_get_subchannel ( intptr_t subchannel_id )

◆ grpc_channelz_get_top_channels()

GRPCAPI char* grpc_channelz_get_top_channels ( intptr_t start_channel_id )

Channelz is under active development.

The following APIs will see some churn as the feature is implemented. This comment will be removed once channelz is officially supported, and these APIs become stable. For now you may track the progress by following this github issue: https://github.com/grpc/grpc/issues/15340

the following APIs return allocated JSON strings that match the response objects from the channelz proto, found here: https://github.com/grpc/grpc/blob/master/src/proto/grpc/channelz/channelz.proto.

For easy conversion to protobuf, The JSON is formatted according to: https://developers.google.com/protocol-buffers/docs/proto3#json.

◆ grpc_completion_queue_create()

GRPCAPI grpc_completion_queue* grpc_completion_queue_create	(	const grpc_completion_queue_factory *	factory,
		const grpc_completion_queue_attributes *	attributes,
		void *	reserved
	)

Create a completion queue.

◆ grpc_completion_queue_create_for_callback()

GRPCAPI grpc_completion_queue* grpc_completion_queue_create_for_callback	(	grpc_experimental_completion_queue_functor *	shutdown_callback,
		void *	reserved
	)

Helper function to create a completion queue with grpc_cq_completion_type of GRPC_CQ_CALLBACK and grpc_cq_polling_type of GRPC_CQ_DEFAULT_POLLING.

This function is experimental.

◆ grpc_completion_queue_create_for_next()

GRPCAPI grpc_completion_queue* grpc_completion_queue_create_for_next ( void * reserved )

Helper function to create a completion queue with grpc_cq_completion_type of GRPC_CQ_NEXT and grpc_cq_polling_type of GRPC_CQ_DEFAULT_POLLING.

◆ grpc_completion_queue_create_for_pluck()

GRPCAPI grpc_completion_queue* grpc_completion_queue_create_for_pluck ( void * reserved )

Helper function to create a completion queue with grpc_cq_completion_type of GRPC_CQ_PLUCK and grpc_cq_polling_type of GRPC_CQ_DEFAULT_POLLING.

◆ grpc_completion_queue_destroy()

GRPCAPI void grpc_completion_queue_destroy ( grpc_completion_queue * cq )

Destroy a completion queue.

The caller must ensure that the queue is drained and no threads are executing grpc_completion_queue_next

◆ grpc_completion_queue_factory_lookup()

const GRPCAPI grpc_completion_queue_factory* grpc_completion_queue_factory_lookup ( const grpc_completion_queue_attributes * attributes )

Returns the completion queue factory based on the attributes.

MAY return a NULL if no factory can be found

◆ grpc_completion_queue_next()

GRPCAPI grpc_event grpc_completion_queue_next	(	grpc_completion_queue *	cq,
		gpr_timespec	deadline,
		void *	reserved
	)

Blocks until an event is available, the completion queue is being shut down, or deadline is reached.

Returns a grpc_event with type GRPC_QUEUE_TIMEOUT on timeout, otherwise a grpc_event describing the event that occurred.

Callers must not call grpc_completion_queue_next and grpc_completion_queue_pluck simultaneously on the same completion queue.

◆ grpc_completion_queue_pluck()

GRPCAPI grpc_event grpc_completion_queue_pluck	(	grpc_completion_queue *	cq,
		void *	tag,
		gpr_timespec	deadline,
		void *	reserved
	)

Blocks until an event with tag 'tag' is available, the completion queue is being shutdown or deadline is reached.

Returns a grpc_event with type GRPC_QUEUE_TIMEOUT on timeout, otherwise a grpc_event describing the event that occurred.

Callers must not call grpc_completion_queue_next and grpc_completion_queue_pluck simultaneously on the same completion queue.

Completion queues support a maximum of GRPC_MAX_COMPLETION_QUEUE_PLUCKERS concurrently executing plucks at any time.

◆ grpc_completion_queue_shutdown()

GRPCAPI void grpc_completion_queue_shutdown ( grpc_completion_queue * cq )

Begin destruction of a completion queue.

Once all possible events are drained then grpc_completion_queue_next will start to produce GRPC_QUEUE_SHUTDOWN events only. At that point it's safe to call grpc_completion_queue_destroy.

After calling this function applications should ensure that no NEW work is added to be published on this completion queue.

◆ grpc_completion_queue_thread_local_cache_flush()

GRPCAPI int grpc_completion_queue_thread_local_cache_flush	(	grpc_completion_queue *	cq,
		void **	tag,
		int *	ok
	)

Flushes the thread local cache for cq.

Returns 1 if there was contents in the cache. If there was an event in cq tls cache, its tag is placed in tag, and ok is set to the event success.

◆ grpc_completion_queue_thread_local_cache_init()

GRPCAPI void grpc_completion_queue_thread_local_cache_init ( grpc_completion_queue * cq )

Initializes a thread local cache for cq.

grpc_flush_cq_tls_cache() MUST be called on the same thread, with the same cq.

◆ grpc_g_stands_for()

const GRPCAPI char* grpc_g_stands_for ( void )

Return a string specifying what the 'g' in gRPC stands for.

◆ grpc_header_key_is_legal()

GRPCAPI int grpc_header_key_is_legal ( grpc_slice slice )

Check whether a metadata key is legal (will be accepted by core)

◆ grpc_header_nonbin_value_is_legal()

GRPCAPI int grpc_header_nonbin_value_is_legal ( grpc_slice slice )

Check whether a non-binary metadata value is legal (will be accepted by core)

◆ grpc_init()

GRPCAPI void grpc_init ( void )

Initialize the grpc library.

After it's called, a matching invocation to grpc_shutdown() is expected.

It is not safe to call any other grpc functions before calling this. (To avoid overhead, little checking is done, and some things may work. We do not warrant that they will continue to do so in future revisions of this library).

◆ grpc_insecure_channel_create()

GRPCAPI grpc_channel* grpc_insecure_channel_create	(	const char *	target,
		const grpc_channel_args *	args,
		void *	reserved
	)

Create a client channel to 'target'.

Additional channel level configuration MAY be provided by grpc_channel_args, though the expectation is that most clients will want to simply pass NULL. The user data in 'args' need only live through the invocation of this function. However, if any args of the 'pointer' type are passed, then the referenced vtable must be maintained by the caller until grpc_channel_destroy terminates. See grpc_channel_args definition for more on this.

◆ grpc_is_binary_header()

GRPCAPI int grpc_is_binary_header ( grpc_slice slice )

Check whether a metadata key corresponds to a binary value.

◆ grpc_is_initialized()

GRPCAPI int grpc_is_initialized ( void )

EXPERIMENTAL.

Returns 1 if the grpc library has been initialized. TODO(ericgribkoff) Decide if this should be promoted to non-experimental as part of stabilizing the fork support API, as tracked in https://github.com/grpc/grpc/issues/15334

◆ grpc_lame_client_channel_create()

GRPCAPI grpc_channel* grpc_lame_client_channel_create	(	const char *	target,
		grpc_status_code	error_code,
		const char *	error_message
	)

Create a lame client: this client fails every operation attempted on it.

◆ grpc_metadata_array_destroy()

GRPCAPI void grpc_metadata_array_destroy ( grpc_metadata_array * array )

◆ grpc_metadata_array_init()

GRPCAPI void grpc_metadata_array_init ( grpc_metadata_array * array )

◆ grpc_register_plugin()

GRPCAPI void grpc_register_plugin	(	void(*)(void)	init,
		void(*)(void)	destroy
	)

Registers a plugin to be initialized and destroyed with the library.

The init and destroy functions will be invoked as part of grpc_init() and grpc_shutdown(), respectively. Note that these functions can be invoked an arbitrary number of times (and hence so will init and destroy). It is safe to pass NULL to either argument. Plugins are destroyed in the reverse order they were initialized.

◆ grpc_resource_quota_arg_vtable()

const GRPCAPI grpc_arg_pointer_vtable* grpc_resource_quota_arg_vtable ( void )

Fetch a vtable for a grpc_channel_arg that points to a grpc_resource_quota.

◆ grpc_resource_quota_create()

GRPCAPI grpc_resource_quota* grpc_resource_quota_create ( const char * trace_name )

Create a buffer pool.

◆ grpc_resource_quota_ref()

GRPCAPI void grpc_resource_quota_ref ( grpc_resource_quota * resource_quota )

Add a reference to a buffer pool.

◆ grpc_resource_quota_resize()

GRPCAPI void grpc_resource_quota_resize	(	grpc_resource_quota *	resource_quota,
		size_t	new_size
	)

Update the size of a buffer pool.

◆ grpc_resource_quota_set_max_threads()

GRPCAPI void grpc_resource_quota_set_max_threads	(	grpc_resource_quota *	resource_quota,
		int	new_max_threads
	)

Update the size of the maximum number of threads allowed.

◆ grpc_resource_quota_unref()

GRPCAPI void grpc_resource_quota_unref ( grpc_resource_quota * resource_quota )

Drop a reference to a buffer pool.

◆ grpc_server_add_insecure_http2_port()

GRPCAPI int grpc_server_add_insecure_http2_port	(	grpc_server *	server,
		const char *	addr
	)

Add a HTTP2 over plaintext over tcp listener.

Returns bound port number on success, 0 on failure. REQUIRES: server not started

◆ grpc_server_cancel_all_calls()

GRPCAPI void grpc_server_cancel_all_calls ( grpc_server * server )

Cancel all in-progress calls.

Only usable after shutdown.

◆ grpc_server_create()

GRPCAPI grpc_server* grpc_server_create	(	const grpc_channel_args *	args,
		void *	reserved
	)

Create a server.

Additional configuration for each incoming channel can be specified with args. If no additional configuration is needed, args can be NULL. The user data in 'args' need only live through the invocation of this function. However, if any args of the 'pointer' type are passed, then the referenced vtable must be maintained by the caller until grpc_server_destroy terminates. See grpc_channel_args definition for more on this.

◆ grpc_server_destroy()

GRPCAPI void grpc_server_destroy ( grpc_server * server )

Destroy a server.

Shutdown must have completed beforehand (i.e. all tags generated by grpc_server_shutdown_and_notify must have been received, and at least one call to grpc_server_shutdown_and_notify must have been made).

◆ grpc_server_register_completion_queue()

GRPCAPI void grpc_server_register_completion_queue	(	grpc_server *	server,
		grpc_completion_queue *	cq,
		void *	reserved
	)

Register a completion queue with the server.

Must be done for any notification completion queue that is passed to grpc_server_request_*_call and to grpc_server_shutdown_and_notify. Must be performed prior to grpc_server_start.

◆ grpc_server_register_method()

GRPCAPI void* grpc_server_register_method	(	grpc_server *	server,
		const char *	method,
		const char *	host,
		grpc_server_register_method_payload_handling	payload_handling,
		uint32_t	flags
	)

Registers a method in the server.

Methods to this (host, method) pair will not be reported by grpc_server_request_call, but instead be reported by grpc_server_request_registered_call when passed the appropriate registered_method (as returned by this function). Must be called before grpc_server_start. Returns NULL on failure.

◆ grpc_server_request_call()

GRPCAPI grpc_call_error grpc_server_request_call	(	grpc_server *	server,
		grpc_call **	call,
		grpc_call_details *	details,
		grpc_metadata_array *	request_metadata,
		grpc_completion_queue *	cq_bound_to_call,
		grpc_completion_queue *	cq_for_notification,
		void *	tag_new
	)

Request notification of a new call.

Once a call is received, a notification tagged with tag_new is added to cq_for_notification. call, details and request_metadata are updated with the appropriate call information. cq_bound_to_call is bound to call, and batch operation notifications for that call will be posted to cq_bound_to_call. Note that cq_for_notification must have been registered to the server via grpc_server_register_completion_queue.

◆ grpc_server_request_registered_call()

GRPCAPI grpc_call_error grpc_server_request_registered_call	(	grpc_server *	server,
		void *	registered_method,
		grpc_call **	call,
		gpr_timespec *	deadline,
		grpc_metadata_array *	request_metadata,
		grpc_byte_buffer **	optional_payload,
		grpc_completion_queue *	cq_bound_to_call,
		grpc_completion_queue *	cq_for_notification,
		void *	tag_new
	)

Request notification of a new pre-registered call.

'cq_for_notification' must have been registered to the server via grpc_server_register_completion_queue.

◆ grpc_server_shutdown_and_notify()

GRPCAPI void grpc_server_shutdown_and_notify	(	grpc_server *	server,
		grpc_completion_queue *	cq,
		void *	tag
	)

Begin shutting down a server.

After completion, no new calls or connections will be admitted. Existing calls will be allowed to complete. Send a GRPC_OP_COMPLETE event when there are no more calls being serviced. Shutdown is idempotent, and all tags will be notified at once if multiple grpc_server_shutdown_and_notify calls are made. 'cq' must have been registered to this server via grpc_server_register_completion_queue.

◆ grpc_server_start()

GRPCAPI void grpc_server_start ( grpc_server * server )

Start a server - tells all listeners to start listening.

◆ grpc_shutdown()

GRPCAPI void grpc_shutdown ( void )

Shut down the grpc library.

Before it's called, there should haven been a matching invocation to grpc_init().

The last call to grpc_shutdown will initiate cleaning up of grpc library internals, which can happen in another thread. Once the clean-up is done, no memory is used by grpc, nor are any instructions executing within the grpc library. Prior to calling, all application owned grpc objects must have been destroyed.

◆ grpc_shutdown_blocking()

GRPCAPI void grpc_shutdown_blocking ( void )

EXPERIMENTAL.

Blocking shut down grpc library. This is only for wrapped language to use now.

◆ grpc_tracer_set_enabled()

GRPCAPI int grpc_tracer_set_enabled	(	const char *	name,
		int	enabled
	)

Enable or disable a tracer.

Tracers (usually controlled by the environment variable GRPC_TRACE) allow printf-style debugging on GRPC internals, and are useful for tracking down problems in the field.

Use of this function is not strictly thread-safe, but the thread-safety issues raised by it should not be of concern.

◆ grpc_version_string()

const GRPCAPI char* grpc_version_string ( void )

Return a string representing the current version of grpc.

Macros

Enumerations

Functions

Macro Definition Documentation

◆ GRPC_MAX_COMPLETION_QUEUE_PLUCKERS

Enumeration Type Documentation

◆ grpc_server_register_method_payload_handling

Function Documentation

◆ grpc_call_arena_alloc()

◆ grpc_call_cancel()

◆ grpc_call_cancel_with_status()

◆ grpc_call_details_destroy()

◆ grpc_call_details_init()

◆ grpc_call_error_to_string()

◆ grpc_call_get_peer()

◆ grpc_call_ref()

◆ grpc_call_start_batch()

◆ grpc_call_unref()

◆ grpc_census_call_get_context()

◆ grpc_census_call_set_context()

◆ grpc_channel_check_connectivity_state()

◆ grpc_channel_create_call()

◆ grpc_channel_create_registered_call()

◆ grpc_channel_destroy()

◆ grpc_channel_get_info()

◆ grpc_channel_get_target()

◆ grpc_channel_num_external_connectivity_watchers()

◆ grpc_channel_ping()

◆ grpc_channel_register_call()

◆ grpc_channel_reset_connect_backoff()

◆ grpc_channel_support_connectivity_watcher()

◆ grpc_channel_watch_connectivity_state()

◆ grpc_channelz_get_channel()

◆ grpc_channelz_get_server()

◆ grpc_channelz_get_server_sockets()

◆ grpc_channelz_get_servers()

◆ grpc_channelz_get_socket()

◆ grpc_channelz_get_subchannel()

◆ grpc_channelz_get_top_channels()

◆ grpc_completion_queue_create()

◆ grpc_completion_queue_create_for_callback()

◆ grpc_completion_queue_create_for_next()

◆ grpc_completion_queue_create_for_pluck()

◆ grpc_completion_queue_destroy()

◆ grpc_completion_queue_factory_lookup()

◆ grpc_completion_queue_next()

◆ grpc_completion_queue_pluck()

◆ grpc_completion_queue_shutdown()

◆ grpc_completion_queue_thread_local_cache_flush()

◆ grpc_completion_queue_thread_local_cache_init()

◆ grpc_g_stands_for()

◆ grpc_header_key_is_legal()

◆ grpc_header_nonbin_value_is_legal()

◆ grpc_init()

◆ grpc_insecure_channel_create()

◆ grpc_is_binary_header()

◆ grpc_is_initialized()

◆ grpc_lame_client_channel_create()

◆ grpc_metadata_array_destroy()

◆ grpc_metadata_array_init()

◆ grpc_register_plugin()

◆ grpc_resource_quota_arg_vtable()

◆ grpc_resource_quota_create()

◆ grpc_resource_quota_ref()

◆ grpc_resource_quota_resize()

◆ grpc_resource_quota_set_max_threads()

◆ grpc_resource_quota_unref()

◆ grpc_server_add_insecure_http2_port()

◆ grpc_server_cancel_all_calls()

◆ grpc_server_create()

◆ grpc_server_destroy()

◆ grpc_server_register_completion_queue()

◆ grpc_server_register_method()

◆ grpc_server_request_call()

◆ grpc_server_request_registered_call()

◆ grpc_server_shutdown_and_notify()

◆ grpc_server_start()

◆ grpc_shutdown()

◆ grpc_shutdown_blocking()

◆ grpc_tracer_set_enabled()