-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy patherrors.html
312 lines (311 loc) · 11 KB
/
errors.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
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
<!DOCTYPE html>
<html lang="en">
<head>
<link rel="stylesheet" type="text/css" href="styles/style.css">
<title>OpenFAM: A library for programming Fabric-Attached Memory</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
<header>
<h1>OpenFAM Reference Implementation</h1>
</header>
<section>
<nav>
<ul>
<li><a href="index.html">Home</a></li>
<li><a href="release_notes.html">Release Notes</a></li>
<li><a href="limitations.html">Design Choices</a></li>
<li><a href="errors.html">Exceptions and Error Codes</a></li>
<li><a href="services.html">Services</a></li>
<li><a href="config_files.html">Configuration Files</a></li>
</ul>
<hr>
Initialization and Finalization
<ul>
<li><a href="fam_initialize.html">fam_initialize</a></li>
<li><a href="fam_finalize.html">fam_finalize</a></li>
<li><a href="fam_abort.html">fam_abort</a></li>
</ul>
<hr>
Options & Query
<ul>
<li><a href="fam_list_options.html">fam_list_options</a></li>
<li><a href="fam_get_option.html">fam_get_option</a></li>
<li><a href="fam_lookup.html">fam_lookup</a></li>
<li><a href="fam_stat.html">fam_stat</a></li>
</ul>
<hr>
Memory Allocation
<ul>
<li><a href="fam_create_region.html">fam_create_region</a></li>
<li><a href="fam_destroy_region.html">fam_destroy_region</a></li>
<li><a href="fam_resize_region.html">fam_resize_region</a></li>
<li><a href="fam_allocate.html">fam_allocate</a></li>
<li><a href="fam_deallocate.html">fam_deallocate</a></li>
<li><a href="fam_change_permissions.html">fam_change_permissions</a></li>
<li><a href="fam_close.html">fam_close</a></li>
</ul>
<hr>
Memory Map
<ul>
<li><a href="fam_map.html">fam_map</a></li>
<li><a href="fam_unmap.html">fam_unmap</a></li>
</ul>
<hr>
Data Path Operations
<ul>
<li><a href="fam_get.html">fam_get</a></li>
<li><a href="fam_put.html">fam_put</a></li>
<li><a href="fam_gather.html">fam_gather</a></li>
<li><a href="fam_scatter.html">fam_scatter</a></li>
<li><a href="fam_copy.html">fam_copy</a></li>
<li><a href="fam_copy_wait.html">fam_copy_wait</a></li>
<li><a href="fam_backup.html">fam_backup</a></li>
<li><a href="fam_backup_wait.html">fam_backup_wait</a></li>
<li><a href="fam_restore.html">fam_restore</a></li>
<li><a href="fam_restore_wait.html">fam_restore_wait</a></li>
<li><a href="fam_delete_backup.html">fam_delete_backup</a></li>
<li><a href="fam_delete_backup_wait.html">fam_delete_backup_wait</a></li>
</ul>
<hr>
Atomics
<ul>
<li><a href="fam_set.html">fam_set</a></li>
<li><a href="fam_add.html">fam_add</a></li>
<li><a href="fam_subtract.html">fam_subtract</a></li>
<li><a href="fam_min.html">fam_min</a></li>
<li><a href="fam_max.html">fam_max</a></li>
<li><a href="fam_and.html">fam_and</a></li>
<li><a href="fam_or.html">fam_or</a></li>
<li><a href="fam_xor.html">fam_xor</a></li>
<li><a href="fam_fetch_TYPE.html">fam_fetch_TYPE</a></li>
<li><a href="fam_swap.html">fam_swap</a></li>
<li><a href="fam_compare_swap.html">fam_compare_swap</a></li>
<li><a href="fam_fetch_add.html">fam_fetch_add</a></li>
<li><a href="fam_fetch_subtract.html">fam_fetch_subtract</a></li>
<li><a href="fam_fetch_min.html">fam_fetch_min</a></li>
<li><a href="fam_fetch_and.html">fam_fetch_and</a></li>
<li><a href="fam_fetch_max.html">fam_fetch_max</a></li>
<li><a href="fam_fetch_or.html">fam_fetch_or</a></li>
<li><a href="fam_fetch_xor.html">fam_fetch_xor</a></li>
</ul>
<hr>
Ordering
<ul>
<li><a href="fam_barrier_all.html">fam_barrier_all</a></li>
<li><a href="fam_fence.html">fam_fence</a></li>
<li><a href="fam_quiet.html">fam_quiet</a></li>
<li><a href="fam_progress.html">fam_progress</a></li>
<li><a href="fam_context_open.html">fam_context_open</a></li>
<li><a href="fam_context_close.html">fam_context_close</a></li>
</ul>
<hr>
</nav>
<article>
<h1>Error handling</h1>
<p>Note that unlike C or C11, C++ provides native support for
exceptions. Hence the C++ API adopts the C++ style of handling and
reporting errors to its caller, using exceptions. Unlike the normal
C convention of returning integer values (0 for success and negative
values in case of failure), it uses C++ exceptions to indicate error
scenarios. All APIs return the expected output on success (or void
if no output is returned), and throw an exception on error. Instead
of checking the return value for errors as in C, the caller should
use try-catch blocks for handling errors.</p>
<p>The OpenFAM implementation defines a <code>Fam_Exception</code> class, which
is derived from C++ standard exception class. It also defines a list of individual error
numbers to categorize various types of failures. Individual error numbers identify specific
error conditions. The <code>Fam_Exception</code> object received by the caller in case of an
error contains a specific error number and an appropriate error
message string. The application can retrieve this information using
member functions, <code>fam_error()</code> and <code>fam_error_msg()/what()</code> and take
any necessary action. The currently defined exception and
error numbers are defined in Table 1 and Table 2</p>
<table>
<caption>Table 1: List of OpenFAM exceptions</caption>
<tbody>
<tr>
<th>Fam Exception Class</th>
<th>Description</th>
</tr>
<tr>
<td class="code">Fam_Exception</td>
<td>This exception class object is returned for all the error conditions.
It will contain specific error number. </td>
</tbody>
</table>
<br>
<table>
<caption>Table 2: List of OpenFAM error numbers</caption>
<tbody>
<tr>
<th>Fam Error</th>
<th>Description</th>
</tr>
<tr>
<td class="code">FAM_ERR_UNKNOWN</td>
<td>Unexpected or Unknown errors.</td>
</tr>
<tr>
<td class="code">FAM_ERR_NOPERM</td>
<td>Caller does not have access rights for the desired
operation.</td>
</tr>
<tr>
<td class="code">FAM_ERR_TIMEOUT</td>
<td>Blocking APIs reached retry/timeout limit.</td>
</tr>
<tr>
<td class="code">FAM_ERR_INVALID</td>
<td>APIs called with invalid options/arguments.</td>
</tr>
<tr>
<td class="code">FAM_ERR_LIBFABRIC</td>
<td>Libfabric API failure.</td>
</tr>
<tr>
<td class="code">FAM_ERR_SHM</td>
<td>Shared memory allocator error.</td>
</tr>
<tr>
<td class="code">FAM_ERR_NOT_CREATED</td>
<td>Data item or region creation in FAM failed.</td>
</tr>
<tr>
<td class="code">FAM_ERR_NOTFOUND</td>
<td>Data item or region not found in FAM.</td>
</tr>
<tr>
<td class="code">FAM_ERR_ALREADYEXIST</td>
<td>Data item or region already exists in FAM.</td>
</tr>
<tr>
<td class="code">FAM_ERR_ALLOCATOR</td>
<td>Allocator specific error</td>
</tr>
<tr>
<td class="code">FAM_ERR_RPC</td>
<td>Error from grpc layer.</td>
</tr>
<tr>
<td class="code">FAM_ERR_PMI</td>
<td>Runtime error.</td>
</tr>
<tr>
<td class="code">FAM_ERR_OUTOFRANGE</td>
<td>Data access out of range.</td>
</tr>
<tr>
<td class="code">FAM_ERR_NO_SPACE</td>
<td>No space in Region.</td>
</tr>
<tr>
<td class="code">FAM_ERR_NULLPTR</td>
<td>Null pointer access error.</td>
</tr>
<tr>
<td class="code">FAM_ERR_UNIMPL</td>
<td>Calling unimplemented functions/APIs.</td>
</tr>
<tr>
<td class="code">FAM_ERR_RESOURCE</td>
<td>Resource not available.</td>
</tr>
<tr>
<td class="code">FAM_ERR_INVALIDOP</td>
<td>Invalid operations</td>
</tr>
<tr>
<td class="code">FAM_ERR_RPC_CLIENT_NOTFOUND</td>
<td>RPC service not available.</td>
</tr>
<tr>
<td class="code">FAM_ERR_MEMSERV_LIST_EMPTY</td>
<td>Memory service not initialized.</td>
</tr>
<tr>
<td class="code">FAM_ERR_METADATA</td>
<td>Metadata service error.</td>
</tr>
<tr>
<td class="code">FAM_ERR_MEMORY</td>
<td>Memory service error.</td>
</tr>
<tr>
<td class="code">FAM_ERR_NAME_TOO_LONG</td>
<td>Region or Data item name too long.</td>
</tr>
<tr>
<td class="code">FAM_ERR_ATL_QUEUE_FULL</td>
<td>Atomic large transfer APIs queue full.</td>
</tr>
<tr>
<td class="code">FAM_ERR_ATL_QUEUE_INSERT</td>
<td>Atomic large transfer APIs queue insert error.</td>
</tr>
<tr>
<td class="code">FAM_ERR_ATL_NOT_ENABLED</td>
<td>Atomic large transfer APIs not enabled.</td>
</tr>
<tr>
<td class="code">FAM_ERR_ATL</td>
<td>Atomic large transfer API error.</td>
</tr>
<tr>
<td class="code">FAM_BACKUP_NOT_CREATED</td>
<td>Backup could not be created.</td>
</tr>
<tr>
<td class="code">FAM_BACKUP_NOTFOUND</td>
<td>Backup does not exist.</td>
</tr>
<tr>
<td class="code">FAM_BACKUP_INFO_NOTFOUND</td>
<td>Backup metadata is not found.</td>
</tr>
</tbody>
</table>
<p>The library contains both blocking and non-blocking
calls for most data path operations. In case of errors, all blocking
calls throw exceptions immediately. For example, a call to
<code>fam_put_blocking()</code> will either complete successfully, or throw <code>Fam_Exception</code> object
containing one of the following error numbers - <code>FAM_ERR_INVALID</code>,
<code>FAM_ERR_OUTOFRANGE</code>, <code>FAM_ERR_NOTFOUND</code> or
<code>FAM_ERR_TIMEOUT</code>. In general, the application should use the
normal try-catch block to handle exceptions:</p>
<pre> try {
fam_put_blocking();
} catch (Fam_Exception &e) {
// Exception handling code
}
</pre>
<p>However, the non-blocking calls are queued within the library,
and may not catch exceptions immediately. Depending on the
underlying error, a fam exception will be thrown immediately with specific error number,
while others may only be thrown during the next <code>fam_quiet()</code> call.
Thus the code may look like:</p>
<pre> try {
fam_put_nonblocking();
} catch (Fam_Exception &e) {
// handle error numbers(for example)
// FAM_ERR_INVALID, FAM_ERR_NOTFOUND, FAM_ERR_OUTOFRANGE, FAM_ERR_NOPERM
}
// ... Continue rest of the code ...
try {
fam_quiet();
} catch (Fam_Exception &e) {
// This exception may actually result from a previous
// fam_put_nonblocking() operation with following error number
// FAM_ERR_TIMEOUT, FAM_ERR_OUTOFRANGE, FAM_ERR_NOPERM
}
</pre>
<p>Note that uncaught exceptions will result in the application
being terminated.</p>
</article>
</section>
<footer>
<p>Copyright 2021-23, Hewlett Packard Enterprise Development Co, LLP</p>
</footer>
</body>
</html>