summaryrefslogtreecommitdiffstats
path: root/group___g_a_p_l.html
blob: 604e15d565ecd3a4402fd2367bf55daef6e0a411 (plain)
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
<!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.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>HDF5: Group Access Properties</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>
<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:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
  $(document).ready(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>
   &#160;<span id="projectnumber">1.15.0.1fd82ab</span>
   </div>
   <div id="projectbrief">API Reference</div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.svg"
               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.svg" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'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:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('group___g_a_p_l.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">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="summary">
<a href="#func-members">Functions</a>  </div>
  <div class="headertitle">
<div class="title">Group Access Properties<div class="ingroups"><a class="el" href="group___h5_p.html">Property Lists (H5P)</a> &raquo; <a class="el" href="group___l_a_p_l.html">Link Access Properties</a></div></div>  </div>
</div><!--header-->
<div class="contents">
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>The functions in this section can be applied to group property lists.</p>
<p><a class="anchor" id="table_gapl_id"></a>
<table class="doxtable">
<caption border="1" style="background-color:whitesmoke;">Group access property list functions (H5P)</caption>
<tr>
<th>Function </th><th>Purpose  </th></tr>
<tr>
<td><a class="el" href="group___g_a_p_l.html#ga5bc0b1fc7e1e3961bf0b441e722949eb" title="Sets metadata I/O mode for read operations to be collective or independent (default)">H5Pset_all_coll_metadata_ops</a>/<a class="el" href="group___g_a_p_l.html#ga8792cbe7eeace1382f588ed12a92092a" title="Retrieves metadata read mode setting.">H5Pget_all_coll_metadata_ops</a> </td><td>Sets/gets metadata I/O mode for read operations  </td></tr>
</table>
</p>
<div id="dynsection-0" onclick="return toggleVisibility(this)" class="dynheader closed" style="cursor:pointer;">
  <img id="dynsection-0-trigger" src="closed.png" alt="+"/> Collaboration diagram for Group Access Properties:</div>
<div id="dynsection-0-summary" class="dynsummary" style="display:block;">
</div>
<div id="dynsection-0-content" class="dyncontent" style="display:none;">
<div class="center"><img src="group___g_a_p_l.png" border="0" usemap="#agroup______g__a__p__l" alt=""/></div>
<map name="agroup______g__a__p__l" id="agroup______g__a__p__l">
<area shape="rect" title=" " alt="" coords="221,5,401,31"/>
<area shape="rect" href="group___l_a_p_l.html" title=" " alt="" coords="5,5,173,31"/>
</map>
</div>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga5bc0b1fc7e1e3961bf0b441e722949eb"><td class="memItemLeft" align="right" valign="top"><a class="el" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group___g_a_p_l.html#ga5bc0b1fc7e1e3961bf0b441e722949eb">H5Pset_all_coll_metadata_ops</a> (<a class="el" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> plist_id, <a class="el" href="_h5public_8h.html#ad470b00eccd2115c707c02de5fa1120d">hbool_t</a> is_collective)</td></tr>
<tr class="memdesc:ga5bc0b1fc7e1e3961bf0b441e722949eb"><td class="mdescLeft">&#160;</td><td class="mdescRight">Sets metadata I/O mode for read operations to be collective or independent (default)  <a href="group___g_a_p_l.html#ga5bc0b1fc7e1e3961bf0b441e722949eb">More...</a><br /></td></tr>
<tr class="separator:ga5bc0b1fc7e1e3961bf0b441e722949eb"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga8792cbe7eeace1382f588ed12a92092a"><td class="memItemLeft" align="right" valign="top"><a class="el" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group___g_a_p_l.html#ga8792cbe7eeace1382f588ed12a92092a">H5Pget_all_coll_metadata_ops</a> (<a class="el" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> plist_id, <a class="el" href="_h5public_8h.html#ad470b00eccd2115c707c02de5fa1120d">hbool_t</a> *is_collective)</td></tr>
<tr class="memdesc:ga8792cbe7eeace1382f588ed12a92092a"><td class="mdescLeft">&#160;</td><td class="mdescRight">Retrieves metadata read mode setting.  <a href="group___g_a_p_l.html#ga8792cbe7eeace1382f588ed12a92092a">More...</a><br /></td></tr>
<tr class="separator:ga8792cbe7eeace1382f588ed12a92092a"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<h2 class="groupheader">Function Documentation</h2>
<a id="ga8792cbe7eeace1382f588ed12a92092a"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga8792cbe7eeace1382f588ed12a92092a">&#9670;&nbsp;</a></span>H5Pget_all_coll_metadata_ops()</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> H5Pget_all_coll_metadata_ops </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a>&#160;</td>
          <td class="paramname"><em>plist_id</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="_h5public_8h.html#ad470b00eccd2115c707c02de5fa1120d">hbool_t</a> *&#160;</td>
          <td class="paramname"><em>is_collective</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Retrieves metadata read mode setting. </p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">plist_id</td><td>File, group, dataset, datatype, link, or attribute access property list identifier </td></tr>
    <tr><td class="paramdir">[out]</td><td class="paramname">is_collective</td><td>Pointer to a buffer containing the Boolean value indicating whether metadata reads are collective (<code>&gt;0</code>) or independent (<code>0</code>). Default mode: Independent (<code>0</code>)</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="group___g_a_p_l.html#ga8792cbe7eeace1382f588ed12a92092a" title="Retrieves metadata read mode setting.">H5Pget_all_coll_metadata_ops()</a> retrieves the collective metadata read setting from the access property list <code>plist_id</code> into <code>is_collective</code>.</p>
<dl class="section see"><dt>See also</dt><dd><ul>
<li><a class="el" href="group___g_a_p_l.html#ga8792cbe7eeace1382f588ed12a92092a" title="Retrieves metadata read mode setting.">H5Pget_all_coll_metadata_ops()</a> </li>
<li><a class="el" href="group___f_a_p_l.html#gac83ab4e788a5b6e0d578f40ca67d8d00" title="Retrieves metadata write mode setting.">H5Pget_coll_metadata_write()</a> </li>
<li><a class="el" href="group___g_a_p_l.html#ga5bc0b1fc7e1e3961bf0b441e722949eb" title="Sets metadata I/O mode for read operations to be collective or independent (default)">H5Pset_all_coll_metadata_ops()</a> </li>
<li><a class="el" href="group___f_a_p_l.html#ga6380f9929cf42c8203813f7e72dde35c" title="Sets metadata write mode to be collective or independent (default)">H5Pset_coll_metadata_write()</a> </li>
<li><a class="el" href="maybe_metadata_reads.html">Functions with No Access Property List Parameter that May Generate Metadata Reads</a></li>
</ul>
</dd></dl>
<dl class="section since"><dt>Since</dt><dd>1.10.0 </dd></dl>

</div>
</div>
<a id="ga5bc0b1fc7e1e3961bf0b441e722949eb"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga5bc0b1fc7e1e3961bf0b441e722949eb">&#9670;&nbsp;</a></span>H5Pset_all_coll_metadata_ops()</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> H5Pset_all_coll_metadata_ops </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a>&#160;</td>
          <td class="paramname"><em>plist_id</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="_h5public_8h.html#ad470b00eccd2115c707c02de5fa1120d">hbool_t</a>&#160;</td>
          <td class="paramname"><em>is_collective</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Sets metadata I/O mode for read operations to be collective or independent (default) </p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">plist_id</td><td>File, group, dataset, datatype, link, or attribute access property list identifier </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">is_collective</td><td>Boolean value indicating whether metadata reads are collective (<code>1</code>) or independent (<code>0</code>). Default mode: Independent (<code>0</code>)</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="group___g_a_p_l.html#ga5bc0b1fc7e1e3961bf0b441e722949eb" title="Sets metadata I/O mode for read operations to be collective or independent (default)">H5Pset_all_coll_metadata_ops()</a> sets the metadata I/O mode for read operations in the access property list <code>plist_id</code>.</p>
<p>When engaging in parallel I/O, all metadata write operations must be collective. If <code>is_collective</code> is <code>1</code>, this property specifies that the HDF5 library will perform all metadata read operations collectively; if <code>is_collective</code> is <code>0</code>, such operations may be performed independently.</p>
<p>Users must be aware that several HDF5 operations can potentially issue metadata reads. These include opening a dataset, datatype, or group; reading an attribute; or issuing a <em>get info</em> call such as getting information for a group with <a class="el" href="group___h5_f.html#gae17036b3e36a8777328204e8bf073144">H5Fget_info()</a>. Collective I/O requirements must be kept in mind when issuing such calls in the context of parallel I/O.</p>
<p>If this property is collective on a file access property list that is used in creating or opening a file, then the HDF5 library will assume that all metadata read operations issued on that file identifier will be issued collectively from all ranks irrespective of the individual setting of a particular operation. If this assumption is not adhered to, corruption will be introduced in the metadata cache and HDF5's behavior will be undefined.</p>
<p>Alternatively, a user may wish to avoid setting this property globally on the file access property list, and individually set it on particular object access property lists (dataset, group, link, datatype, attribute access property lists) for certain operations. This will indicate that only the operations issued with such an access property list will be called collectively and other operations may potentially be called independently. There are, however, several HDF5 operations that can issue metadata reads but have no property list in their function signatures to allow passing the collective requirement property. For those operations, the only option is to set the global collective requirement property on the file access property list; otherwise the metadata reads that can be triggered from those operations will be done independently by each process.</p>
<p>Functions that do not accommodate an access property list but that might issue metadata reads are listed in <a class="el" href="maybe_metadata_reads.html">Functions with No Access Property List Parameter that May Generate Metadata Reads</a>.</p>
<dl class="section attention"><dt>Attention</dt><dd>As noted above, corruption will be introduced into the metadata cache and HDF5 library behavior will be undefined when both of the following conditions exist:<ul>
<li>A file is created or opened with a file access property list in which the collective metadata I/O property is set to <code>1</code>.</li>
<li>Any function is called that triggers an independent metadata read while the file remains open with that file access property list.</li>
</ul>
</dd>
<dd>
An approach that avoids this corruption risk is described above.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><ul>
<li><a class="el" href="group___g_a_p_l.html#ga8792cbe7eeace1382f588ed12a92092a" title="Retrieves metadata read mode setting.">H5Pget_all_coll_metadata_ops()</a> </li>
<li><a class="el" href="group___f_a_p_l.html#gac83ab4e788a5b6e0d578f40ca67d8d00" title="Retrieves metadata write mode setting.">H5Pget_coll_metadata_write()</a> </li>
<li><a class="el" href="group___g_a_p_l.html#ga5bc0b1fc7e1e3961bf0b441e722949eb" title="Sets metadata I/O mode for read operations to be collective or independent (default)">H5Pset_all_coll_metadata_ops()</a> </li>
<li><a class="el" href="group___f_a_p_l.html#ga6380f9929cf42c8203813f7e72dde35c" title="Sets metadata write mode to be collective or independent (default)">H5Pset_coll_metadata_write()</a> </li>
<li><a class="el" href="maybe_metadata_reads.html">Functions with No Access Property List Parameter that May Generate Metadata Reads</a></li>
</ul>
</dd></dl>
<dl class="section since"><dt>Since</dt><dd>1.10.0 </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.9.1 </li>
  </ul>
</div>
</body>
</html>