diff --git a/include/grpc/grpc.h b/include/grpc/grpc.h index 47d749c7289..aec78be31b7 100644 --- a/include/grpc/grpc.h +++ b/include/grpc/grpc.h @@ -269,9 +269,11 @@ GRPCAPI void grpc_channel_get_info(grpc_channel* 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. The data in 'args' need only live through the invocation of - this function. */ + 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. */ GRPCAPI grpc_channel* grpc_insecure_channel_create( const char* target, const grpc_channel_args* args, void* reserved); @@ -364,8 +366,11 @@ GRPCAPI grpc_call_error grpc_server_request_registered_call( /** Create a server. Additional configuration for each incoming channel 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 - through the invocation of this function. */ + 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. */ GRPCAPI grpc_server* grpc_server_create(const grpc_channel_args* args, void* reserved); diff --git a/include/grpc/grpc_security.h b/include/grpc/grpc_security.h index bae07ac3098..08776337cc5 100644 --- a/include/grpc/grpc_security.h +++ b/include/grpc/grpc_security.h @@ -300,7 +300,13 @@ GRPCAPI grpc_call_credentials* grpc_metadata_credentials_create_from_plugin( /** --- Secure channel creation. --- */ -/** Creates a secure channel using the passed-in credentials. */ +/** Creates a secure channel using the passed-in credentials. 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. */ GRPCAPI grpc_channel* grpc_secure_channel_create( grpc_channel_credentials* creds, const char* target, const grpc_channel_args* args, void* reserved); diff --git a/include/grpc/impl/codegen/grpc_types.h b/include/grpc/impl/codegen/grpc_types.h index d64b23f332d..a372dbba73a 100644 --- a/include/grpc/impl/codegen/grpc_types.h +++ b/include/grpc/impl/codegen/grpc_types.h @@ -119,9 +119,14 @@ typedef struct { 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 (i.e. the values in this structure need only live through the + time (i.e. the keys and values in this structure need only live through the creation invocation). + However, if one of the args has grpc_arg_type==GRPC_ARG_POINTER, then the + grpc_arg_pointer_vtable must live until the channel args are done being + used by core (i.e. when the object for use with which they were passed + is destroyed). + See the description of the \ref grpc_arg_keys "available args" for more details. */ typedef struct {