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
|
<!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.10.0"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>HDF5: Parallel</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" src="cookie.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>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(function() { init_search(); });
/* @license-end */
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="hdf5doxy.css" rel="stylesheet" type="text/css">
<!-- <link href="hdf5doxy.css" rel="stylesheet" type="text/css"/>
-->
<script type="text/javascript" src="hdf5_navtree_hacks.js"></script>
</head>
<body>
<div style="background:#FFDDDD;font-size:120%;text-align:center;margin:0;padding:5px">Please, help us to better serve our user community by answering the following short survey: <a href="https://www.hdfgroup.org/website-survey/">https://www.hdfgroup.org/website-survey/</a></div>
<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"><img alt="Logo" src="HDFG-logo.png"/></td>
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname"><a href="https://www.hdfgroup.org">HDF5</a>
 <span id="projectnumber">1.15.0.68e8c0e</span>
</div>
<div id="projectbrief">API Reference</div>
</td>
<td> <div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<span id="MSearchSelect" onmouseover="return searchBox.OnSearchSelectShow()" onmouseout="return searchBox.OnSearchSelectHide()"> </span>
<input type="text" id="MSearchField" value="" placeholder="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.svg" alt=""/></a>
</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.10.0 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
</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">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(function(){initNavTree('group___p_h5_f.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- 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">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div class="header">
<div class="summary">
<a href="#func-members">Functions</a> </div>
<div class="headertitle"><div class="title">Parallel<div class="ingroups"><a class="el" href="group___h5_f.html">Files (H5F)</a></div></div></div>
</div><!--header-->
<div class="contents">
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="func-members" name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga087dbbf37cb5c451ae8a6f66b227f0fc" id="r_ga087dbbf37cb5c451ae8a6f66b227f0fc"><td class="memItemLeft" align="right" valign="top"><a class="el" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="#ga087dbbf37cb5c451ae8a6f66b227f0fc">H5Fset_mpi_atomicity</a> (<a class="el" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> file_id, <a class="el" href="_h5public_8h.html#ad470b00eccd2115c707c02de5fa1120d">hbool_t</a> flag)</td></tr>
<tr class="memdesc:ga087dbbf37cb5c451ae8a6f66b227f0fc"><td class="mdescLeft"> </td><td class="mdescRight">Sets the MPI atomicity mode. <br /></td></tr>
<tr class="separator:ga087dbbf37cb5c451ae8a6f66b227f0fc"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga849316b77788799fecb321a87d987ade" id="r_ga849316b77788799fecb321a87d987ade"><td class="memItemLeft" align="right" valign="top"><a class="el" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="#ga849316b77788799fecb321a87d987ade">H5Fget_mpi_atomicity</a> (<a class="el" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> file_id, <a class="el" href="_h5public_8h.html#ad470b00eccd2115c707c02de5fa1120d">hbool_t</a> *flag)</td></tr>
<tr class="memdesc:ga849316b77788799fecb321a87d987ade"><td class="mdescLeft"> </td><td class="mdescRight">Retrieves the atomicity mode in use. <br /></td></tr>
<tr class="separator:ga849316b77788799fecb321a87d987ade"><td class="memSeparator" colspan="2"> </td></tr>
</table>
<h2 class="groupheader">Function Documentation</h2>
<a id="ga849316b77788799fecb321a87d987ade" name="ga849316b77788799fecb321a87d987ade"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga849316b77788799fecb321a87d987ade">◆ </a></span>H5Fget_mpi_atomicity()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> H5Fget_mpi_atomicity </td>
<td>(</td>
<td class="paramtype"><a class="el" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a></td> <td class="paramname"><span class="paramname"><em>file_id</em>, </span></td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="_h5public_8h.html#ad470b00eccd2115c707c02de5fa1120d">hbool_t</a> *</td> <td class="paramname"><span class="paramname"><em>flag</em></span> )</td>
</tr>
</table>
</div><div class="memdoc">
<p>Retrieves the atomicity mode in use. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">file_id</td><td>File identifier </td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">flag</td><td>Logical flag for atomicity setting. Valid values are: <ul>
<li>1 – MPI file access is set to atomic mode. </li>
<li>0 – MPI file access is set to nonatomic mode. </li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns a non-negative value if successful; otherwise, returns a negative value.</dd></dl>
<p><a class="el" href="#ga849316b77788799fecb321a87d987ade" title="Retrieves the atomicity mode in use.">H5Fget_mpi_atomicity()</a> retrieves the current consistency semantics mode for data access for the file <code>file_id</code>.</p>
<p>Upon successful return, <code>flag</code> will be set to <code>1</code> if file access is set to atomic mode and <code>0</code> if file access is set to nonatomic mode.</p>
<dl class="section see"><dt>See also</dt><dd><a href="https://portal.hdfgroup.org/display/HDF5/Enabling+a+Strict+Consistency+Semantics+Model+in+Parallel+HDF5">Enabling a Strict Consistency Semantics Model in Parallel HDF5</a></dd></dl>
<dl class="section since"><dt>Since</dt><dd>1.8.9 </dd></dl>
</div>
</div>
<a id="ga087dbbf37cb5c451ae8a6f66b227f0fc" name="ga087dbbf37cb5c451ae8a6f66b227f0fc"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga087dbbf37cb5c451ae8a6f66b227f0fc">◆ </a></span>H5Fset_mpi_atomicity()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> H5Fset_mpi_atomicity </td>
<td>(</td>
<td class="paramtype"><a class="el" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a></td> <td class="paramname"><span class="paramname"><em>file_id</em>, </span></td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="_h5public_8h.html#ad470b00eccd2115c707c02de5fa1120d">hbool_t</a></td> <td class="paramname"><span class="paramname"><em>flag</em></span> )</td>
</tr>
</table>
</div><div class="memdoc">
<p>Sets the MPI atomicity mode. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">file_id</td><td>File identifier </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">flag</td><td>Logical flag for atomicity setting. Valid values are: <ul>
<li><code>1</code> – Sets MPI file access to atomic mode. </li>
<li><code>0</code> – Sets MPI file access to nonatomic mode. </li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns a non-negative value if successful; otherwise, returns a negative value.</dd></dl>
<dl class="section user"><dt>Motivation</dt><dd><a class="el" href="#ga087dbbf37cb5c451ae8a6f66b227f0fc" title="Sets the MPI atomicity mode.">H5Fset_mpi_atomicity()</a> is applicable only in parallel environments using MPI I/O. The function is one of the tools used to ensure sequential consistency. This means that a set of operations will behave as though they were performed in a serial order consistent with the program order.</dd></dl>
<p><a class="el" href="#ga087dbbf37cb5c451ae8a6f66b227f0fc" title="Sets the MPI atomicity mode.">H5Fset_mpi_atomicity()</a> sets MPI consistency semantics for data access to the file, <code>file_id</code>.</p>
<p>If <code>flag</code> is set to <code>1</code>, all file access operations will appear atomic, guaranteeing sequential consistency. If <code>flag</code> is set to <code>0</code>, enforcement of atomic file access will be turned off.</p>
<p><a class="el" href="#ga087dbbf37cb5c451ae8a6f66b227f0fc" title="Sets the MPI atomicity mode.">H5Fset_mpi_atomicity()</a> is a collective function and all participating processes must pass the same values for <code>file_id</code> and <code>flag</code>.</p>
<p>This function is available only when the HDF5 library is configured with parallel support (<code>–enable-parallel | HDF5_ENABLE_PARALLEL</code>). It is useful only when used with the <a class="el" href="_h5_f_dmpio_8h.html#a7a231bc1d78744088a4e1d297284cabf">H5FD_MPIO</a> driver (see <a class="el" href="group___f_a_p_l.html#gaa0204810c1fea1667d62cf7c176416ff" title="Stores MPI IO communicator information to the file access property list.">H5Pset_fapl_mpio()</a>). </p>
<dl class="section attention"><dt>Attention</dt><dd><p class="startdd"><a class="el" href="#ga087dbbf37cb5c451ae8a6f66b227f0fc" title="Sets the MPI atomicity mode.">H5Fset_mpi_atomicity()</a> calls <code>MPI_File_set_atomicity</code> underneath and is not supported if the execution platform does not support <code>MPI_File_set_atomicity</code>. When it is supported and used, the performance of data access operations may drop significantly.</p>
<p class="enddd">In certain scenarios, even when <code>MPI_File_set_atomicity</code> is supported, setting atomicity with <a class="el" href="#ga087dbbf37cb5c451ae8a6f66b227f0fc" title="Sets the MPI atomicity mode.">H5Fset_mpi_atomicity()</a> and <code>flag</code> set to 1 does not always yield strictly atomic updates. For example, some <a class="el" href="group___h5_d.html#ga98f44998b67587662af8b0d8a0a75906" title="Writes raw data from a buffer to a dataset.">H5Dwrite()</a> calls translate to multiple <code>MPI_File_write_at</code> calls. This happens in all cases where the high-level file access routine translates to multiple lower level file access routines. The following scenarios will raise this issue: </p><ul>
<li>Non-contiguous file access using independent I/O </li>
<li>Partial collective I/O using chunked access </li>
<li>Collective I/O using filters or when data conversion is required</li>
</ul>
<p>This issue arises because MPI atomicity is a matter of MPI file access operations rather than HDF5 access operations. But the user is normally seeking atomicity at the HDF5 level. To accomplish this, the application must set a barrier after a write, <a class="el" href="group___h5_d.html#ga98f44998b67587662af8b0d8a0a75906" title="Writes raw data from a buffer to a dataset.">H5Dwrite()</a>, but before the next read, <a class="el" href="group___h5_d.html#ga8287d5a7be7b8e55ffeff68f7d26811c" title="Reads raw data from a dataset into a provided buffer.">H5Dread()</a>, in addition to calling <a class="el" href="#ga087dbbf37cb5c451ae8a6f66b227f0fc" title="Sets the MPI atomicity mode.">H5Fset_mpi_atomicity()</a>.The barrier will guarantee that all underlying write operations execute atomically before the read operations starts. This ensures additional ordering semantics and will normally produce the desired behavior. </p>
</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a href="https://portal.hdfgroup.org/display/HDF5/Enabling+a+Strict+Consistency+Semantics+Model+in+Parallel+HDF5">Enabling a Strict Consistency Semantics Model in Parallel HDF5</a></dd></dl>
<dl class="section since"><dt>Since</dt><dd>1.8.9 </dd></dl>
</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.10.0 </li>
</ul>
</div>
</body>
</html>
|
