From e83c2349408cc6668020e5bdd7edf547607395a7 Mon Sep 17 00:00:00 2001
From: ncteisen <ncteisen@gmail.com>
Date: Mon, 12 Feb 2018 07:25:53 -0800
Subject: [PATCH] Add details about API gaurantees

---
 include/grpc/grpc.h                    | 15 ++++++++++-----
 include/grpc/grpc_security.h           |  8 +++++++-
 include/grpc/impl/codegen/grpc_types.h |  7 ++++++-
 3 files changed, 23 insertions(+), 7 deletions(-)

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 {