1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
<!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"/>
<title>WiredTiger: Asynchronous operations in Java</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="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="wiredtiger.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="projectlogo"><a href="http://wiredtiger.com/"><img alt="Logo" src="LogoFinal-header.png" alt="WiredTiger" /></a></td>
<td style="padding-left: 0.5em;">
<div id="projectname">
 <span id="projectnumber">Version 3.2.1</span>
</div>
<div id="projectbrief"><!-- 3.2.1 --></div>
</td>
</tr>
</tbody>
</table>
</div>
<div class="banner">
<a href="https://github.com/wiredtiger/wiredtiger">Fork me on GitHub</a>
<a class="last" href="http://groups.google.com/group/wiredtiger-users">Join my user group</a>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',false,false,'search.php','Search');
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('async_lang_java.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Asynchronous operations in Java </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>WiredTiger supports asynchronous operations; as an example of where this can be useful, a server application handling requests from a network as fast as possible may want its worker threads to initiate a unit of work and then immediately respond to the next request, rather than waiting for the results of the first request.</p>
<p>WiredTiger supports asynchronous operations through the AsyncOp handle. The work unit represented by the AsyncOp handle is queued by the application and performed by an internal WiredTiger worker thread. When the work unit completes, the WiredTiger thread makes a callback to notify the application the operation is finished, along with providing any results and error values.</p>
<p>The asynchronous operation handle operates in a manner similar to a Cursor handle. An asynchronous operation includes:</p>
<ul>
<li>getter/setters for key and value fields</li>
<li>encoding of fields to store in the data source</li>
<li>methods to modify and retrieve specific data (for example, insert and update)</li>
<li>a method to compact a table</li>
</ul>
<p>The AsyncOp handle does not survive after the callback function returns into the WiredTiger library. When the application callback returns the handle is returned to the system pool. The application callback must copy out any key, value or other information that it needs before the callback function returns.</p>
<h1><a class="anchor" id="async_config_lang_java"></a>
Configuring asynchronous operations</h1>
<p>To perform asynchronous operations, the application must first include the <code>async</code> configuration option when <code>wiredtiger.open</code> is called. Additional configuration parameters include the number of WiredTiger worker threads created to handle the incoming queue of operations and the maximum number of simultaneous asynchronous operations that are expected.</p>
<p>For example, the following configures an application for asynchronous operations, with a maximum of 10 asynchronous operations and 2 supporting threads:</p>
<div class="fragment"><div class="line"> conn = wiredtiger.open(home, <span class="stringliteral">"create,cache_size=100MB,"</span> +</div><div class="line"> <span class="stringliteral">"async=(enabled=true,ops_max=20,threads=2)"</span>);</div></div><!-- fragment --><p> If the number of requests exceeds the configured maximum number, a AsyncOp handle won't immediately be available and an error will be returned to the application when it attempts to allocate a handle. If the number of configured worker threads are unable to keep up with the requests, requests will be forced to wait for worker threads to become available.</p>
<h1><a class="anchor" id="async_alloc_lang_java"></a>
Allocating an asynchronous operations handle</h1>
<p>A AsyncOp handle is allocated using the Connection.async_new_op method. This method takes an existing object URI and a callback. For example:</p>
<div class="fragment"><div class="line"> op = tryAsyncNewOp(conn, <span class="stringliteral">"table:async"</span>, null, asynciface);</div></div><!-- fragment --><p> To aid the application in matching up an asynchronous operation with a subsequent call to the callback function, every handle contains a unique <code>uint64_t</code> identifier and AsyncOpType type. The <code>identifier</code> is assigned when the handle is allocated and the <code>type</code> is assigned when the asynchronous operation is queued.</p>
<p>To retrieve the id, use the AsyncOp.get_id method:</p>
<div class="fragment"><div class="line"> <span class="comment">/* Retrieve the operation's 64-bit identifier. */</span></div><div class="line"> <span class="keywordtype">long</span> <span class="keywordtype">id</span> = op.getId();</div></div><!-- fragment --><p> To retrieve the AsyncOpType type, use the AsyncOp.get_type method:</p>
<div class="fragment"><div class="line"> <span class="comment">/* Retrieve the operation's type. */</span></div><div class="line"> AsyncOpType optype = op.getType();</div></div><!-- fragment --><p> WiredTiger only allows a limited number of method calls back into the library using the AsyncOp handle, while in the callback function. The application is allowed to retrieve than handle's key, value, identifier and the operation type from the AsyncOp handle.</p>
<p>Here is a complete example callback function implementation, from the example program ex_async.java:</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>AsyncKeys <span class="keyword">implements</span> AsyncCallback {</div><div class="line"></div><div class="line"> <span class="keyword">public</span> <span class="keywordtype">int</span> numKeys = 0;</div><div class="line"></div><div class="line"> <span class="keyword">public</span> AsyncKeys() {}</div><div class="line"></div><div class="line"> <span class="keyword">public</span> <span class="keywordtype">void</span> notifyError(String desc) {</div><div class="line"> System.err.println(<span class="stringliteral">"ERROR: notify: "</span> + desc);</div><div class="line"> }</div><div class="line"></div><div class="line"> <span class="keyword">public</span> <span class="keywordtype">int</span> notify(AsyncOp op, <span class="keywordtype">int</span> opReturn, <span class="keywordtype">int</span> flags) {</div><div class="line"> <span class="comment">/*</span></div><div class="line"><span class="comment"> * Note: we are careful not to throw any errors here. Any</span></div><div class="line"><span class="comment"> * exceptions would be swallowed by a native worker thread.</span></div><div class="line"><span class="comment"> */</span></div><div class="line"> <span class="keywordtype">int</span> ret = 0;</div><div class="line"> <span class="keywordflow">try</span> {</div><div class="line"> <span class="comment">/* Retrieve the operation's type. */</span></div><div class="line"> AsyncOpType optype = op.getType();</div><div class="line"> <span class="comment">/* Retrieve the operation's 64-bit identifier. */</span></div><div class="line"> <span class="keywordtype">long</span> <span class="keywordtype">id</span> = op.getId();</div><div class="line"> <span class="comment">/* If doing a search, retrieve the key/value pair. */</span></div><div class="line"> <span class="keywordflow">if</span> (optype == AsyncOpType.WT_AOP_SEARCH) {</div><div class="line"> String key = op.getKeyString();</div><div class="line"> String value = op.getValueString();</div><div class="line"> <span class="keyword">synchronized</span> (<span class="keyword">this</span>) {</div><div class="line"> numKeys += 1;</div><div class="line"> }</div><div class="line"> System.out.println(<span class="stringliteral">"Id "</span> + <span class="keywordtype">id</span> + <span class="stringliteral">" got record: "</span> + key +</div><div class="line"> <span class="stringliteral">" : "</span> + value);</div><div class="line"> }</div><div class="line"> }</div><div class="line"> <span class="keywordflow">catch</span> (Exception e) {</div><div class="line"> System.err.println(<span class="stringliteral">"ERROR: exception in notify: "</span> + e.toString() +</div><div class="line"> <span class="stringliteral">", opreturn="</span> + opReturn);</div><div class="line"> ret = 1;</div><div class="line"> }</div><div class="line"> <span class="keywordflow">return</span> (ret);</div><div class="line"> }</div><div class="line">}</div></div><!-- fragment --> <div class="fragment"><div class="line"> AsyncKeys asynciface = <span class="keyword">new</span> AsyncKeys();</div></div><!-- fragment --> <h1><a class="anchor" id="async_operations_lang_java"></a>
Executing asynchronous operations</h1>
<p>The AsyncOp handle behaves similarly to the Cursor handle, that is, the key and value are initialized and then an operation is performed.</p>
<p>For example, the following code does an asynchronous insert into the table:</p>
<div class="fragment"><div class="line"> <span class="comment">/*</span></div><div class="line"><span class="comment"> * Set the operation's string key and value, and then do</span></div><div class="line"><span class="comment"> * an asynchronous insert.</span></div><div class="line"><span class="comment"> */</span></div><div class="line"> k[i] = <span class="stringliteral">"key"</span> + i;</div><div class="line"> op.putKeyString(k[i]);</div><div class="line"> v[i] = <span class="stringliteral">"value"</span> + i;</div><div class="line"> op.putValueString(v[i]);</div><div class="line"> ret = op.insert();</div></div><!-- fragment --><p> For example, the following code does an asynchronous search of the table:</p>
<div class="fragment"><div class="line"> <span class="comment">/*</span></div><div class="line"><span class="comment"> * Set the operation's string key and value, and then do</span></div><div class="line"><span class="comment"> * an asynchronous search.</span></div><div class="line"><span class="comment"> */</span></div><div class="line"> k[i] = <span class="stringliteral">"key"</span> + i;</div><div class="line"> op.putKeyString(k[i]);</div><div class="line"> ret = op.search();</div></div><!-- fragment --><p> When a database contains multiple tables, it may be desired to compact several tables in parallel without having to manage separate threads to each call Session.compact. Alternatively, compacting several tables serially may take much longer. The AsyncOp.compact method allows the application to compact multiple objects asynchronously.</p>
<div class="fragment"><div class="line"> <span class="comment">/*</span></div><div class="line"><span class="comment"> * Compact a table asynchronously, limiting the run-time to 5 minutes.</span></div><div class="line"><span class="comment"> */</span></div><div class="line"> op = tryAsyncNewOp(conn, <span class="stringliteral">"table:async"</span>, <span class="stringliteral">"timeout=300"</span>, asynciface);</div><div class="line"> ret = op.compact();</div></div><!-- fragment --> <h1><a class="anchor" id="async_flush_lang_java"></a>
Waiting for outstanding operations to complete</h1>
<p>The Connection.async_flush method can be used to wait for all previous operations to complete. When that call returns, all previously queued operations are guaranteed to have been completed and their callback functions have returned.</p>
<div class="fragment"><div class="line"> <span class="comment">/* Wait for all outstanding operations to complete. */</span></div><div class="line"> ret = conn.async_flush();</div></div><!-- fragment --><p> Because Connection.close implicitly does a Connection.async_flush, the call is not required in all applications.</p>
<h1><a class="anchor" id="async_transactions_lang_java"></a>
Asynchronous operations and transactions</h1>
<p>Each asynchronous worker thread operates in its own session, executing a single asynchronous operation with the context of the session's transaction. Therefore, there is no way to combine multiple, related updates into a single transaction when using asynchronous operations.</p>
<p>The transaction is committed if the operation was successful and the application callback returns success, otherwise the transaction is rolled back. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a class="el" href="index.html">Reference Guide</a></li><li class="navelem"><a class="el" href="programming_lang_java.html">Writing WiredTiger applications in Java</a></li>
<li class="footer">Copyright (c) 2008-2019 MongoDB, Inc. All rights reserved. Contact <a href="mailto:info@wiredtiger.com">info@wiredtiger.com</a> for more information.</li>
</ul>
</div>
</body>
</html>
|
