blob: 2f7d538c9b68f082c0c06fe4ad06069908dfc73f [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://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.6"/>
<title>Kudu C++ client API: kudu::client::KuduSession Class Reference</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/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { searchBox.OnSelectItem(0); });
</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 style="padding-left: 0.5em;">
<div id="projectname">Kudu C++ client API
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.6 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main&#160;Page</span></a></li>
<li><a href="pages.html"><span>Related&#160;Pages</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li class="current"><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</div>
<div id="navrow2" class="tabs2">
<ul class="tablist">
<li><a href="annotated.html"><span>Class&#160;List</span></a></li>
<li><a href="classes.html"><span>Class&#160;Index</span></a></li>
<li><a href="hierarchy.html"><span>Class&#160;Hierarchy</span></a></li>
<li><a href="functions.html"><span>Class&#160;Members</span></a></li>
</ul>
</div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Friends</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(11)"><span class="SelectionMark">&#160;</span>Pages</a></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 id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="namespacekudu.html">kudu</a></li><li class="navelem"><b>client</b></li><li class="navelem"><a class="el" href="classkudu_1_1client_1_1KuduSession.html">KuduSession</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="summary">
<a href="#pub-types">Public Types</a> &#124;
<a href="#pub-methods">Public Member Functions</a> &#124;
<a href="#friends">Friends</a> &#124;
<a href="classkudu_1_1client_1_1KuduSession-members.html">List of all members</a> </div>
<div class="headertitle">
<div class="title">kudu::client::KuduSession Class Reference</div> </div>
</div><!--header-->
<div class="contents">
<p>Representation of a Kudu client session.
<a href="classkudu_1_1client_1_1KuduSession.html#details">More...</a></p>
<p><code>#include &lt;<a class="el" href="client_8h_source.html">client.h</a>&gt;</code></p>
<div class="dynheader">
Inheritance diagram for kudu::client::KuduSession:</div>
<div class="dyncontent">
<div class="center">
<img src="classkudu_1_1client_1_1KuduSession.png" usemap="#kudu::client::KuduSession_map" alt=""/>
<map id="kudu::client::KuduSession_map" name="kudu::client::KuduSession_map">
</map>
</div></div>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="pub-types"></a>
Public Types</h2></td></tr>
<tr class="memitem:aaec3956e642610d703f3b83b78e24e19"><td class="memItemLeft" align="right" valign="top">enum &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classkudu_1_1client_1_1KuduSession.html#aaec3956e642610d703f3b83b78e24e19">FlushMode</a> { <a class="el" href="classkudu_1_1client_1_1KuduSession.html#aaec3956e642610d703f3b83b78e24e19ad74b76e407e62ca951d369521636df2b">AUTO_FLUSH_SYNC</a>,
<a class="el" href="classkudu_1_1client_1_1KuduSession.html#aaec3956e642610d703f3b83b78e24e19a520b8eef7ef0fd149b2757faf43972b1">AUTO_FLUSH_BACKGROUND</a>,
<a class="el" href="classkudu_1_1client_1_1KuduSession.html#aaec3956e642610d703f3b83b78e24e19a1db3efc2094da09aae45bb68475cdb4a">MANUAL_FLUSH</a>
}</td></tr>
<tr class="memdesc:aaec3956e642610d703f3b83b78e24e19"><td class="mdescLeft">&#160;</td><td class="mdescRight">Modes of flush operations. <a href="classkudu_1_1client_1_1KuduSession.html#aaec3956e642610d703f3b83b78e24e19">More...</a><br/></td></tr>
<tr class="separator:aaec3956e642610d703f3b83b78e24e19"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:aabd55109ba3b086bbe33b277cdd40d22"><td class="memItemLeft" align="right" valign="top">enum &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classkudu_1_1client_1_1KuduSession.html#aabd55109ba3b086bbe33b277cdd40d22">ExternalConsistencyMode</a> { <a class="el" href="classkudu_1_1client_1_1KuduSession.html#aabd55109ba3b086bbe33b277cdd40d22ae978fab7451faebf4399830b603c855c">CLIENT_PROPAGATED</a>,
<a class="el" href="classkudu_1_1client_1_1KuduSession.html#aabd55109ba3b086bbe33b277cdd40d22a70010f3ef1f70b99b02328c024c436c9">COMMIT_WAIT</a>
}</td></tr>
<tr class="memdesc:aabd55109ba3b086bbe33b277cdd40d22"><td class="mdescLeft">&#160;</td><td class="mdescRight">The possible external consistency modes on which Kudu operates. <a href="classkudu_1_1client_1_1KuduSession.html#aabd55109ba3b086bbe33b277cdd40d22">More...</a><br/></td></tr>
<tr class="separator:aabd55109ba3b086bbe33b277cdd40d22"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="pub-methods"></a>
Public Member Functions</h2></td></tr>
<tr class="memitem:a83555781b5a037f87c215e565ecf1a8f"><td class="memItemLeft" align="right" valign="top"><a class="el" href="classkudu_1_1Status.html">Status</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classkudu_1_1client_1_1KuduSession.html#a83555781b5a037f87c215e565ecf1a8f">SetFlushMode</a> (<a class="el" href="classkudu_1_1client_1_1KuduSession.html#aaec3956e642610d703f3b83b78e24e19">FlushMode</a> m) WARN_UNUSED_RESULT</td></tr>
<tr class="separator:a83555781b5a037f87c215e565ecf1a8f"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a56d1c7f47dfcaf5121b15a4435a8eeca"><td class="memItemLeft" align="right" valign="top"><a class="el" href="classkudu_1_1Status.html">Status</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classkudu_1_1client_1_1KuduSession.html#a56d1c7f47dfcaf5121b15a4435a8eeca">SetExternalConsistencyMode</a> (<a class="el" href="classkudu_1_1client_1_1KuduSession.html#aabd55109ba3b086bbe33b277cdd40d22">ExternalConsistencyMode</a> m) WARN_UNUSED_RESULT</td></tr>
<tr class="separator:a56d1c7f47dfcaf5121b15a4435a8eeca"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:aefa9bbc51c27104ce103b9ecda3b8abf"><td class="memItemLeft" align="right" valign="top"><a class="el" href="classkudu_1_1Status.html">Status</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classkudu_1_1client_1_1KuduSession.html#aefa9bbc51c27104ce103b9ecda3b8abf">SetMutationBufferSpace</a> (size_t size_bytes) WARN_UNUSED_RESULT</td></tr>
<tr class="separator:aefa9bbc51c27104ce103b9ecda3b8abf"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a25b22362650d7120f59cc1025e40bd79"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classkudu_1_1client_1_1KuduSession.html#a25b22362650d7120f59cc1025e40bd79">SetTimeoutMillis</a> (int millis)</td></tr>
<tr class="separator:a25b22362650d7120f59cc1025e40bd79"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ad3f7324b27fca298c5ca3d07b4741943"><td class="memItemLeft" align="right" valign="top"><a class="el" href="classkudu_1_1Status.html">Status</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classkudu_1_1client_1_1KuduSession.html#ad3f7324b27fca298c5ca3d07b4741943">Apply</a> (<a class="el" href="classkudu_1_1client_1_1KuduWriteOperation.html">KuduWriteOperation</a> *write_op) WARN_UNUSED_RESULT</td></tr>
<tr class="separator:ad3f7324b27fca298c5ca3d07b4741943"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a507e940962fdf08ee232534f73792b79"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classkudu_1_1client_1_1KuduSession.html#a507e940962fdf08ee232534f73792b79">ApplyAsync</a> (<a class="el" href="classkudu_1_1client_1_1KuduWriteOperation.html">KuduWriteOperation</a> *write_op, <a class="el" href="classkudu_1_1client_1_1KuduStatusCallback.html">KuduStatusCallback</a> *cb)</td></tr>
<tr class="separator:a507e940962fdf08ee232534f73792b79"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a64955abb5f5cc821b6e56354f733ce84"><td class="memItemLeft" align="right" valign="top"><a class="el" href="classkudu_1_1Status.html">Status</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classkudu_1_1client_1_1KuduSession.html#a64955abb5f5cc821b6e56354f733ce84">Flush</a> () WARN_UNUSED_RESULT</td></tr>
<tr class="separator:a64955abb5f5cc821b6e56354f733ce84"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ad8c68570479e95b325d8a5437eef8731"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classkudu_1_1client_1_1KuduSession.html#ad8c68570479e95b325d8a5437eef8731">FlushAsync</a> (<a class="el" href="classkudu_1_1client_1_1KuduStatusCallback.html">KuduStatusCallback</a> *cb)</td></tr>
<tr class="separator:ad8c68570479e95b325d8a5437eef8731"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:aa5204844e361ecc3068fbc4e02fd4436"><td class="memItemLeft" align="right" valign="top"><a class="el" href="classkudu_1_1Status.html">Status</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classkudu_1_1client_1_1KuduSession.html#aa5204844e361ecc3068fbc4e02fd4436">Close</a> () WARN_UNUSED_RESULT</td></tr>
<tr class="separator:aa5204844e361ecc3068fbc4e02fd4436"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a3f224e9b95f86da7e1f2ea6fcf327756"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classkudu_1_1client_1_1KuduSession.html#a3f224e9b95f86da7e1f2ea6fcf327756">HasPendingOperations</a> () const </td></tr>
<tr class="separator:a3f224e9b95f86da7e1f2ea6fcf327756"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a10edb757e362792454f0974e644109ab"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classkudu_1_1client_1_1KuduSession.html#a10edb757e362792454f0974e644109ab">CountBufferedOperations</a> () const </td></tr>
<tr class="separator:a10edb757e362792454f0974e644109ab"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a277c213a68679c6b0d5c432919eb9198"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classkudu_1_1client_1_1KuduSession.html#a277c213a68679c6b0d5c432919eb9198">CountPendingErrors</a> () const </td></tr>
<tr class="separator:a277c213a68679c6b0d5c432919eb9198"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ad5e3521623338de49cfd62914bdcb2f7"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classkudu_1_1client_1_1KuduSession.html#ad5e3521623338de49cfd62914bdcb2f7">GetPendingErrors</a> (std::vector&lt; <a class="el" href="classkudu_1_1client_1_1KuduError.html">KuduError</a> * &gt; *errors, bool *overflowed)</td></tr>
<tr class="separator:ad5e3521623338de49cfd62914bdcb2f7"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a4ed0bac1edcbba612d7de41e8c8adfd5"><td class="memItemLeft" align="right" valign="top"><a class="el" href="classkudu_1_1client_1_1KuduClient.html">KuduClient</a> *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classkudu_1_1client_1_1KuduSession.html#a4ed0bac1edcbba612d7de41e8c8adfd5">client</a> () const </td></tr>
<tr class="separator:a4ed0bac1edcbba612d7de41e8c8adfd5"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="friends"></a>
Friends</h2></td></tr>
<tr class="memitem:a5b5a804db2a148e792148f521f04b486"><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="a5b5a804db2a148e792148f521f04b486"></a>
class&#160;</td><td class="memItemRight" valign="bottom"><b>KuduClient</b></td></tr>
<tr class="separator:a5b5a804db2a148e792148f521f04b486"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ada57057f15990c8cc54770c782fa9ad4"><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="ada57057f15990c8cc54770c782fa9ad4"></a>
class&#160;</td><td class="memItemRight" valign="bottom"><b>internal::Batcher</b></td></tr>
<tr class="separator:ada57057f15990c8cc54770c782fa9ad4"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p>Representation of a Kudu client session. </p>
<p>A <a class="el" href="classkudu_1_1client_1_1KuduSession.html" title="Representation of a Kudu client session. ">KuduSession</a> belongs to a specific <a class="el" href="classkudu_1_1client_1_1KuduClient.html" title="A handle for a connection to a cluster. ">KuduClient</a>, and represents a context in which all read/write data access should take place. Within a session, multiple operations may be accumulated and batched together for better efficiency. Settings like timeouts, priorities, and trace IDs are also set per session.</p>
<p>A <a class="el" href="classkudu_1_1client_1_1KuduSession.html" title="Representation of a Kudu client session. ">KuduSession</a>'s main purpose is for grouping together multiple data-access operations together into batches or transactions. It is important to note the distinction between these two:</p>
<ul>
<li>A batch is a set of operations which are grouped together in order to amortize fixed costs such as RPC call overhead and round trip times. A batch DOES NOT imply any ACID-like guarantees. Within a batch, some operations may succeed while others fail, and concurrent readers may see partial results. If the client crashes mid-batch, it is possible that some of the operations will be made durable while others were lost. </li>
<li>In contrast, a transaction is a set of operations which are treated as an indivisible semantic unit, per the usual definitions of database transactions and isolation levels.</li>
</ul>
<dl class="section note"><dt>Note</dt><dd>Kudu does not currently support transactions! They are only mentioned in the above documentation to clarify that batches are not transactional and should only be used for efficiency.</dd></dl>
<p><a class="el" href="classkudu_1_1client_1_1KuduSession.html" title="Representation of a Kudu client session. ">KuduSession</a> is separate from <a class="el" href="classkudu_1_1client_1_1KuduTable.html" title="A representation of a table on a particular cluster. ">KuduTable</a> because a given batch or transaction may span multiple tables. This is particularly important in the future when we add ACID support, but even in the context of batching, we may be able to coalesce writes to different tables hosted on the same server into the same RPC.</p>
<p><a class="el" href="classkudu_1_1client_1_1KuduSession.html" title="Representation of a Kudu client session. ">KuduSession</a> is separate from <a class="el" href="classkudu_1_1client_1_1KuduClient.html" title="A handle for a connection to a cluster. ">KuduClient</a> because, in a multi-threaded application, different threads may need to concurrently execute transactions. Similar to a JDBC "session", transaction boundaries will be delineated on a per-session basis &ndash; in between a "BeginTransaction" and "Commit" call on a given session, all operations will be part of the same transaction. Meanwhile another concurrent Session object can safely run non-transactional work or other transactions without interfering.</p>
<p>Additionally, there is a guarantee that writes from different sessions do not get batched together into the same RPCs &ndash; this means that latency-sensitive clients can run through the same <a class="el" href="classkudu_1_1client_1_1KuduClient.html" title="A handle for a connection to a cluster. ">KuduClient</a> object as throughput-oriented clients, perhaps by setting the latency-sensitive session's timeouts low and priorities high. Without the separation of batches, a latency-sensitive single-row insert might get batched along with 10MB worth of inserts from the batch writer, thus delaying the response significantly.</p>
<p>Though we currently do not have transactional support, users will be forced to use a <a class="el" href="classkudu_1_1client_1_1KuduSession.html" title="Representation of a Kudu client session. ">KuduSession</a> to instantiate reads as well as writes. This will make it more straight-forward to add RW transactions in the future without significant modifications to the API.</p>
<p>Users who are familiar with the Hibernate ORM framework should find this concept of a Session familiar.</p>
<dl class="section note"><dt>Note</dt><dd>This class is not thread-safe except where otherwise specified. </dd></dl>
</div><h2 class="groupheader">Member Enumeration Documentation</h2>
<a class="anchor" id="aabd55109ba3b086bbe33b277cdd40d22"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">enum <a class="el" href="classkudu_1_1client_1_1KuduSession.html#aabd55109ba3b086bbe33b277cdd40d22">kudu::client::KuduSession::ExternalConsistencyMode</a></td>
</tr>
</table>
</div><div class="memdoc">
<p>The possible external consistency modes on which Kudu operates. </p>
<table class="fieldtable">
<tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><em><a class="anchor" id="aabd55109ba3b086bbe33b277cdd40d22ae978fab7451faebf4399830b603c855c"></a>CLIENT_PROPAGATED</em>&#160;</td><td class="fielddoc">
<p>The response to any write will contain a timestamp. Any further calls from the same client to other servers will update those servers with that timestamp. Following write operations from the same client will be assigned timestamps that are strictly higher, enforcing external consistency without having to wait or incur any latency penalties.</p>
<p>In order to maintain external consistency for writes between two different clients in this mode, the user must forward the timestamp from the first client to the second by using <a class="el" href="classkudu_1_1client_1_1KuduClient.html#a3a671b3540c74ef7c358bb98e95031e0">KuduClient::GetLatestObservedTimestamp()</a> and <a class="el" href="classkudu_1_1client_1_1KuduClient.html#a0809b055eda76fd68988462f2a9791dd">KuduClient::SetLatestObservedTimestamp()</a>.</p>
<p>This is the default external consistency mode.</p>
<dl class="section warning"><dt>Warning</dt><dd>Failure to propagate timestamp information through back-channels between two different clients will negate any external consistency guarantee under this mode. </dd></dl>
</td></tr>
<tr><td class="fieldname"><em><a class="anchor" id="aabd55109ba3b086bbe33b277cdd40d22a70010f3ef1f70b99b02328c024c436c9"></a>COMMIT_WAIT</em>&#160;</td><td class="fielddoc">
<p>The server will guarantee that write operations from the same or from other client are externally consistent, without the need to propagate timestamps across clients. This is done by making write operations wait until there is certainty that all follow up write operations (operations that start after the previous one finishes) will be assigned a timestamp that is strictly higher, enforcing external consistency.</p>
<dl class="section warning"><dt>Warning</dt><dd>Depending on the clock synchronization state of TabletServers this may imply considerable latency. Moreover operations in <code>COMMIT_WAIT</code> external consistency mode will outright fail if TabletServer clocks are either unsynchronized or synchronized but with a maximum error which surpasses a pre-configured threshold. </dd></dl>
</td></tr>
</table>
</div>
</div>
<a class="anchor" id="aaec3956e642610d703f3b83b78e24e19"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">enum <a class="el" href="classkudu_1_1client_1_1KuduSession.html#aaec3956e642610d703f3b83b78e24e19">kudu::client::KuduSession::FlushMode</a></td>
</tr>
</table>
</div><div class="memdoc">
<p>Modes of flush operations. </p>
<table class="fieldtable">
<tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><em><a class="anchor" id="aaec3956e642610d703f3b83b78e24e19ad74b76e407e62ca951d369521636df2b"></a>AUTO_FLUSH_SYNC</em>&#160;</td><td class="fielddoc">
<p>Every write will be sent to the server in-band with the <a class="el" href="classkudu_1_1client_1_1KuduSession.html#ad3f7324b27fca298c5ca3d07b4741943">Apply()</a> call. No batching will occur. In this mode, the <a class="el" href="classkudu_1_1client_1_1KuduSession.html#a64955abb5f5cc821b6e56354f733ce84">Flush()</a> call never has any effect, since each <a class="el" href="classkudu_1_1client_1_1KuduSession.html#ad3f7324b27fca298c5ca3d07b4741943">Apply()</a> call has already flushed the buffer. This is the default flush mode. </p>
</td></tr>
<tr><td class="fieldname"><em><a class="anchor" id="aaec3956e642610d703f3b83b78e24e19a520b8eef7ef0fd149b2757faf43972b1"></a>AUTO_FLUSH_BACKGROUND</em>&#160;</td><td class="fielddoc">
<p><a class="el" href="classkudu_1_1client_1_1KuduSession.html#ad3f7324b27fca298c5ca3d07b4741943">Apply()</a> calls will return immediately, but the writes will be sent in the background, potentially batched together with other writes from the same session. If there is not sufficient buffer space, then <a class="el" href="classkudu_1_1client_1_1KuduSession.html#ad3f7324b27fca298c5ca3d07b4741943">Apply()</a> will block for buffer space to be available.</p>
<p>Because writes are applied in the background, any errors will be stored in a session-local buffer. Call <a class="el" href="classkudu_1_1client_1_1KuduSession.html#a277c213a68679c6b0d5c432919eb9198">CountPendingErrors()</a> or <a class="el" href="classkudu_1_1client_1_1KuduSession.html#ad5e3521623338de49cfd62914bdcb2f7">GetPendingErrors()</a> to retrieve them.</p>
<p>The <a class="el" href="classkudu_1_1client_1_1KuduSession.html#a64955abb5f5cc821b6e56354f733ce84">Flush()</a> call can be used to block until the buffer is empty.</p>
<dl class="section warning"><dt>Warning</dt><dd>This is not implemented yet, see KUDU-456</dd></dl>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000006">Todo:</a></b></dt><dd>Provide an API for the user to specify a callback to do their own error reporting.</dd></dl>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000007">Todo:</a></b></dt><dd>Specify which threads the background activity runs on (probably the messenger IO threads?). </dd></dl>
</td></tr>
<tr><td class="fieldname"><em><a class="anchor" id="aaec3956e642610d703f3b83b78e24e19a1db3efc2094da09aae45bb68475cdb4a"></a>MANUAL_FLUSH</em>&#160;</td><td class="fielddoc">
<p><a class="el" href="classkudu_1_1client_1_1KuduSession.html#ad3f7324b27fca298c5ca3d07b4741943">Apply()</a> calls will return immediately, and the writes will not be sent until the user calls <a class="el" href="classkudu_1_1client_1_1KuduSession.html#a64955abb5f5cc821b6e56354f733ce84">Flush()</a>. If the buffer runs past the configured space limit, then <a class="el" href="classkudu_1_1client_1_1KuduSession.html#ad3f7324b27fca298c5ca3d07b4741943">Apply()</a> will return an error. </p>
</td></tr>
</table>
</div>
</div>
<h2 class="groupheader">Member Function Documentation</h2>
<a class="anchor" id="ad3f7324b27fca298c5ca3d07b4741943"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classkudu_1_1Status.html">Status</a> kudu::client::KuduSession::Apply </td>
<td>(</td>
<td class="paramtype"><a class="el" href="classkudu_1_1client_1_1KuduWriteOperation.html">KuduWriteOperation</a> *&#160;</td>
<td class="paramname"><em>write_op</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000004">Todo:</a></b></dt><dd>Add "doAs" ability here for proxy servers to be able to act on behalf of other users, assuming access rights. </dd></dl>
<p>Apply the write operation.</p>
<p>The behavior of this function depends on the current flush mode. Regardless of flush mode, however, <a class="el" href="classkudu_1_1client_1_1KuduSession.html#ad3f7324b27fca298c5ca3d07b4741943">Apply()</a> may begin to perform processing in the background for the call (e.g. looking up the tablet, etc). Given that, an error may be queued into the PendingErrors structure prior to flushing, even in <code>MANUAL_FLUSH</code> mode.</p>
<p>In case of any error, which may occur during flushing or because the write_op is malformed, the write_op is stored in the session's error collector which may be retrieved at any time.</p>
<dl class="section note"><dt>Note</dt><dd>This method is thread safe.</dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">write_op</td><td>Operation to apply. This method transfers the write_op's ownership to the <a class="el" href="classkudu_1_1client_1_1KuduSession.html" title="Representation of a Kudu client session. ">KuduSession</a>. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Operation result status. </dd></dl>
</div>
</div>
<a class="anchor" id="a507e940962fdf08ee232534f73792b79"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void kudu::client::KuduSession::ApplyAsync </td>
<td>(</td>
<td class="paramtype"><a class="el" href="classkudu_1_1client_1_1KuduWriteOperation.html">KuduWriteOperation</a> *&#160;</td>
<td class="paramname"><em>write_op</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="classkudu_1_1client_1_1KuduStatusCallback.html">KuduStatusCallback</a> *&#160;</td>
<td class="paramname"><em>cb</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Apply the write operation asynchronously.</p>
<p>This method is similar to <a class="el" href="classkudu_1_1client_1_1KuduSession.html#ad3f7324b27fca298c5ca3d07b4741943">Apply()</a>, except it never blocks. Even in the flush modes that return immediately, <code>cb</code> is triggered with the result. The callback may be called by a reactor thread, or in some cases may be called inline by the same thread which calls <a class="el" href="classkudu_1_1client_1_1KuduSession.html#a507e940962fdf08ee232534f73792b79">ApplyAsync()</a>.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">write_op</td><td>Operation to apply. This method transfers the write_op's ownership to the <a class="el" href="classkudu_1_1client_1_1KuduSession.html" title="Representation of a Kudu client session. ">KuduSession</a>. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">cb</td><td>Callback to report the status of the operation. The <code>cb</code> object must remain valid until it is called.</td></tr>
</table>
</dd>
</dl>
<dl class="section warning"><dt>Warning</dt><dd>Not yet implemented. </dd></dl>
</div>
</div>
<a class="anchor" id="a4ed0bac1edcbba612d7de41e8c8adfd5"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classkudu_1_1client_1_1KuduClient.html">KuduClient</a>* kudu::client::KuduSession::client </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td> const</td>
</tr>
</table>
</div><div class="memdoc">
<dl class="section return"><dt>Returns</dt><dd>Client for the session: pointer to the associated client object. </dd></dl>
</div>
</div>
<a class="anchor" id="aa5204844e361ecc3068fbc4e02fd4436"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classkudu_1_1Status.html">Status</a> kudu::client::KuduSession::Close </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<dl class="section return"><dt>Returns</dt><dd><a class="el" href="classkudu_1_1Status.html" title="A representation of an operation&#39;s outcome. ">Status</a> of the session closure. In particular, an error is returned if there are unflushed or in-flight operations. </dd></dl>
</div>
</div>
<a class="anchor" id="a10edb757e362792454f0974e644109ab"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kudu::client::KuduSession::CountBufferedOperations </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td> const</td>
</tr>
</table>
</div><div class="memdoc">
<p>Get number of buffered operations (not the same as 'pending').</p>
<p>Note that this is different than <a class="el" href="classkudu_1_1client_1_1KuduSession.html#a3f224e9b95f86da7e1f2ea6fcf327756">HasPendingOperations()</a> above, which includes operations which have been sent and not yet responded to. This is only relevant in <code>MANUAL_FLUSH</code> mode, where the result will not decrease except for after a manual flush, after which point it will be 0. In the other flush modes, data is immediately put en-route to the destination, so this will return 0.</p>
<dl class="section note"><dt>Note</dt><dd>This function is thread-safe.</dd></dl>
<dl class="section return"><dt>Returns</dt><dd>The number of buffered operations. These are operations that have not yet been flushed &ndash; i.e. they are not en-route yet. </dd></dl>
</div>
</div>
<a class="anchor" id="a277c213a68679c6b0d5c432919eb9198"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kudu::client::KuduSession::CountPendingErrors </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td> const</td>
</tr>
</table>
</div><div class="memdoc">
<p>Get error count for pending operations.</p>
<p>Errors may accumulate in session's lifetime; use this method to see how many errors happened since last call of <a class="el" href="classkudu_1_1client_1_1KuduSession.html#ad5e3521623338de49cfd62914bdcb2f7">GetPendingErrors()</a> method.</p>
<dl class="section note"><dt>Note</dt><dd>This function is thread-safe.</dd></dl>
<dl class="section return"><dt>Returns</dt><dd>Total count of errors accumulated during the session. </dd></dl>
</div>
</div>
<a class="anchor" id="a64955abb5f5cc821b6e56354f733ce84"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classkudu_1_1Status.html">Status</a> kudu::client::KuduSession::Flush </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Flush any pending writes.</p>
<p>In <code>AUTO_FLUSH_SYNC</code> mode, this has no effect, since every <a class="el" href="classkudu_1_1client_1_1KuduSession.html#ad3f7324b27fca298c5ca3d07b4741943">Apply()</a> call flushes itself inline.</p>
<dl class="section note"><dt>Note</dt><dd>This function is thread-safe.</dd></dl>
<dl class="section return"><dt>Returns</dt><dd>Operation result status. In particular, returns a non-OK status if there are any pending errors after the rows have been flushed. Callers should then use GetPendingErrors to determine which specific operations failed. </dd></dl>
</div>
</div>
<a class="anchor" id="ad8c68570479e95b325d8a5437eef8731"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void kudu::client::KuduSession::FlushAsync </td>
<td>(</td>
<td class="paramtype"><a class="el" href="classkudu_1_1client_1_1KuduStatusCallback.html">KuduStatusCallback</a> *&#160;</td>
<td class="paramname"><em>cb</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Flush any pending writes asynchronously.</p>
<p>This method schedules a background flush of pending operations. Provided callback is invoked upon completion of the flush. If there were errors while flushing the operations, corresponding 'not OK' status is passed as a parameter for the callback invocation. Callers should then use <a class="el" href="classkudu_1_1client_1_1KuduSession.html#ad5e3521623338de49cfd62914bdcb2f7">GetPendingErrors()</a> to determine which specific operations failed.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">cb</td><td>Callback to call upon flush completion. The <code>cb</code> must remain valid until it is invoked.</td></tr>
</table>
</dd>
</dl>
<p>In the case that the async version of this method is used, then the callback will be called upon completion of the operations which were buffered since the last flush. In other words, in the following sequence: </p>
<div class="fragment"><div class="line">session-&gt;Insert(a);</div>
<div class="line">session-&gt;FlushAsync(callback_1);</div>
<div class="line">session-&gt;Insert(b);</div>
<div class="line">session-&gt;FlushAsync(callback_2);</div>
</div><!-- fragment --><p> ... <code>callback_2</code> will be triggered once <code>b</code> has been inserted, regardless of whether <code>a</code> has completed or not.</p>
<dl class="section note"><dt>Note</dt><dd>This also means that, if FlushAsync is called twice in succession, with no intervening operations, the second flush will return immediately. For example: <div class="fragment"><div class="line">session-&gt;Insert(a);</div>
<div class="line">session-&gt;FlushAsync(callback_1); <span class="comment">// called when &#39;a&#39; is inserted</span></div>
<div class="line">session-&gt;FlushAsync(callback_2); <span class="comment">// called immediately!</span></div>
</div><!-- fragment --> Note that, as in all other async functions in Kudu, the callback may be called either from an IO thread or the same thread which calls FlushAsync. The callback should not block. </dd></dl>
</div>
</div>
<a class="anchor" id="ad5e3521623338de49cfd62914bdcb2f7"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void kudu::client::KuduSession::GetPendingErrors </td>
<td>(</td>
<td class="paramtype">std::vector&lt; <a class="el" href="classkudu_1_1client_1_1KuduError.html">KuduError</a> * &gt; *&#160;</td>
<td class="paramname"><em>errors</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">bool *&#160;</td>
<td class="paramname"><em>overflowed</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Get information on errors from previous session activity.</p>
<p>The information on errors are reset upon calling this method.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[out]</td><td class="paramname">errors</td><td>Pointer to the container to fill with error info objects. Caller takes ownership of the returned errors in the container. </td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">overflowed</td><td>If there were more errors than could be held in the session's error storage, then <code>overflowed</code> is set to <code>true</code>.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>This function is thread-safe. </dd></dl>
</div>
</div>
<a class="anchor" id="a3f224e9b95f86da7e1f2ea6fcf327756"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">bool kudu::client::KuduSession::HasPendingOperations </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td> const</td>
</tr>
</table>
</div><div class="memdoc">
<p>Check if there are any pending operations in this session.</p>
<dl class="section note"><dt>Note</dt><dd>This function is thread-safe.</dd></dl>
<dl class="section return"><dt>Returns</dt><dd><code>true</code> if there are operations which have not yet been delivered to the cluster. This may include buffered operations (i.e. those that have not yet been flushed) as well as in-flight operations (i.e. those that are in the process of being sent to the servers).</dd></dl>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000005">Todo:</a></b></dt><dd>Maybe "incomplete" or "undelivered" is clearer? </dd></dl>
</div>
</div>
<a class="anchor" id="a56d1c7f47dfcaf5121b15a4435a8eeca"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classkudu_1_1Status.html">Status</a> kudu::client::KuduSession::SetExternalConsistencyMode </td>
<td>(</td>
<td class="paramtype"><a class="el" href="classkudu_1_1client_1_1KuduSession.html#aabd55109ba3b086bbe33b277cdd40d22">ExternalConsistencyMode</a>&#160;</td>
<td class="paramname"><em>m</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Set external consistency mode for the session.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">m</td><td>External consistency mode to set. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Operation result status. </dd></dl>
</div>
</div>
<a class="anchor" id="a83555781b5a037f87c215e565ecf1a8f"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classkudu_1_1Status.html">Status</a> kudu::client::KuduSession::SetFlushMode </td>
<td>(</td>
<td class="paramtype"><a class="el" href="classkudu_1_1client_1_1KuduSession.html#aaec3956e642610d703f3b83b78e24e19">FlushMode</a>&#160;</td>
<td class="paramname"><em>m</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Set the flush mode.</p>
<dl class="section pre"><dt>Precondition</dt><dd>There should be no pending writes &ndash; call <a class="el" href="classkudu_1_1client_1_1KuduSession.html#a64955abb5f5cc821b6e56354f733ce84">Flush()</a> first to ensure nothing is pending.</dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">m</td><td>Flush mode to set. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Operation status. </dd></dl>
</div>
</div>
<a class="anchor" id="aefa9bbc51c27104ce103b9ecda3b8abf"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classkudu_1_1Status.html">Status</a> kudu::client::KuduSession::SetMutationBufferSpace </td>
<td>(</td>
<td class="paramtype">size_t&#160;</td>
<td class="paramname"><em>size_bytes</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Set the amount of buffer space used by this session for outbound writes.</p>
<p>The effect of the buffer size varies based on the flush mode of the session: </p>
<ul>
<li>AUTO_FLUSH_SYNC since no buffering is done, this has no effect. </li>
<li>AUTO_FLUSH_BACKGROUND if the buffer space is exhausted, then write calls will block until there is space available in the buffer. </li>
<li>MANUAL_FLUSH if the buffer space is exhausted, then write calls will return an error</li>
</ul>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">size_bytes</td><td>Size of the buffer space to set (number of bytes). </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Operation result status. </dd></dl>
</div>
</div>
<a class="anchor" id="a25b22362650d7120f59cc1025e40bd79"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void kudu::client::KuduSession::SetTimeoutMillis </td>
<td>(</td>
<td class="paramtype">int&#160;</td>
<td class="paramname"><em>millis</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Set the timeout for writes made in this session.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">millis</td><td>Timeout to set in milliseconds; should be greater than 0. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<hr/>The documentation for this class was generated from the following file:<ul>
<li>include/kudu/client/<a class="el" href="client_8h_source.html">client.h</a></li>
</ul>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Mon Aug 22 2016 17:03:49 for Kudu C++ client API by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.6
</small></address>
</body>
</html>