From c56b2cb33ce9adebd615e941695ec292aaa0babb Mon Sep 17 00:00:00 2001
From: Craig Tiller <ctiller@google.com>
Date: Thu, 5 Feb 2015 16:35:38 -0800
Subject: [PATCH] Add comments
---
include/grpc/grpc.h | 29 +++++++++++++++++++++++++++--
1 file changed, 27 insertions(+), 2 deletions(-)
diff --git a/include/grpc/grpc.h b/include/grpc/grpc.h
index 89cccab3d2..982cd3b43e 100644
--- a/include/grpc/grpc.h
+++ b/include/grpc/grpc.h
@@ -293,14 +293,39 @@ typedef struct grpc_op {
const char *status_details;
} send_status_from_server;
/* ownership of the array is with the caller, but ownership of the elements
- stays with the call object */
+ stays with the call object (ie key, value members are owned by the call
+ object, recv_initial_metadata->array is owned by the caller).
+ After the operation completes, call grpc_metadata_array_destroy on this
+ value, or reuse it in a future op. */
grpc_metadata_array *recv_initial_metadata;
grpc_byte_buffer **recv_message;
struct {
/* ownership of the array is with the caller, but ownership of the elements
- stays with the call object */
+ stays with the call object (ie key, value members are owned by the call
+ object, trailing_metadata->array is owned by the caller).
+ After the operation completes, call grpc_metadata_array_destroy on this
+ value, or reuse it in a future op. */
grpc_metadata_array *trailing_metadata;
grpc_status_code *status;
+ /* status_details is a buffer owned by the application before the op completes
+ and after the op has completed. During the operation status_details may be
+ reallocated to a size larger than *status_details_capacity, in which case
+ *status_details_capacity will be updated with the new array capacity.
+
+ Pre-allocating space:
+ size_t my_capacity = 8;
+ char *my_details = gpr_malloc(my_capacity);
+ x.status_details = &my_details;
+ x.status_details_capacity = &my_capacity;
+
+ Not pre-allocating space:
+ size_t my_capacity = 0;
+ char *my_details = NULL;
+ x.status_details = &my_details;
+ x.status_details_capacity = &my_capacity;
+
+ After the call:
+ gpr_free(my_details); */
char **status_details;
size_t *status_details_capacity;
} recv_status_on_client;
--
GitLab