Skip to content
Snippets Groups Projects
Commit aabf72c2 authored by Nicolas Noble's avatar Nicolas Noble
Browse files

Merge pull request #2551 from ctiller/markup-the-things 

Mark up all existing comments in grpc.h for Doxygen, add main page
parents 7a68b291 2d984bf2
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 196 additions and 192 deletions
include/grpc/grpc.h
+ 196
− 192
View file @ aabf72c2
...@@ -45,40 +45,49 @@ ...@@ -45,40 +45,49 @@
extern "C" { extern "C" {
#endif #endif
/* Completion Queues enable notification of the completion of asynchronous /*! \mainpage GRPC Core
actions. */ *
* \section intro_sec The GRPC Core library is a low-level library designed
* to be wrapped by higher level libraries.
*
* The top-level API is provided in grpc.h.
* Security related functionality lives in grpc_security.h.
*/
/** Completion Queues enable notification of the completion of asynchronous
actions. */
typedef struct grpc_completion_queue grpc_completion_queue; typedef struct grpc_completion_queue grpc_completion_queue;
/* The Channel interface allows creation of Call objects. */ /** The Channel interface allows creation of Call objects. */
typedef struct grpc_channel grpc_channel; typedef struct grpc_channel grpc_channel;
/* A server listens to some port and responds to request calls */ /** A server listens to some port and responds to request calls */
typedef struct grpc_server grpc_server; typedef struct grpc_server grpc_server;
/* A Call represents an RPC. When created, it is in a configuration state /** A Call represents an RPC. When created, it is in a configuration state
allowing properties to be set until it is invoked. After invoke, the Call allowing properties to be set until it is invoked. After invoke, the Call
can have messages written to it and read from it. */ can have messages written to it and read from it. */
typedef struct grpc_call grpc_call; typedef struct grpc_call grpc_call;
/* Type specifier for grpc_arg */ /** Type specifier for grpc_arg */
typedef enum { typedef enum {
GRPC_ARG_STRING, GRPC_ARG_STRING,
GRPC_ARG_INTEGER, GRPC_ARG_INTEGER,
GRPC_ARG_POINTER GRPC_ARG_POINTER
} grpc_arg_type; } grpc_arg_type;
/* A single argument... each argument has a key and a value /** A single argument... each argument has a key and a value
A note on naming keys: A note on naming keys:
Keys are namespaced into groups, usually grouped by library, and are Keys are namespaced into groups, usually grouped by library, and are
keys for module XYZ are named XYZ.key1, XYZ.key2, etc. Module names must keys for module XYZ are named XYZ.key1, XYZ.key2, etc. Module names must
be restricted to the regex [A-Za-z][_A-Za-z0-9]{,15}. be restricted to the regex [A-Za-z][_A-Za-z0-9]{,15}.
Key names must be restricted to the regex [A-Za-z][_A-Za-z0-9]{,47}. Key names must be restricted to the regex [A-Za-z][_A-Za-z0-9]{,47}.
GRPC core library keys are prefixed by grpc. GRPC core library keys are prefixed by grpc.
Library authors are strongly encouraged to #define symbolic constants for Library authors are strongly encouraged to \#define symbolic constants for
their keys so that it's possible to change them in the future. */ their keys so that it's possible to change them in the future. */
typedef struct { typedef struct {
grpc_arg_type type; grpc_arg_type type;
char *key; char *key;
...@@ -107,14 +116,14 @@ typedef struct { ...@@ -107,14 +116,14 @@ typedef struct {
} grpc_channel_args; } grpc_channel_args;
/* Channel argument keys: */ /* Channel argument keys: */
/* Enable census for tracing and stats collection */ /** Enable census for tracing and stats collection */
#define GRPC_ARG_ENABLE_CENSUS "grpc.census" #define GRPC_ARG_ENABLE_CENSUS "grpc.census"
/* Maximum number of concurrent incoming streams to allow on a http2 /** Maximum number of concurrent incoming streams to allow on a http2
connection */ connection */
#define GRPC_ARG_MAX_CONCURRENT_STREAMS "grpc.max_concurrent_streams" #define GRPC_ARG_MAX_CONCURRENT_STREAMS "grpc.max_concurrent_streams"
/* Maximum message length that the channel can receive */ /** Maximum message length that the channel can receive */
#define GRPC_ARG_MAX_MESSAGE_LENGTH "grpc.max_message_length" #define GRPC_ARG_MAX_MESSAGE_LENGTH "grpc.max_message_length"
/* Initial sequence number for http2 transports */ /** Initial sequence number for http2 transports */
#define GRPC_ARG_HTTP2_INITIAL_SEQUENCE_NUMBER \ #define GRPC_ARG_HTTP2_INITIAL_SEQUENCE_NUMBER \
"grpc.http2.initial_sequence_number" "grpc.http2.initial_sequence_number"
...@@ -132,59 +141,59 @@ typedef enum { ...@@ -132,59 +141,59 @@ typedef enum {
GRPC_CHANNEL_FATAL_FAILURE GRPC_CHANNEL_FATAL_FAILURE
} grpc_connectivity_state; } grpc_connectivity_state;
/* Result of a grpc call. If the caller satisfies the prerequisites of a /** Result of a grpc call. If the caller satisfies the prerequisites of a
particular operation, the grpc_call_error returned will be GRPC_CALL_OK. particular operation, the grpc_call_error returned will be GRPC_CALL_OK.
Receiving any other value listed here is an indication of a bug in the Receiving any other value listed here is an indication of a bug in the
caller. */ caller. */
typedef enum grpc_call_error { typedef enum grpc_call_error {
/* everything went ok */ /** everything went ok */
GRPC_CALL_OK = 0, GRPC_CALL_OK = 0,
/* something failed, we don't know what */ /** something failed, we don't know what */
GRPC_CALL_ERROR, GRPC_CALL_ERROR,
/* this method is not available on the server */ /** this method is not available on the server */
GRPC_CALL_ERROR_NOT_ON_SERVER, GRPC_CALL_ERROR_NOT_ON_SERVER,
/* this method is not available on the client */ /** this method is not available on the client */
GRPC_CALL_ERROR_NOT_ON_CLIENT, GRPC_CALL_ERROR_NOT_ON_CLIENT,
/* this method must be called before server_accept */ /** this method must be called before server_accept */
GRPC_CALL_ERROR_ALREADY_ACCEPTED, GRPC_CALL_ERROR_ALREADY_ACCEPTED,
/* this method must be called before invoke */ /** this method must be called before invoke */
GRPC_CALL_ERROR_ALREADY_INVOKED, GRPC_CALL_ERROR_ALREADY_INVOKED,
/* this method must be called after invoke */ /** this method must be called after invoke */
GRPC_CALL_ERROR_NOT_INVOKED, GRPC_CALL_ERROR_NOT_INVOKED,
/* this call is already finished /** this call is already finished
(writes_done or write_status has already been called) */ (writes_done or write_status has already been called) */
GRPC_CALL_ERROR_ALREADY_FINISHED, GRPC_CALL_ERROR_ALREADY_FINISHED,
/* there is already an outstanding read/write operation on the call */ /** there is already an outstanding read/write operation on the call */
GRPC_CALL_ERROR_TOO_MANY_OPERATIONS, GRPC_CALL_ERROR_TOO_MANY_OPERATIONS,
/* the flags value was illegal for this call */ /** the flags value was illegal for this call */
GRPC_CALL_ERROR_INVALID_FLAGS, GRPC_CALL_ERROR_INVALID_FLAGS,
/* invalid metadata was passed to this call */ /** invalid metadata was passed to this call */
GRPC_CALL_ERROR_INVALID_METADATA, GRPC_CALL_ERROR_INVALID_METADATA,
/* completion queue for notification has not been registered with the server /** completion queue for notification has not been registered with the
*/ server */
GRPC_CALL_ERROR_NOT_SERVER_COMPLETION_QUEUE GRPC_CALL_ERROR_NOT_SERVER_COMPLETION_QUEUE
} grpc_call_error; } grpc_call_error;
/* Write Flags: */ /* Write Flags: */
/* Hint that the write may be buffered and need not go out on the wire /** Hint that the write may be buffered and need not go out on the wire
immediately. GRPC is free to buffer the message until the next non-buffered immediately. GRPC is free to buffer the message until the next non-buffered
write, or until writes_done, but it need not buffer completely or at all. */ write, or until writes_done, but it need not buffer completely or at all. */
#define GRPC_WRITE_BUFFER_HINT (0x00000001u) #define GRPC_WRITE_BUFFER_HINT (0x00000001u)
/* Force compression to be disabled for a particular write /** Force compression to be disabled for a particular write
(start_write/add_metadata). Illegal on invoke/accept. */ (start_write/add_metadata). Illegal on invoke/accept. */
#define GRPC_WRITE_NO_COMPRESS (0x00000002u) #define GRPC_WRITE_NO_COMPRESS (0x00000002u)
/* Mask of all valid flags. */ /** Mask of all valid flags. */
#define GRPC_WRITE_USED_MASK (GRPC_WRITE_BUFFER_HINT | GRPC_WRITE_NO_COMPRESS) #define GRPC_WRITE_USED_MASK (GRPC_WRITE_BUFFER_HINT | GRPC_WRITE_NO_COMPRESS)
/* A single metadata element */ /** A single metadata element */
typedef struct grpc_metadata { typedef struct grpc_metadata {
const char *key; const char *key;
const char *value; const char *value;
size_t value_length; size_t value_length;
/* The following fields are reserved for grpc internal use. /** The following fields are reserved for grpc internal use.
There is no need to initialize them, and they will be set to garbage during There is no need to initialize them, and they will be set to garbage during
calls to grpc. */ calls to grpc. */
struct { struct {
void *obfuscated[3]; void *obfuscated[3];
} internal_data; } internal_data;
...@@ -235,42 +244,41 @@ void grpc_call_details_init(grpc_call_details *details); ...@@ -235,42 +244,41 @@ void grpc_call_details_init(grpc_call_details *details);
void grpc_call_details_destroy(grpc_call_details *details); void grpc_call_details_destroy(grpc_call_details *details);
typedef enum { typedef enum {
/* Send initial metadata: one and only one instance MUST be sent for each /** Send initial metadata: one and only one instance MUST be sent for each
call, call, unless the call was cancelled - in which case this can be skipped */
unless the call was cancelled - in which case this can be skipped */
GRPC_OP_SEND_INITIAL_METADATA = 0, GRPC_OP_SEND_INITIAL_METADATA = 0,
/* Send a message: 0 or more of these operations can occur for each call */ /** Send a message: 0 or more of these operations can occur for each call */
GRPC_OP_SEND_MESSAGE, GRPC_OP_SEND_MESSAGE,
/* Send a close from the client: one and only one instance MUST be sent from /** Send a close from the client: one and only one instance MUST be sent from
the client, the client, unless the call was cancelled - in which case this can be
unless the call was cancelled - in which case this can be skipped */ skipped */
GRPC_OP_SEND_CLOSE_FROM_CLIENT, GRPC_OP_SEND_CLOSE_FROM_CLIENT,
/* Send status from the server: one and only one instance MUST be sent from /** Send status from the server: one and only one instance MUST be sent from
the server the server unless the call was cancelled - in which case this can be
unless the call was cancelled - in which case this can be skipped */ skipped */
GRPC_OP_SEND_STATUS_FROM_SERVER, GRPC_OP_SEND_STATUS_FROM_SERVER,
/* Receive initial metadata: one and only one MUST be made on the client, must /** Receive initial metadata: one and only one MUST be made on the client,
not be made on the server */ must not be made on the server */
GRPC_OP_RECV_INITIAL_METADATA, GRPC_OP_RECV_INITIAL_METADATA,
/* Receive a message: 0 or more of these operations can occur for each call */ /** Receive a message: 0 or more of these operations can occur for each call */
GRPC_OP_RECV_MESSAGE, GRPC_OP_RECV_MESSAGE,
/* Receive status on the client: one and only one must be made on the client. /** Receive status on the client: one and only one must be made on the client.
This operation always succeeds, meaning ops paired with this operation This operation always succeeds, meaning ops paired with this operation
will also appear to succeed, even though they may not have. In that case will also appear to succeed, even though they may not have. In that case
the status will indicate some failure. the status will indicate some failure. */
*/
GRPC_OP_RECV_STATUS_ON_CLIENT, GRPC_OP_RECV_STATUS_ON_CLIENT,
/* Receive close on the server: one and only one must be made on the server /** Receive close on the server: one and only one must be made on the
*/ server */
GRPC_OP_RECV_CLOSE_ON_SERVER GRPC_OP_RECV_CLOSE_ON_SERVER
} grpc_op_type; } grpc_op_type;
/* Operation data: one field for each op type (except SEND_CLOSE_FROM_CLIENT /** Operation data: one field for each op type (except SEND_CLOSE_FROM_CLIENT
which has which has no arguments) */
no arguments) */
typedef struct grpc_op { typedef struct grpc_op {
/** Operation type, as defined by grpc_op_type */
grpc_op_type op; grpc_op_type op;
gpr_uint32 flags; /**< Write flags bitset for grpc_begin_messages */ /** Write flags bitset for grpc_begin_messages */
gpr_uint32 flags;
union { union {
struct { struct {
size_t count; size_t count;
...@@ -283,53 +291,49 @@ typedef struct grpc_op { ...@@ -283,53 +291,49 @@ typedef struct grpc_op {
grpc_status_code status; grpc_status_code status;
const char *status_details; const char *status_details;
} send_status_from_server; } send_status_from_server;
/* ownership of the array is with the caller, but ownership of the elements /** ownership of the array is with the caller, but ownership of the elements
stays with the call object (ie key, value members are owned by the call stays with the call object (ie key, value members are owned by the call
object, recv_initial_metadata->array is owned by the caller). object, recv_initial_metadata->array is owned by the caller).
After the operation completes, call grpc_metadata_array_destroy on this After the operation completes, call grpc_metadata_array_destroy on this
value, or reuse it in a future op. */ value, or reuse it in a future op. */
grpc_metadata_array *recv_initial_metadata; grpc_metadata_array *recv_initial_metadata;
/* ownership of the byte buffer is moved to the caller; the caller must call /** ownership of the byte buffer is moved to the caller; the caller must call
grpc_byte_buffer_destroy on this value, or reuse it in a future op. */ grpc_byte_buffer_destroy on this value, or reuse it in a future op. */
grpc_byte_buffer **recv_message; grpc_byte_buffer **recv_message;
struct { struct {
/* ownership of the array is with the caller, but ownership of the /** ownership of the array is with the caller, but ownership of the
elements elements stays with the call object (ie key, value members are owned
stays with the call object (ie key, value members are owned by the call by the call object, trailing_metadata->array is owned by the caller).
object, trailing_metadata->array is owned by the caller). After the operation completes, call grpc_metadata_array_destroy on this
After the operation completes, call grpc_metadata_array_destroy on this value, or reuse it in a future op. */
value, or reuse it in a future op. */
grpc_metadata_array *trailing_metadata; grpc_metadata_array *trailing_metadata;
grpc_status_code *status; grpc_status_code *status;
/* status_details is a buffer owned by the application before the op /** status_details is a buffer owned by the application before the op
completes completes and after the op has completed. During the operation
and after the op has completed. During the operation status_details may status_details may be reallocated to a size larger than
be *status_details_capacity, in which case *status_details_capacity will
reallocated to a size larger than *status_details_capacity, in which be updated with the new array capacity.
case
*status_details_capacity will be updated with the new array capacity. Pre-allocating space:
size_t my_capacity = 8;
Pre-allocating space: char *my_details = gpr_malloc(my_capacity);
size_t my_capacity = 8; x.status_details = &my_details;
char *my_details = gpr_malloc(my_capacity); x.status_details_capacity = &my_capacity;
x.status_details = &my_details;
x.status_details_capacity = &my_capacity; Not pre-allocating space:
size_t my_capacity = 0;
Not pre-allocating space: char *my_details = NULL;
size_t my_capacity = 0; x.status_details = &my_details;
char *my_details = NULL; x.status_details_capacity = &my_capacity;
x.status_details = &my_details;
x.status_details_capacity = &my_capacity; After the call:
gpr_free(my_details); */
After the call:
gpr_free(my_details); */
char **status_details; char **status_details;
size_t *status_details_capacity; size_t *status_details_capacity;
} recv_status_on_client; } recv_status_on_client;
struct { struct {
/* out argument, set to 1 if the call failed in any way (seen as a /** out argument, set to 1 if the call failed in any way (seen as a
cancellation cancellation on the server), or 0 if the call succeeded */
on the server), or 0 if the call succeeded */
int *cancelled; int *cancelled;
} recv_close_on_server; } recv_close_on_server;
} data; } data;
...@@ -379,62 +383,62 @@ grpc_event grpc_completion_queue_next(grpc_completion_queue *cq, ...@@ -379,62 +383,62 @@ grpc_event grpc_completion_queue_next(grpc_completion_queue *cq,
grpc_event grpc_completion_queue_pluck(grpc_completion_queue *cq, void *tag, grpc_event grpc_completion_queue_pluck(grpc_completion_queue *cq, void *tag,
gpr_timespec deadline); gpr_timespec deadline);
/* Begin destruction of a completion queue. Once all possible events are /** Begin destruction of a completion queue. Once all possible events are
drained then grpc_completion_queue_next will start to produce drained then grpc_completion_queue_next will start to produce
GRPC_QUEUE_SHUTDOWN events only. At that point it's safe to call GRPC_QUEUE_SHUTDOWN events only. At that point it's safe to call
grpc_completion_queue_destroy. grpc_completion_queue_destroy.
After calling this function applications should ensure that no After calling this function applications should ensure that no
NEW work is added to be published on this completion queue. */ NEW work is added to be published on this completion queue. */
void grpc_completion_queue_shutdown(grpc_completion_queue *cq); void grpc_completion_queue_shutdown(grpc_completion_queue *cq);
/* Destroy a completion queue. The caller must ensure that the queue is /** Destroy a completion queue. The caller must ensure that the queue is
drained and no threads are executing grpc_completion_queue_next */ drained and no threads are executing grpc_completion_queue_next */
void grpc_completion_queue_destroy(grpc_completion_queue *cq); void grpc_completion_queue_destroy(grpc_completion_queue *cq);
/* Create a call given a grpc_channel, in order to call 'method'. All /** Create a call given a grpc_channel, in order to call 'method'. All
completions are sent to 'completion_queue'. 'method' and 'host' need only completions are sent to 'completion_queue'. 'method' and 'host' need only
live through the invocation of this function. */ live through the invocation of this function. */
grpc_call *grpc_channel_create_call(grpc_channel *channel, grpc_call *grpc_channel_create_call(grpc_channel *channel,
grpc_completion_queue *completion_queue, grpc_completion_queue *completion_queue,
const char *method, const char *host, const char *method, const char *host,
gpr_timespec deadline); gpr_timespec deadline);
/* Pre-register a method/host pair on a channel. */ /** Pre-register a method/host pair on a channel. */
void *grpc_channel_register_call(grpc_channel *channel, const char *method, void *grpc_channel_register_call(grpc_channel *channel, const char *method,
const char *host); const char *host);
/* Create a call given a handle returned from grpc_channel_register_call */ /** Create a call given a handle returned from grpc_channel_register_call */
grpc_call *grpc_channel_create_registered_call( grpc_call *grpc_channel_create_registered_call(
grpc_channel *channel, grpc_completion_queue *completion_queue, grpc_channel *channel, grpc_completion_queue *completion_queue,
void *registered_call_handle, gpr_timespec deadline); void *registered_call_handle, gpr_timespec deadline);
/* Start a batch of operations defined in the array ops; when complete, post a /** 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. completion of type 'tag' to the completion queue bound to the call.
The order of ops specified in the batch has no significance. 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 Only one operation of each type can be active at once in any given
batch. You must call grpc_completion_queue_next or batch. You must call grpc_completion_queue_next or
grpc_completion_queue_pluck on the completion queue associated with 'call' grpc_completion_queue_pluck on the completion queue associated with 'call'
for work to be performed. for work to be performed.
THREAD SAFETY: access to grpc_call_start_batch in multi-threaded environment THREAD SAFETY: access to grpc_call_start_batch in multi-threaded environment
needs to be synchronized. As an optimization, you may synchronize batches needs to be synchronized. As an optimization, you may synchronize batches
containing just send operations independently from batches containing just containing just send operations independently from batches containing just
receive operations. */ receive operations. */
grpc_call_error grpc_call_start_batch(grpc_call *call, const grpc_op *ops, grpc_call_error grpc_call_start_batch(grpc_call *call, const grpc_op *ops,
size_t nops, void *tag); size_t nops, void *tag);
/* Create a client channel to 'target'. Additional channel level configuration /** Create a client channel to 'target'. Additional channel level configuration
MAY be provided by grpc_channel_args, though the expectation is that most MAY be provided by grpc_channel_args, though the expectation is that most
clients will want to simply pass NULL. See grpc_channel_args definition for clients will want to simply pass NULL. See grpc_channel_args definition for
more on this. The data in 'args' need only live through the invocation of more on this. The data in 'args' need only live through the invocation of
this function. */ this function. */
grpc_channel *grpc_channel_create(const char *target, grpc_channel *grpc_channel_create(const char *target,
const grpc_channel_args *args); const grpc_channel_args *args);
/* Create a lame client: this client fails every operation attempted on it. */ /** Create a lame client: this client fails every operation attempted on it. */
grpc_channel *grpc_lame_client_channel_create(void); grpc_channel *grpc_lame_client_channel_create(void);
/* Close and destroy a grpc channel */ /** Close and destroy a grpc channel */
void grpc_channel_destroy(grpc_channel *channel); void grpc_channel_destroy(grpc_channel *channel);
/* Error handling for grpc_call /* Error handling for grpc_call
...@@ -443,49 +447,49 @@ void grpc_channel_destroy(grpc_channel *channel); ...@@ -443,49 +447,49 @@ void grpc_channel_destroy(grpc_channel *channel);
If a grpc_call fails, it's guaranteed that no change to the call state If a grpc_call fails, it's guaranteed that no change to the call state
has been made. */ has been made. */
/* Called by clients to cancel an RPC on the server. /** Called by clients to cancel an RPC on the server.
Can be called multiple times, from any thread. Can be called multiple times, from any thread.
THREAD-SAFETY grpc_call_cancel and grpc_call_cancel_with_status THREAD-SAFETY grpc_call_cancel and grpc_call_cancel_with_status
are thread-safe, and can be called at any point before grpc_call_destroy are thread-safe, and can be called at any point before grpc_call_destroy
is called.*/ is called.*/
grpc_call_error grpc_call_cancel(grpc_call *call); grpc_call_error grpc_call_cancel(grpc_call *call);
/* Called by clients to cancel an RPC on the server. /** Called by clients to cancel an RPC on the server.
Can be called multiple times, from any thread. Can be called multiple times, from any thread.
If a status has not been received for the call, set it to the status code If a status has not been received for the call, set it to the status code
and description passed in. and description passed in.
Importantly, this function does not send status nor description to the Importantly, this function does not send status nor description to the
remote endpoint. */ remote endpoint. */
grpc_call_error grpc_call_cancel_with_status(grpc_call *call, grpc_call_error grpc_call_cancel_with_status(grpc_call *call,
grpc_status_code status, grpc_status_code status,
const char *description); const char *description);
/* Destroy a call. /** Destroy a call.
THREAD SAFETY: grpc_call_destroy is thread-compatible */ THREAD SAFETY: grpc_call_destroy is thread-compatible */
void grpc_call_destroy(grpc_call *call); void grpc_call_destroy(grpc_call *call);
/* Request notification of a new call. 'cq_for_notification' must /** Request notification of a new call. 'cq_for_notification' must
have been registered to the server via grpc_server_register_completion_queue. have been registered to the server via
*/ grpc_server_register_completion_queue. */
grpc_call_error grpc_server_request_call( grpc_call_error grpc_server_request_call(
grpc_server *server, grpc_call **call, grpc_call_details *details, grpc_server *server, grpc_call **call, grpc_call_details *details,
grpc_metadata_array *request_metadata, grpc_metadata_array *request_metadata,
grpc_completion_queue *cq_bound_to_call, grpc_completion_queue *cq_bound_to_call,
grpc_completion_queue *cq_for_notification, void *tag_new); grpc_completion_queue *cq_for_notification, void *tag_new);
/* Registers a method in the server. /** Registers a method in the server.
Methods to this (host, method) pair will not be reported by Methods to this (host, method) pair will not be reported by
grpc_server_request_call, but instead be reported by grpc_server_request_call, but instead be reported by
grpc_server_request_registered_call when passed the appropriate grpc_server_request_registered_call when passed the appropriate
registered_method (as returned by this function). registered_method (as returned by this function).
Must be called before grpc_server_start. Must be called before grpc_server_start.
Returns NULL on failure. */ Returns NULL on failure. */
void *grpc_server_register_method(grpc_server *server, const char *method, void *grpc_server_register_method(grpc_server *server, const char *method,
const char *host); const char *host);
/* Request notification of a new pre-registered call. 'cq_for_notification' must /** Request notification of a new pre-registered call. 'cq_for_notification'
have been registered to the server via grpc_server_register_completion_queue. must have been registered to the server via
*/ grpc_server_register_completion_queue. */
grpc_call_error grpc_server_request_registered_call( grpc_call_error grpc_server_request_registered_call(
grpc_server *server, void *registered_method, grpc_call **call, grpc_server *server, void *registered_method, grpc_call **call,
gpr_timespec *deadline, grpc_metadata_array *request_metadata, gpr_timespec *deadline, grpc_metadata_array *request_metadata,
...@@ -493,45 +497,45 @@ grpc_call_error grpc_server_request_registered_call( ...@@ -493,45 +497,45 @@ grpc_call_error grpc_server_request_registered_call(
grpc_completion_queue *cq_bound_to_call, grpc_completion_queue *cq_bound_to_call,
grpc_completion_queue *cq_for_notification, void *tag_new); grpc_completion_queue *cq_for_notification, void *tag_new);
/* Create a server. Additional configuration for each incoming channel can /** Create a server. Additional configuration for each incoming channel can
be specified with args. If no additional configuration is needed, args can be specified with args. If no additional configuration is needed, args can
be NULL. See grpc_channel_args for more. The data in 'args' need only live be NULL. See grpc_channel_args for more. The data in 'args' need only live
through the invocation of this function. */ through the invocation of this function. */
grpc_server *grpc_server_create(const grpc_channel_args *args); grpc_server *grpc_server_create(const grpc_channel_args *args);
/* Register a completion queue with the server. Must be done for any /** Register a completion queue with the server. Must be done for any
notification completion queue that is passed to grpc_server_request_*_call notification completion queue that is passed to grpc_server_request_*_call
and to grpc_server_shutdown_and_notify. Must be performed prior to and to grpc_server_shutdown_and_notify. Must be performed prior to
grpc_server_start. */ grpc_server_start. */
void grpc_server_register_completion_queue(grpc_server *server, void grpc_server_register_completion_queue(grpc_server *server,
grpc_completion_queue *cq); grpc_completion_queue *cq);
/* Add a HTTP2 over plaintext over tcp listener. /** Add a HTTP2 over plaintext over tcp listener.
Returns bound port number on success, 0 on failure. Returns bound port number on success, 0 on failure.
REQUIRES: server not started */ REQUIRES: server not started */
int grpc_server_add_http2_port(grpc_server *server, const char *addr); int grpc_server_add_http2_port(grpc_server *server, const char *addr);
/* Start a server - tells all listeners to start listening */ /** Start a server - tells all listeners to start listening */
void grpc_server_start(grpc_server *server); void grpc_server_start(grpc_server *server);
/* Begin shutting down a server. /** Begin shutting down a server.
After completion, no new calls or connections will be admitted. After completion, no new calls or connections will be admitted.
Existing calls will be allowed to complete. Existing calls will be allowed to complete.
Send a GRPC_OP_COMPLETE event when there are no more calls being serviced. 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 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 grpc_server_shutdown_and_notify calls are made. 'cq' must have been
registered to this server via grpc_server_register_completion_queue. */ registered to this server via grpc_server_register_completion_queue. */
void grpc_server_shutdown_and_notify(grpc_server *server, void grpc_server_shutdown_and_notify(grpc_server *server,
grpc_completion_queue *cq, void *tag); grpc_completion_queue *cq, void *tag);
/* Cancel all in-progress calls. /** Cancel all in-progress calls.
Only usable after shutdown. */ Only usable after shutdown. */
void grpc_server_cancel_all_calls(grpc_server *server); void grpc_server_cancel_all_calls(grpc_server *server);
/* Destroy a server. /** Destroy a server.
Shutdown must have completed beforehand (i.e. all tags generated by Shutdown must have completed beforehand (i.e. all tags generated by
grpc_server_shutdown_and_notify must have been received, and at least grpc_server_shutdown_and_notify must have been received, and at least
one call to grpc_server_shutdown_and_notify must have been made). */ one call to grpc_server_shutdown_and_notify must have been made). */
void grpc_server_destroy(grpc_server *server); void grpc_server_destroy(grpc_server *server);
/** Enable or disable a tracer. /** Enable or disable a tracer.
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment