-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy patherror_handling.html
174 lines (174 loc) · 14.1 KB
/
error_handling.html
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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
<!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: Error handling</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);
$(window).load(resizeHeight);
</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 2.9.2</span>
</div>
<div id="projectbrief"><!-- 2.9.2 --></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.10 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="examples.html"><span>Examples</span></a></li>
<li><a href="community.html"><span>Community</span></a></li>
<li><a href="license.html"><span>License</span></a></li>
</ul>
</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('error_handling.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Error handling </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>WiredTiger operations return a value of 0 on success and a non-zero value on error. Error codes may be either positive or negative: positive error codes are standard error codes as described for POSIX-like systems (for example, EINVAL or EBUSY), negative error codes are WiredTiger-specific (for example, WT_ROLLBACK).</p>
<p>WiredTiger-specific error codes always appear in the -31,800 to -31,999 range.</p>
<p>The following is a list of possible WiredTiger-specific errors:</p>
<dl class="section user"><dt>WT_ROLLBACK</dt><dd>This error is generated when an operation cannot be completed due to a conflict with concurrent operations. The operation may be retried; if a transaction is in progress, it should be rolled back and the operation retried in a new transaction.</dd></dl>
<dl class="section user"><dt>WT_DUPLICATE_KEY</dt><dd>This error is generated when the application attempts to insert a record with the same key as an existing record without the 'overwrite' configuration to <a class="el" href="struct_w_t___s_e_s_s_i_o_n.html#afb5b4a69c2c5cafe411b2b04fdc1c75d" title="Open a new cursor on a data source or duplicate an existing cursor. ">WT_SESSION::open_cursor</a>.</dd></dl>
<dl class="section user"><dt>WT_ERROR</dt><dd>This error is returned when an error is not covered by a specific error return.</dd></dl>
<dl class="section user"><dt>WT_NOTFOUND</dt><dd>This error indicates an operation did not find a value to return. This includes cursor search and other operations where no record matched the cursor's search key such as <a class="el" href="struct_w_t___c_u_r_s_o_r.html#a444cdc0952e7f8d55d23173516c7037f" title="Update an existing record and optionally insert a record. ">WT_CURSOR::update</a> or <a class="el" href="struct_w_t___c_u_r_s_o_r.html#abbba24fe607fee519c4c9c4669cd4455" title="Remove a record. ">WT_CURSOR::remove</a>.</dd></dl>
<dl class="section user"><dt>WT_PANIC</dt><dd>This error indicates an underlying problem that requires the application exit and restart. The application can exit immediately when <code>WT_PANIC</code> is returned from a WiredTiger interface, no further WiredTiger calls are required.</dd></dl>
<dl class="section user"><dt>WT_RUN_RECOVERY</dt><dd>This error is generated when wiredtiger_open is configured to return an error if recovery is required to use the database.</dd></dl>
<dl class="section user"><dt>WT_CACHE_FULL</dt><dd>This error is only generated when wiredtiger_open is configured to run in-memory, and an insert or update operation requires more than the configured cache size to complete. The operation may be retried; if a transaction is in progress, it should be rolled back and the operation retried in a new transaction.</dd></dl>
<h1><a class="anchor" id="error_translation"></a>
Translating errors</h1>
<p>The <a class="el" href="struct_w_t___s_e_s_s_i_o_n.html#abe03ccb716e097ed1bb4d42eb733c1f9" title="Return information about an error as a string. ">WT_SESSION::strerror</a> and <a class="el" href="group__wt.html#gae8bf720ddb4a7a7390b70424594c40fd" title="Return information about a WiredTiger error as a string (see WT_SESSION::strerror for a thread-safe A...">wiredtiger_strerror</a> functions return the standard text message associated with any WiredTiger, ISO C, or POSIX standard API.</p>
<div class="fragment"><div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> *key = <span class="stringliteral">"non-existent key"</span>;</div>
<div class="line"> cursor->set_key(cursor, key);</div>
<div class="line"> <span class="keywordflow">if</span> ((ret = cursor->remove(cursor)) != 0) {</div>
<div class="line"> fprintf(stderr,</div>
<div class="line"> <span class="stringliteral">"cursor.remove: %s\n"</span>,</div>
<div class="line"> cursor->session->strerror(cursor->session, ret));</div>
<div class="line"> <span class="keywordflow">return</span> (ret);</div>
<div class="line"> }</div>
</div><!-- fragment --> <div class="fragment"><div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> *key = <span class="stringliteral">"non-existent key"</span>;</div>
<div class="line"> cursor->set_key(cursor, key);</div>
<div class="line"> <span class="keywordflow">if</span> ((ret = cursor->remove(cursor)) != 0) {</div>
<div class="line"> fprintf(stderr,</div>
<div class="line"> <span class="stringliteral">"cursor.remove: %s\n"</span>, <a class="code" href="group__wt.html#gae8bf720ddb4a7a7390b70424594c40fd">wiredtiger_strerror</a>(ret));</div>
<div class="line"> <span class="keywordflow">return</span> (ret);</div>
<div class="line"> }</div>
</div><!-- fragment --><p> Note that <a class="el" href="group__wt.html#gae8bf720ddb4a7a7390b70424594c40fd" title="Return information about a WiredTiger error as a string (see WT_SESSION::strerror for a thread-safe A...">wiredtiger_strerror</a> is not thread-safe.</p>
<h1><a class="anchor" id="error_handling_event"></a>
Error handling using the WT_EVENT_HANDLER</h1>
<p>More complex error handling can be configured by passing an implementation of <a class="el" href="struct_w_t___e_v_e_n_t___h_a_n_d_l_e_r.html" title="The interface implemented by applications to handle error, informational and progress messages...">WT_EVENT_HANDLER</a> to <a class="el" href="group__wt.html#ga9e6adae3fc6964ef837a62795c7840ed" title="Open a connection to a database. ">wiredtiger_open</a> or <a class="el" href="struct_w_t___c_o_n_n_e_c_t_i_o_n.html#afc75c44ff4497627c59d9b6aaa64c9d8" title="Open a session. ">WT_CONNECTION::open_session</a>.</p>
<p>For example, both informational and error messages might be passed to an application-specific logging function that added a timestamp and logged the message to a file, and error messages might additionally be output to the <code>stderr</code> file stream.</p>
<div class="fragment"><div class="line"><span class="comment">/*</span></div>
<div class="line"><span class="comment"> * Create our own event handler structure to allow us to pass context through</span></div>
<div class="line"><span class="comment"> * to event handler callbacks. For this to work the WiredTiger event handler</span></div>
<div class="line"><span class="comment"> * must appear first in our custom event handler structure.</span></div>
<div class="line"><span class="comment"> */</span></div>
<div class="line"><span class="keyword">typedef</span> <span class="keyword">struct </span>{</div>
<div class="line"> <a class="code" href="struct_w_t___e_v_e_n_t___h_a_n_d_l_e_r.html">WT_EVENT_HANDLER</a> h;</div>
<div class="line"> <span class="keyword">const</span> <span class="keywordtype">char</span> *app_id;</div>
<div class="line">} CUSTOM_EVENT_HANDLER;</div>
<div class="line"></div>
<div class="line"><span class="comment">/*</span></div>
<div class="line"><span class="comment"> * handle_wiredtiger_error --</span></div>
<div class="line"><span class="comment"> * Function to handle error callbacks from WiredTiger.</span></div>
<div class="line"><span class="comment"> */</span></div>
<div class="line"><span class="keywordtype">int</span></div>
<div class="line">handle_wiredtiger_error(<a class="code" href="struct_w_t___e_v_e_n_t___h_a_n_d_l_e_r.html">WT_EVENT_HANDLER</a> *handler,</div>
<div class="line"> <a class="code" href="struct_w_t___s_e_s_s_i_o_n.html">WT_SESSION</a> *session, <span class="keywordtype">int</span> error, <span class="keyword">const</span> <span class="keywordtype">char</span> *message)</div>
<div class="line">{</div>
<div class="line"> CUSTOM_EVENT_HANDLER *custom_handler;</div>
<div class="line"></div>
<div class="line"> <span class="comment">/* Cast the handler back to our custom handler. */</span></div>
<div class="line"> custom_handler = (CUSTOM_EVENT_HANDLER *)handler;</div>
<div class="line"></div>
<div class="line"> <span class="comment">/* Report the error on the console. */</span></div>
<div class="line"> fprintf(stderr,</div>
<div class="line"> <span class="stringliteral">"app_id %s, thread context %p, error %d, message %s\n"</span>,</div>
<div class="line"> custom_handler->app_id, (<span class="keywordtype">void</span> *)session, error, message);</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">return</span> (0);</div>
<div class="line">}</div>
<div class="line"></div>
<div class="line"><span class="comment">/*</span></div>
<div class="line"><span class="comment"> * handle_wiredtiger_message --</span></div>
<div class="line"><span class="comment"> * Function to handle message callbacks from WiredTiger.</span></div>
<div class="line"><span class="comment"> */</span></div>
<div class="line"><span class="keywordtype">int</span></div>
<div class="line">handle_wiredtiger_message(</div>
<div class="line"> <a class="code" href="struct_w_t___e_v_e_n_t___h_a_n_d_l_e_r.html">WT_EVENT_HANDLER</a> *handler, <a class="code" href="struct_w_t___s_e_s_s_i_o_n.html">WT_SESSION</a> *session, <span class="keyword">const</span> <span class="keywordtype">char</span> *message)</div>
<div class="line">{</div>
<div class="line"> <span class="comment">/* Cast the handler back to our custom handler. */</span></div>
<div class="line"> printf(<span class="stringliteral">"app id %s, thread context %p, message %s\n"</span>,</div>
<div class="line"> ((CUSTOM_EVENT_HANDLER *)handler)->app_id,</div>
<div class="line"> (<span class="keywordtype">void</span> *)session, message);</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">return</span> (0);</div>
<div class="line">}</div>
</div><!-- fragment --><div class="fragment"><div class="line"> CUSTOM_EVENT_HANDLER event_handler;</div>
<div class="line"></div>
<div class="line"> event_handler.h.handle_error = handle_wiredtiger_error;</div>
<div class="line"> event_handler.h.handle_message = handle_wiredtiger_message;</div>
<div class="line"> <span class="comment">/* Set handlers to NULL to use the default handler. */</span></div>
<div class="line"> event_handler.h.handle_progress = NULL;</div>
<div class="line"> event_handler.h.handle_close = NULL;</div>
<div class="line"> event_handler.app_id = <span class="stringliteral">"example_event_handler"</span>;</div>
<div class="line"></div>
<div class="line"> ret = <a class="code" href="group__wt.html#ga9e6adae3fc6964ef837a62795c7840ed">wiredtiger_open</a>(home,</div>
<div class="line"> (<a class="code" href="struct_w_t___e_v_e_n_t___h_a_n_d_l_e_r.html">WT_EVENT_HANDLER</a> *)&event_handler, <span class="stringliteral">"create"</span>, &conn);</div>
</div><!-- fragment --></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.html">Writing WiredTiger applications</a></li>
<li class="footer">Copyright (c) 2008-2016 MongoDB, Inc. All rights reserved. Contact <a href="mailto:[email protected]">[email protected]</a> for more information.</li>
</ul>
</div>
</body>
</html>