carto
/
grpc


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162
							<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.17"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>GRPC Core: gRPC Error</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">GRPC Core
   &#160;<span id="projectnumber">15.0.0</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.17 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

</div><!-- top -->
<div class="PageDoc"><div class="header">
  <div class="headertitle">
<div class="title">gRPC Error </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="autotoc_md104"></a>
Background</h1>
<p><code>grpc_error</code> is the c-core's opaque representation of an error. It holds a collection of integers, strings, timestamps, and child errors that related to the final error.</p>
<p>always present are:</p>
<ul>
<li>GRPC_ERROR_STR_FILE and GRPC_ERROR_INT_FILE_LINE - the source location where the error was generated</li>
<li>GRPC_ERROR_STR_DESCRIPTION - a human readable description of the error</li>
<li>GRPC_ERROR_TIME_CREATED - a timestamp indicating when the error happened</li>
</ul>
<p>An error can also have children; these are other errors that are believed to have contributed to this one. By accumulating children, we can begin to root cause high level failures from low level failures, without having to derive execution paths from log lines.</p>
<p>grpc_errors are refcounted objects, which means they need strict ownership semantics. An extra ref on an error can cause a memory leak, and a missing ref can cause a crash.</p>
<p>This document serves as a detailed overview of grpc_error's ownership rules. It should help people use the errors, as well as help people debug refcount related errors.</p>
<h1><a class="anchor" id="autotoc_md105"></a>
Clarification of Ownership</h1>
<p>If a particular function is said to "own" an error, that means it has the responsibility of calling unref on the error. A function may have access to an error without ownership of it.</p>
<p>This means the function may use the error, but must not call unref on it, since that will be done elsewhere in the code. A function that does not own an error may explicitly take ownership of it by manually calling GRPC_ERROR_REF.</p>
<h1><a class="anchor" id="autotoc_md106"></a>
Ownership Rules</h1>
<p>There are three rules of error ownership, which we will go over in detail.</p>
<ul>
<li>If <code>grpc_error</code> is returned by a function, the caller owns a ref to that instance.</li>
<li>If a <code>grpc_error</code> is passed to a <code>grpc_closure</code> callback function, then that function does not own a ref to the error.</li>
<li>if a <code>grpc_error</code> is passed to <em>any other function</em>, then that function takes ownership of the error.</li>
</ul>
<h2><a class="anchor" id="autotoc_md107"></a>
Rule 1</h2>
<blockquote class="doxtable">
<p>If <code>grpc_error</code> is returned by a function, the caller owns a ref to that instance.* </p>
</blockquote>
<p>For example, in the following code block, error1 and error2 are owned by the current function.</p>
<div class="fragment"><div class="line">grpc_error* error1 = GRPC_ERROR_CREATE_FROM_STATIC_STRING(<span class="stringliteral">&quot;Some error occurred&quot;</span>);</div>
<div class="line">grpc_error* error2 = some_operation_that_might_fail(...);</div>
</div><!-- fragment --><p>The current function would have to explicitly call GRPC_ERROR_UNREF on the errors, or pass them along to a function that would take over the ownership.</p>
<h2><a class="anchor" id="autotoc_md108"></a>
Rule 2</h2>
<blockquote class="doxtable">
<p>If a <code>grpc_error</code> is passed to a <code>grpc_closure</code> callback function, then that function does not own a ref to the error. </p>
</blockquote>
<p>A <code>grpc_closure</code> callback function is any function that has the signature:</p>
<div class="fragment"><div class="line">void (*cb)(grpc_exec_ctx *exec_ctx, <span class="keywordtype">void</span> *arg, grpc_error *error);</div>
</div><!-- fragment --><p>This means that the error ownership is NOT transferred when a functions calls:</p>
<div class="fragment"><div class="line">c-&gt;cb(exec_ctx, c-&gt;cb_arg, err);</div>
</div><!-- fragment --><p>The caller is still responsible for unref-ing the error.</p>
<p>However, the above line is currently being phased out! It is safer to invoke callbacks with <code>GRPC_CLOSURE_RUN</code> and <code>GRPC_CLOSURE_SCHED</code>. These functions are not callbacks, so they will take ownership of the error passed to them.</p>
<div class="fragment"><div class="line">grpc_error* error = GRPC_ERROR_CREATE_FROM_STATIC_STRING(<span class="stringliteral">&quot;Some error occurred&quot;</span>);</div>
<div class="line">GRPC_CLOSURE_RUN(exec_ctx, cb, error);</div>
<div class="line"><span class="comment">// current function no longer has ownership of the error</span></div>
</div><!-- fragment --><p>If you schedule or run a closure, but still need ownership of the error, then you must explicitly take a reference.</p>
<div class="fragment"><div class="line">grpc_error* error = GRPC_ERROR_CREATE_FROM_STATIC_STRING(<span class="stringliteral">&quot;Some error occurred&quot;</span>);</div>
<div class="line">GRPC_CLOSURE_RUN(exec_ctx, cb, GRPC_ERROR_REF(error));</div>
<div class="line"><span class="comment">// do some other things with the error</span></div>
<div class="line">GRPC_ERROR_UNREF(error);</div>
</div><!-- fragment --><p>Rule 2 is more important to keep in mind when <b>implementing</b> <code>grpc_closure</code> callback functions. You must keep in mind that you do not own the error, and must not unref it. More importantly, you cannot pass it to any function that would take ownership of the error, without explicitly taking ownership yourself. For example:</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> on_some_action(grpc_exec_ctx *exec_ctx, <span class="keywordtype">void</span> *arg, grpc_error *error) {</div>
<div class="line">  <span class="comment">// this would cause a crash, because some_function will unref the error,</span></div>
<div class="line">  <span class="comment">// and the caller of this callback will also unref it.</span></div>
<div class="line">  some_function(error);</div>
<div class="line"> </div>
<div class="line">  <span class="comment">// this callback function must take ownership, so it can give that</span></div>
<div class="line">  <span class="comment">// ownership to the function it is calling.</span></div>
<div class="line">  some_function(GRPC_ERROR_REF(error));</div>
<div class="line">}</div>
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md109"></a>
Rule 3</h2>
<blockquote class="doxtable">
<p>if a <code>grpc_error</code> is passed to <em>any other function</em>, then that function takes ownership of the error. </p>
</blockquote>
<p>Take the following example:</p>
<div class="fragment"><div class="line">grpc_error* error = GRPC_ERROR_CREATE_FROM_STATIC_STRING(<span class="stringliteral">&quot;Some error occurred&quot;</span>);</div>
<div class="line"><span class="comment">// do some things</span></div>
<div class="line">some_function(error);</div>
<div class="line"><span class="comment">// can&#39;t use error anymore! might be gone.</span></div>
</div><!-- fragment --><p>When some_function is called, it takes over the ownership of the error, and it will eventually unref it. So the caller can no longer safely use the error.</p>
<p>If the caller needed to keep using the error (or passing it to other functions), if would have to take on a reference to it. This is a common pattern seen.</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> func() {</div>
<div class="line">  grpc_error* error = GRPC_ERROR_CREATE_FROM_STATIC_STRING(<span class="stringliteral">&quot;Some error&quot;</span>);</div>
<div class="line">  some_function(GRPC_ERROR_REF(error));</div>
<div class="line">  <span class="comment">// do things</span></div>
<div class="line">  some_other_function(GRPC_ERROR_REF(error));</div>
<div class="line">  <span class="comment">// do more things</span></div>
<div class="line">  some_last_function(error);</div>
<div class="line">}</div>
</div><!-- fragment --><p>The last call takes ownership and will eventually give the error its final unref.</p>
<p>When <b>implementing</b> a function that takes an error (and is not a <code>grpc_closure</code> callback function), you must ensure the error is unref-ed either by doing it explicitly with GRPC_ERROR_UNREF, or by passing the error to a function that takes over the ownership. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Wed Mar 3 2021 19:17:11 for GRPC Core by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.17
</small></address>
</body>
</html>