Explain the newer semantics of grpc_error_add_child

2 files changed, 12 insertions, 0 deletions

diff --git a/src/core/lib/iomgr/error.cc b/src/core/lib/iomgr/error.cc
index dfd063a695..13bc69ffb6 100644
--- a/src/core/lib/iomgr/error.cc
+++ b/src/core/lib/iomgr/error.cc
@@ -515,15 +515,20 @@ grpc_error* grpc_error_add_child(grpc_error* src, grpc_error* child) {
   GPR_TIMER_SCOPE("grpc_error_add_child", 0);
   if (src != GRPC_ERROR_NONE) {
     if (child == GRPC_ERROR_NONE) {
+      /* \a child is empty. Simply return the ref to \a src */
       return src;
     } else if (child != src) {
       grpc_error* new_err = copy_error_and_unref(src);
       internal_add_error(&new_err, child);
       return new_err;
     } else {
+      /* \a src and \a child are the same. Drop one of the references and return
+       * the other */
+      GRPC_ERROR_UNREF(child);
       return src;
     }
   } else {
+    /* \a src is empty. Simply return the ref to \a child */
     return child;
   }
 }
diff --git a/src/core/lib/iomgr/error.h b/src/core/lib/iomgr/error.h
index e5369695c9..49f4029bc2 100644
--- a/src/core/lib/iomgr/error.h
+++ b/src/core/lib/iomgr/error.h
@@ -185,6 +185,13 @@ bool grpc_error_get_str(grpc_error* error, grpc_error_strs which,
 /// error occurring. Allows root causing high level errors from lower level
 /// errors that contributed to them. The src error takes ownership of the
 /// child error.
+///
+/// Edge Conditions -
+/// 1) If either of \a src or \a child is GRPC_ERROR_NONE, returns a reference
+/// to the other argument. 2) If both \a src and \a child are GRPC_ERROR_NONE,
+/// returns GRPC_ERROR_NONE. 3) If \a src and \a child point to the same error,
+/// returns a single reference. (Note that, 2 references should have been
+/// received to the error in this case.)
 grpc_error* grpc_error_add_child(grpc_error* src,
                                  grpc_error* child) GRPC_MUST_USE_RESULT;