From 29f2b219a8631ed788708a326190aa3a611911e0 Mon Sep 17 00:00:00 2001 From: Craig Tiller Date: Tue, 17 Feb 2015 17:01:24 -0800 Subject: Add channel argument documentation --- include/grpc/grpc.h | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/include/grpc/grpc.h b/include/grpc/grpc.h index 9807de9f4b..077b432e88 100644 --- a/include/grpc/grpc.h +++ b/include/grpc/grpc.h @@ -92,7 +92,12 @@ typedef struct { } value; } grpc_arg; -/* An array of arguments that can be passed around */ +/* An array of arguments that can be passed around. + Used to set optional channel-level configuration. + These configuration options are modelled as key-value pairs as defined + by grpc_arg; keys are strings to allow easy backwards-compatible extension + by arbitrary parties. + All evaluation is performed at channel creation time. */ typedef struct { size_t num_args; grpc_arg *args; @@ -400,7 +405,10 @@ grpc_call *grpc_channel_create_call(grpc_channel *channel, grpc_call_error grpc_call_start_batch(grpc_call *call, const grpc_op *ops, size_t nops, void *tag); -/* Create a client channel */ +/* 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. See grpc_channel_args definition + for more on this. */ grpc_channel *grpc_channel_create(const char *target, const grpc_channel_args *args); @@ -545,7 +553,8 @@ grpc_call_error grpc_server_request_call( grpc_metadata_array *request_metadata, grpc_completion_queue *completion_queue, void *tag_new); -/* Create a server */ +/* Create a server. Additional configuration for each incoming channel can + be specified with args. See grpc_channel_args for more. */ grpc_server *grpc_server_create(grpc_completion_queue *cq, const grpc_channel_args *args); -- cgit v1.2.3 From e7163ab6250ea6adc6b85ea36e67bd6c93ccaadc Mon Sep 17 00:00:00 2001 From: Craig Tiller Date: Tue, 17 Feb 2015 20:46:08 -0800 Subject: Expand comment --- include/grpc/grpc.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/include/grpc/grpc.h b/include/grpc/grpc.h index 077b432e88..358f59238a 100644 --- a/include/grpc/grpc.h +++ b/include/grpc/grpc.h @@ -554,7 +554,8 @@ grpc_call_error grpc_server_request_call( grpc_completion_queue *completion_queue, void *tag_new); /* Create a server. Additional configuration for each incoming channel can - be specified with args. See grpc_channel_args for more. */ + be specified with args. If no additional configuration is needed, args can + be NULL. See grpc_channel_args for more. */ grpc_server *grpc_server_create(grpc_completion_queue *cq, const grpc_channel_args *args); -- cgit v1.2.3